Content-based routing
By default, Debezium streams all of the change events that it reads from a table to a single static topic. However, there might be situations in which you might want to reroute selected events to other topics, based on the event content. The process of routing messages based on their content is described in the Content-based routing messaging pattern. To apply this pattern in Debezium, you use the content-based routing single message transform (SMT) to write expressions that are evaluated for each event. Depending how an event is evaluated, the SMT either routes the event message to the original destination topic, or reroutes it to the topic that you specify in the expression.
|
The content-based routing SMT is under active development. The structure of the emitted message or other details might change as development progresses. |
While it is possible to use Java to create a custom SMT to encode routing logic, using a custom-coded SMT has its drawbacks. For example:
-
It is necessary to compile the transformation up front and deploy it to Kafka Connect.
-
Every change needs code recompilation and redeployment, leading to inflexible operations.
The content-based routing SMT supports scripting languages that integrate with JSR 223 (Scripting for the Java™ Platform).
Debezium does not come with any implementations of the JSR 223 API. To use an expression language with Debezium, you must download the JSR 223 script engine implementation for the language, and add to your Debezium connector plug-in directories, along any other JAR files used by the language implementation. For example, for Groovy 3, you can download its JSR 223 implementation from https://groovy-lang.org/. The JSR 223 implementation for GraalVM JavaScript is available at https://github.com/graalvm/graaljs.
Set up
For security reasons, the content-based routing SMT is not included with the Debezium connector archives.
Instead, it is provided in a separate artifact, debezium-scripting-1.2.5.Final.tar.gz.
To use the content-based routing SMT with a Debezium connector plug-in, you must explicitly add the SMT artifact to your Kafka Connect environment.
| After the routing SMT is present in a Kafka Connect instance, any user who is allowed to add a connector to the instance can run scripting expressions. To ensure that scripting expressions can be run only by authorized users, be sure to secure the Kafka Connect instance and its configuration interface before you add the routing SMT. |
With Zookeeper, Kafka, Kafka Connect, and one or more Debezium connectors installed, the remaining tasks to install the filter SMT are:
-
Download the scripting SMT archive
-
Extract the contents of the archive into the Debezium plug-in directories of your Kafka Connect environment.
-
Obtain a JSR-223 script engine implementation and add its contents to the Debezium plug-in directories of your Kafka Connect environment.
-
Restart your Kafka Connect process to pick up the new JAR files.
Example: Basic configuration
To configure a Debezium connector to route change event records based on the event content, you configure the ContentBasedRouter SMT in the Kafka Connect configuration for the connector.
Configuration of the content-based routing SMT requires you to specify a regular expression that defines the filtering criteria. In the configuration, you create a regular expression that defines routing criteria. The expression defines a pattern for evaluating event records. It also specifies the name of a destination topic where events that match the pattern are routed. The pattern that you specify might designate an event type, such as a table insert, update, or delete operation. You might also define a pattern that matches a value in a specific column or row.
For example, to reroute all update (u) records to an updates topic, you might add the following configuration to your connector configuration:
...
transforms=route
transforms.route.type=io.debezium.transforms.ContentBasedRouter
transforms.route.language=jsr223.groovy
transforms.route.topic.expression=value.op == 'u' ? 'updates' : null
...The preceding example specifies the use of the Groovy expression language.
Records that do not match the pattern are routed to the default topic.
Variables for use in content-based routing expressions
Debezium binds certain variables into the evaluation context for the SMT. When you create expressions to specify conditions to control the routing destination, the SMT can look up and interpret the values of these variables to evaluate conditions in an expression.
The following table lists the variables that Debezium binds into the evaluation context for the content-based routing SMT:
| Name | Description | Type |
|---|---|---|
|
A key of the message. |
|
|
A value of the message. |
|
|
Schema of the message key. |
|
|
Schema of the message value. |
|
|
Name of the target topic. |
String |
|
A Java map of message headers. The key field is the header name.
The
|
|
An expression can invoke arbitrary methods on its variables.
Expressions should resolve to a Boolean value that determines how the SMT dispositions the message.
When the routing condition in an expression evaluates to true, the message is retained.
When the routing condition evaluates to false, the message is removed.
Expressions should not result in any side-effects. That is, they should not modify any variables that they pass.
Language specifics
The way that you express content-based routing conditions depends on the scripting language that you use.
For example, as shown in the basic configuration example, when you use Groovy as the expression language,
the following expression reroutes all update (u) records to the updates topic, while routing other records to the default topic:
value.op == 'u' ? 'updates' : nullOther languages use different methods to express the same condition.
|
The Debezium MongoDB connector emits the You could also take the approach of using a JSON parser within the expression.
For example, if you use Groovy as the expression language, add the |
When you use JavaScript as the expression language, you can call the Struct#get() method to specify the content-based routing condition, as in the following example:
value.get('op') == 'u' ? 'updates' : nullWhen you create content-based routing conditions by using JavaScript with Graal.js, you use an approach that is similar to the one use with Groovy. For example:
value.op == 'u' ? 'updates' : nullConfiguration options
Property |
Default |
Description |
An optional regular expression that evaluates the name of the destination topic for an event to determine whether to apply the condition logic.
If the name of the destination topic matches the value in |
||
The language in which the expression is written. Must begin with |
||
The expression to be evaluated for every message. Must evaluate to a |
||
|
Specifies how the transformation handles
|