Best practices for Sink connector

This page collects recommendations and operational practices for running the Sink connector. Each recommendation explains the trade-offs so you can decide whether it applies to your use case.

Choosing a sink strategy

The Sink connector supports four strategies for turning incoming Kafka messages into writes to Neo4j: Change Data Capture, Pattern, CUD, and Cypher. Use the following decision guide to pick between them.

Strategy Use it when

Strategy	Use it when
Change Data Capture	The messages are produced by a Neo4j Source connector configured with the CDC strategy, or by the deprecated Neo4j Streams plugin. This is the strategy to reach for when you’re replicating one Neo4j database into another and don’t control the message format yourself, since it’s generated for you.
Pattern	The messages come from an arbitrary producer, but each topic’s messages consistently map to one node or relationship shape. A declarative Cypher-like pattern is enough to extract that shape, without writing any Cypher yourself. This is a good default for straightforward event-to-graph mappings.
CUD	The messages come from an arbitrary producer that can emit explicit `create`/`update`/`merge`/`delete` JSON commands, or you need more than one operation type multiplexed onto the same topic. Prefer this over Pattern when a single topic needs to express more than one kind of write.
Cypher	The write logic doesn’t fit the conventions of the other three strategies, for example conditional logic, multiple entities per message with custom relationships between them, or aggregation across message fields. This is the escape hatch: full control over the write, at the cost of writing and maintaining the Cypher yourself.

Change Data Capture

The messages are produced by a Neo4j Source connector configured with the CDC strategy, or by the deprecated Neo4j Streams plugin. This is the strategy to reach for when you’re replicating one Neo4j database into another and don’t control the message format yourself, since it’s generated for you.

Pattern

The messages come from an arbitrary producer, but each topic’s messages consistently map to one node or relationship shape. A declarative Cypher-like pattern is enough to extract that shape, without writing any Cypher yourself. This is a good default for straightforward event-to-graph mappings.

CUD

The messages come from an arbitrary producer that can emit explicit create/update/merge/delete JSON commands, or you need more than one operation type multiplexed onto the same topic. Prefer this over Pattern when a single topic needs to express more than one kind of write.

Cypher

The write logic doesn’t fit the conventions of the other three strategies, for example conditional logic, multiple entities per message with custom relationships between them, or aggregation across message fields. This is the escape hatch: full control over the write, at the cost of writing and maintaining the Cypher yourself.

Start with Pattern or CUD if your message format is flexible. Reach for Cypher only once you hit something those two conventions can’t express, rather than starting there by default.