Event selectors

This feature has been released as a public beta in AuraDB Enterprise October Release and Neo4j Enterprise Edition 5.13 and breaking changes are likely to be introduced before it is made generally available (GA).

The db.cdc.query procedure supports filtering the returned changes using user-provided selectors.

Filtering for entities

A selector to match both nodes and relationships
{
  select: "e", (1)
  operation: "c", (2)
  changesTo: ["name", "title"] (3)
}

All fields except for select are optional.

1 Select changes on all entities. Other valid values are "n" for nodes and "r" for relationships.
2 Select changes which created entities. Other valid values are "u" for updates and "d" for deletions.
3 Select changes which affected all of the provided properties.

Filtering for nodes

A selector to match nodes only
{
  select: "n", (1)
  elementId: "4:b7e35973-0aff-42fa-873b-5de31868cb4a:1", (2)
  key: { (3)
    property: "value",
    otherProperty: "value"
  },
  labels: ["Person", "Actor"], (4)
  operation: "c", (5)
  changesTo: ["name", "lastName"] (6)
}

All fields except for select are optional.

1 Select changes on nodes. Other valid values are "e" for all entities and "r" for relationships.
2 Select changes on the node with this elementId.
3 Select changes on nodes with matching key properties. Key matching is only possible when key constraints are defined on the node, see The role of elementIds and key properties for details.
4 Select changes on nodes which have all of the specified labels either before or after the change.
5 Select changes which created nodes. Other valid values are "u" for updates and "d" for deletions.
6 Select changes which affect all of the specified properties.

Filtering for relationships

A selector to match relationships only
{
  select: "r", (1)
  elementId: "4:b7e35973-0aff-42fa-873b-5de31868cb4a:1", (2)
  type: "ACTED_IN", (3)
  key: { (4)
    property: "value",
    otherProperty: "value"
  },
  start: { (5)
    select: "n", (6)
    elementId: "4:b7e35973-0aff-42fa-873b-5de31868cb4a:1", (7)
    key: { (8)
      userId: "1001",
      name: "John"
    },
    labels: ["Person", "Actor"] (9)
  },
  end:{ (10)
    select: "n",
    elementId: "5:b7e35973-0aff-42fa-873b-5de31878ab4a:3",
    key: {
      title: "Matrix"
    },
    labels: ["Movie"]
  },
  operation: "c", (11)
  changesTo: ["name", "lastName"] (12)
}

All fields except for select are optional.

1 Select changes on relationships. Other valid values are "e" for all entities and "n" for nodes.
2 Select changes on the relationship with this elementId.
3 Select changes on relationships with this type.
4 Select changes on relationships with matching key properties. Key matching is only possible when key constraints are defined on the node, see The role of elementIds and key properties for details.
5 Select changes on relationships with a start node matching this node selector. Note that operation and changesTo are not valid inside these node selectors.
6 Optionally specify that this is a node selector. Specifying "r" or "e" here will cause an error.
7 Select relationships where the start node has this elementId.
8 Select relationships where the start node has these key properties. Key matching is only possible when key constraints are defined on the node, see The role of elementIds and key properties for details.
9 Select relationships where the start node has these labels either before or after the change.
10 Select relationships with end nodes matching this node selector. Same schema as start.
11 Select changes which created relationships. Other valid values are "u" for updates and "d" for deletions.
12 Select changes where all specified properties are affected.

The relationship start and end node selectors mostly satisfy the regular node selector schema. The only exception is that you cannot specify operation and changesTo fields inside relationship start and end node selectors.

Filtering by metadata

All of the previous selectors can be combined with metadata filtering.

Additional filtering for metadata values
{
  select: "e", (1)
  authenticatedUser: "alice", (2)
  executingUser: "bob", (3)
  txMetadata: { (4)
    app: "people",
    client: 42
  },
  //...
}

All fields except for select are optional.

1 May also be applied to "n" and "r" selectors.
2 Select changes where the authenticated user matches the value provided.
3 Select changes where the executing user matches the value provided.
4 Select changes where the transactional metadata key/values match the provided entries.

Combining selectors

The more specific a selector is, the fewer changes are returned. For example, specifying both name and surname as a changesTo value only returns changes where both name and surname properties have changed within the same transaction.

Query changes updating both name and surname properties
CALL db.cdc.query($previousChangeId, [
    {select: "n", changesTo: ["name", "surname"]}
])

In order to extract changes for either name or surname properties, specify two separate selectors:

Query changes updating either name or surname properties
CALL db.cdc.query($previousChangeId, [
    {select: "n", changesTo: ["name"]},
    {select: "n", changesTo: ["surname"]}
])