graflo.db.cypher¶
Shared Cypher query fragments (no drivers; safe string builders only).
Modules:
| Name | Description |
|---|---|
bulk |
Create-only Cypher for a bulk load, and the counts that verify it. |
delete |
Cypher statements that remove nodes and relationships by their keys or scope. |
direction |
Relationship-pattern direction for Cypher-family backends. |
escape |
Cypher string and identifier escaping for safe query fragments. |
introspection |
Sampling introspection for the Cypher family. |
rel_merge |
Relationship MERGE map fragments for parallel edges (property-graph backends). |
scan |
Read every relationship between two labels, whatever its endpoints' keys. |
sync |
Cypher for record sync: ensure vertices, then replace what changed owners wrote. |
targets |
The Cypher read behind |
traversal |
Native variable-length traversal for the Cypher family. |
union |
Cypher upserts that union list fields with what a node or relationship holds. |
Attributes¶
__all__ = ['cypher_map_key', 'cypher_name', 'cypher_names', 'cypher_neighbors_query', 'cypher_rel_pattern', 'cypher_string_literal', 'partition_by_absent_merge_props', 'rel_absent_upsert_clause', 'rel_merge_props_map_from_row_index', 'rel_merge_props_map_from_row_props', 'rel_union_rows', 'rel_upsert_clause']
module-attribute
¶
Functions:¶
cypher_map_key(name)
¶
Return a backtick-quoted map-key / property name for Cypher patterns.
Surrounding whitespace is dropped first; embedded backticks are doubled, so two names differing only by a backtick stay two keys.
Source code in graflo/db/cypher/escape.py
cypher_name(name, *, quoted=False)
¶
A label, relationship type, property key or alias as one Cypher token.
An identifier that is not a reserved word is written as is unless quoted; any other name is backtick-quoted with embedded backticks doubled, so a name taken from a schema can never end the token and add query text of its own.
Raises:
| Type | Description |
|---|---|
ValueError
|
if name is empty. |
Source code in graflo/db/cypher/escape.py
cypher_names(names)
¶
One relationship type, or several joined with |, each one token.
cypher_neighbors_query(*, anchor_label, anchor_key_field='id', edge_type, far_label, direction, hops, limit, conditions=())
¶
Render a bounded neighbourhood query.
The anchor values are not part of the text: bind the first as
$anchor_id and each further one as $anchor_id_<n>
(:func:anchor_param) when running the query.
Returns one row per reached node: its properties (far), its labels, and
the relationships of every path that reached it (edges: type,
properties, and each end's properties and labels). Grouping by the node
is load-bearing: a graph with a cycle reaches the same node by several
paths, and without it the row count, and what LIMIT counts, grows with
path multiplicity rather than with neighbourhood size. The anchor itself is
excluded, since a walk in both directions can come back to it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
anchor_label
|
str
|
Storage label of the anchor node. |
required |
anchor_key_field
|
str | Sequence[str]
|
Property, or properties, the anchor is matched on. |
'id'
|
edge_type
|
str | Sequence[str] | None
|
Relationship type to follow, several to follow any of them, or None for any type. |
required |
far_label
|
str | None
|
Storage label the reached node must carry, or None for any. |
required |
direction
|
EdgeDirection
|
Orientation followed from the anchor. |
required |
hops
|
int
|
Maximum hop distance. |
required |
limit
|
int | None
|
Maximum reached nodes. |
required |
conditions
|
Sequence[str]
|
Further predicates over |
()
|
Source code in graflo/db/cypher/traversal.py
cypher_rel_pattern(edge_type, direction=EdgeDirection.OUT, *, variable='r', min_hops=None, max_hops=None)
¶
Render the relationship pattern between two node patterns.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
edge_type
|
str | Sequence[str] | None
|
Relationship type to filter on, several to match any of them, or None for any type. Each is written as one token. |
required |
direction
|
EdgeDirection
|
Orientation followed from the left-hand (anchor) node. |
OUT
|
variable
|
str
|
Relationship variable name bound in the pattern. |
'r'
|
min_hops
|
int | None
|
Lower bound for a variable-length pattern. Defaults to 1 when only max_hops is given. |
None
|
max_hops
|
int | None
|
Upper bound for a variable-length pattern. Omitting both keeps the single-hop form, which is what every existing caller wants. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
e.g. |
str
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
if the hop bounds are non-positive or inverted — an
unbounded |
Source code in graflo/db/cypher/direction.py
cypher_string_literal(value)
¶
partition_by_absent_merge_props(rows, prop_names, *, props_of, ends_of, union=())
¶
Group edge rows by the identity properties each one lacks.
prop_names are the properties the edge's identity names beside its
endpoints. Cypher refuses MERGE on a null property, so a row missing
one (absent or None) cannot use the property MERGE. As on
PostgreSQL (NULLS NOT DISTINCT), absence is part of the key: such a row
matches an existing edge lacking the same properties. Rows lacking some are
deduplicated on their endpoints and present merge values, later properties
winning, because :func:rel_absent_upsert_clause cannot see edges created
earlier in its own batch.
With union fields the complete group is deduplicated as well: one row per
edge carries the union of its rows' members, so no MERGE has to see a row
written earlier in its own batch.
Returns:
| Type | Description |
|---|---|
list[tuple[tuple[str, ...], list[Any]]]
|
|
Source code in graflo/db/cypher/rel_merge.py
rel_absent_upsert_clause(relation_name, prop_names, absent, *, props_expr, source='source', target='target', union=(), union_expr='row[3]')
¶
Upsert a relationship whose identity properties absent are missing.
Matches an existing relation_name edge between source and target
whose present identity properties equal the row's and whose absent ones are
unset, and updates it; creates one when none matches. Follows a MATCH
binding source, target and row. union fields are read from
union_expr and unioned with what the edge holds.
Source code in graflo/db/cypher/rel_merge.py
rel_merge_props_map_from_row_index(prop_names, *, row_index=2)
¶
Build `k`: row[n]['k'], ... for MERGE relationship properties.
Matches batches shaped as row = [source_doc, target_doc, props] (Neo4j,
FalkorDB-style row[2]).
Source code in graflo/db/cypher/rel_merge.py
rel_merge_props_map_from_row_props(prop_names, *, props_expr='row.props')
¶
Build `k`: row.props['k'], ... (Memgraph-style batch rows).
Source code in graflo/db/cypher/rel_merge.py
rel_union_rows(rows, union)
¶
[source, target, props] rows as [source, target, replaced, unioned].
The union fields move out of row[2] into row[3], so r += row[2]
can never overwrite a stored list (:func:rel_upsert_clause).
Source code in graflo/db/cypher/rel_merge.py
rel_upsert_clause(relation_name, prop_names, absent, *, union=(), props_expr='row[2]', union_expr='row[3]')
¶
Upsert one group of :func:partition_by_absent_merge_props rows.
MERGE on the endpoints (and prop_names when the group has them all),
or :func:rel_absent_upsert_clause when it lacks some. Follows a MATCH
binding source, target and row. union fields are read from
union_expr (:func:rel_union_rows) and written as the union of the
stored list and the row's.