84ab0dc3d2
* DBZ-6201: Add docs for HeaderToValue SMT --------- Co-authored-by: roldanbob <broldan@redhat.com>
177 lines
5.6 KiB
Plaintext
177 lines
5.6 KiB
Plaintext
:page-aliases: configuration/header-to-value.adoc
|
|
// Category: debezium-using
|
|
// Type: assembly
|
|
// ModuleID: converting-message-headers-to-event-record-values
|
|
// Title: Converting message headers into event record values
|
|
[id="header-to-value"]
|
|
= HeaderToValue
|
|
|
|
:toc:
|
|
:toc-placement: macro
|
|
:linkattrs:
|
|
:icons: font
|
|
:source-highlighter: highlight.js
|
|
|
|
toc::[]
|
|
|
|
The `HeaderToValue` SMT extracts specified header fields from event records, and then copies or moves the header fields to values in the event record.
|
|
The `move` options removes the fields from the header entirely before adding them as values in the payload.
|
|
You can configure the SMT to manipulate multiple headers in the original message.
|
|
You can use dot notation to specify a node within the payload in which you want to nest the header field.
|
|
For more information about configuring the SMT, see the following xref:example-header-to-value[example].
|
|
|
|
// Type: concept
|
|
// Title: Example: Basic configuration of the {prodname} `HeaderToValue` SMT
|
|
// ModuleID: basic-configuration-of-the-debezium-header-to-value-smt
|
|
[[example-header-to-value]]
|
|
== Example
|
|
|
|
To extract message headers in an event record into the record value, configure the `HeaderToValue` SMT in the Kafka Connect configuration for a connector.
|
|
You can configure the transformation to either remove the original headers or to copy them.
|
|
To remove header fields from the record, configure the SMT to use the `move` operations.
|
|
To retain the header fields in the original record, configure the SMT to use the `copy` operation.
|
|
For example, to remove the headers `event_timestamp` and `key` from an event message, add the following lines to your connector configuration:
|
|
|
|
[source]
|
|
----
|
|
transforms=moveHeadersToValue
|
|
transforms.moveHeadersToValue.type=io.debezium.transforms.HeaderToValue
|
|
transforms.moveHeadersToValue.headers=event_timestamp,key
|
|
transforms.moveHeadersToValue.fields=timestamp,source.id
|
|
transforms.moveHeadersToValue.operation=move
|
|
----
|
|
|
|
The following example shows the headers and values of an event record before and after the transformation is applied.
|
|
|
|
.Effect of applying the `HeaderToValue` SMT
|
|
====
|
|
Event record before it is processed by the `HeaderToValue` transformation::
|
|
|
|
Header before the SMT processes the event record:::
|
|
+
|
|
[source]
|
|
----
|
|
{
|
|
"header_x": 0,
|
|
"event_timestamp": 1626102708861,
|
|
"key": 100,
|
|
}
|
|
----
|
|
|
|
Value before the SMT processes the event record:::
|
|
+
|
|
[source]
|
|
----
|
|
{
|
|
"before": null,
|
|
"after": {
|
|
"id": 1,
|
|
"first_name": "Anne",
|
|
"last_name": "Kretchmar",
|
|
"email": "annek@noanswer.org"
|
|
},
|
|
"source": {
|
|
"version": "2.1.3.Final",
|
|
"connector": "postgresql",
|
|
"name": "PostgreSQL_server",
|
|
"ts_ms": 1559033904863,
|
|
"snapshot": true,
|
|
"db": "postgres",
|
|
"sequence": "[\"24023119\",\"24023128\"]"
|
|
"schema": "public",
|
|
"table": "customers",
|
|
"txId": 555,
|
|
"lsn": 24023128,
|
|
"xmin": null
|
|
},
|
|
"op": "c",
|
|
"ts_ms": 1559033904863
|
|
}
|
|
----
|
|
|
|
Event record after it is processed by the `HeaderToValue` transformation::
|
|
|
|
Header after the SMT removes the specified field:::
|
|
+
|
|
[source, json]
|
|
----
|
|
{
|
|
"header_x": 0
|
|
}
|
|
----
|
|
Value after the SMT moves header fields into the value:::
|
|
+
|
|
[source, json]
|
|
----
|
|
{
|
|
"before": null,
|
|
"after": {
|
|
"id": 1,
|
|
"first_name": "Anne",
|
|
"last_name": "Kretchmar",
|
|
"email": "annek@noanswer.org"
|
|
},
|
|
"source": {
|
|
"version": "2.1.3.Final",
|
|
"connector": "postgresql",
|
|
"name": "PostgreSQL_server",
|
|
"ts_ms": 1559033904863,
|
|
"snapshot": true,
|
|
"db": "postgres",
|
|
"sequence": "[\"24023119\",\"24023128\"]"
|
|
"schema": "public",
|
|
"table": "customers",
|
|
"txId": 555,
|
|
"lsn": 24023128,
|
|
"xmin": null,
|
|
"id": 100
|
|
},
|
|
"op": "c",
|
|
"ts_ms": 1559033904863,
|
|
"event_timestamp": 1626102708861
|
|
}
|
|
----
|
|
====
|
|
|
|
// Type: reference
|
|
// ModuleID: options-for-configuring-the-header-to-value-transformation
|
|
// Title: Options for configuring the `HeaderToValue` transformation
|
|
[[header-to-value-configuration-options]]
|
|
== Configuration options
|
|
|
|
The following table lists the configuration options that you can use with the `HeaderToValue` SMT.
|
|
|
|
.HeaderToValue SMT configuration options
|
|
[cols="14%a,40%a,10%a, 16%a, 16%a, 10%a"]
|
|
|===
|
|
|Property
|
|
|Description
|
|
|Type
|
|
|Default
|
|
|Valid Values
|
|
|Importance
|
|
|
|
|[[header-to-value-headers]]<<header-to-value-headers, `headers`>>
|
|
|A comma-separated list of header names in the record whose values are to be copied or moved to the record value.
|
|
|list
|
|
|No default value
|
|
|non-empty list
|
|
|high
|
|
|[[header-to-value-fields]]<<header-to-value-fields, `fields`>>
|
|
|A comma-separated list of field names, in the same order as the header names listed in the `headers` configuration property.
|
|
Use dot notation to instruct the SMT to nest fields within specific nodes of the message payload.
|
|
For information about how to configure the SMT to use dot notation, see the xref:example-header-to-value[example] that appears earlier in this topic.
|
|
|list
|
|
|No default value
|
|
|non-empty list
|
|
|high
|
|
|[[header-to-value-operation]]<<header-to-value-operation, `operation`>>
|
|
|Specifies one of the following options:
|
|
`move`:: The SMT moves header fields to values in the event record, and removes the fields from the header.
|
|
`copy`:: The SMT copies header field to values in the event record, and retains the original header fields.
|
|
|string
|
|
|No default value
|
|
|move or copy
|
|
|high
|
|
|===
|