diff --git a/modules/ROOT/pages/subscriptions/customize-cdc.adoc b/modules/ROOT/pages/subscriptions/customize-cdc.adoc index e54bf6dc..a3c6e479 100644 --- a/modules/ROOT/pages/subscriptions/customize-cdc.adoc +++ b/modules/ROOT/pages/subscriptions/customize-cdc.adoc @@ -3,7 +3,7 @@ :page-aliases: subscriptions/plugins/index.adoc, subscriptions/plugins/amqp.adoc, subscriptions/plugins/single-instance.adoc :description: This page describes how to customize the behavior of subscriptions. -GraphQL subscriptions to Neo4j use [Change Data Capture](https://neo4j.com/docs/cdc/current/) (CDC). +GraphQL subscriptions to Neo4j use link:https://neo4j.com/docs/cdc/current/[Change Data Capture] (CDC). Its behavior can be configured by passing an instance of `Neo4jGraphQLSubscriptionsCDCEngine`. == Neo4jGraphQLSubscriptionsCDCEngine @@ -44,3 +44,50 @@ const neoSchema = new Neo4jGraphQL({ }); ---- +== Listen to subscription events + +The class `Neo4jGraphQLSubscriptionsCDCEngine` exposes the `events` property, an instance of link:https://nodejs.org/api/events.html#class-eventemitter[EventEmitter], which emits an event for each CDC event. +This is useful for scenarios such as forwarding CDC events to an external queue for processing. + +[NOTE] +==== +It is generally recommended to link:https://neo4j.com/docs/cdc/current/[use CDC directly], outside of the GraphQL library, for event listening. +==== + +To listen to GraphQL subscription events, use the `.on` method on the `events` property: + +[source, javascript, indent=0] +---- +engine.events.on("create", (payload) => { + console.log("Node Created!", payload) +}); +---- + +The following CDC-triggered events can be listened to: + +* `create`: A node has been created. +* `update`: A node has been updated. +* `delete`: A node has been deleted. + +=== Event payload + +Each event includes a JSON payload with event details: + +* `event`: The event type, matching the listener event name. +* `typename`: The GraphQL type name. +* `properties`: Contains `old` and `new` objects representing node properties before and after the mutation. These may be `undefined` if the node did not exist before or after the mutation. +* `id`: The node ID (not exposed through the GraphQL API). +* `timestamp`: The timestamp of the mutation that triggered the event. + +For example, a node creation event would look like this: + +[source, javascript, indent=0] +---- +{ + event: 'create', + typename: 'Movie', + properties: { old: undefined, new: { title: 'The Matrix' } }, + id: '4:70bade62-2121-4808-9348-3ab77859e164:510', + timestamp: 1739286926054 +} +----