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).

cdc.query procedure support filtering returned changes using user provided selectors.

Selector schema

Full schema for selectors is defined below. Each selector can contain a number of supported filters, where each filter needs to be satisfied by the change event to be included in the output.

Selecting entities

You can construct selectors that can both match 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 are creating entities. Other valid values are "u" for entity updates and "d" for entity deletions.
3 Select changes which affected all of the provided properties.

Selecting nodes

You can construct selectors that can only match nodes.

{
  "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 element id. See Cypher Manual → Functions → Scalar functions for more information on element ids.
3 Select changes on nodes with matching key properties. Key matching is only possible when specific constraints are defined on the node, see Capturing key properties for details.
4 Select changes on nodes which have all of the specified labels.
5 Select changes which are creating nodes. Other valid values are "u" for node updates and "d" for node deletions.
6 Select changes which affect all of the specified properties.

Selecting relationships

You can construct selectors that can only match relationships.

{
  "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 element id. See Cypher Manual → Functions → Scalar functions for more information on element ids.
3 Select changes on relationships with this type.
4 Select changes on relationships with matching key properties. Key matching is only possible when specific constraints are defined on the relationship, see Capturing 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 element id. See Cypher Manual → Functions → Scalar functions for more information on element ids.
8 Select relationships where the start node has these key properties. Key matching is only possible when specific constraints are defined on the node, see Capturing key properties for details.
9 Select relationships where the start node has these labels.
10 Select relationships with end nodes matching this node selector. Same schema as start.
11 Select changes which are creating relationships. Other valid values are "u" for relationship updates and "d" for relationship 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.

Metadata selectors

All of the above selectors also support matching based on the metadata associated with a change.

{
  "select": "e", (1)
  "authenticatedUser": "alice", (2)
  "executingUser": "bob", (3)
  "txMetadata": { (4)
    "property": "value",
    "otherProperty": 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 cdc.query($previousChangeId, [{select:"n", changesTo:["name", "surname"]}])

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

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