GFQL Chain Matcher

GFQL Chain Matcher#

Chain enables combining multiple matchers into a single matcher, e.g., for mining paths and subgraphs.

Same-path constraints are expressed via where on a Chain; see GFQL WHERE (Same-Path Constraints).

class graphistry.compute.chain.Chain(chain, where=None, validate=True)#

Bases: ASTSerializable

Parameters:

  • chain (List[ASTObject])

  • where (Sequence[WhereComparison] | None)

  • validate (bool)

classmethod from_json(d, validate=True)#

Convert a JSON AST into a list of ASTObjects

Parameters:

  • d (Dict[str, None | bool | str | float | int | List[Any] | Dict[str, Any]])

  • validate (bool)

Return type:

Chain

gfql_validated()#

Mark a Chain that gfql built and is executing in the same call.

Return type:

Chain

to_json(validate=True)#

Convert a list of ASTObjects into a JSON AST

Return type:

Dict[str, None | bool | str | float | int | List[Any] | Dict[str, Any]]

validate(collect_all=False)#

Validate this AST node.

Args:
collect_all: If True, collect all errors instead of raising on first.

If False (default), raise on first error.

Returns:

If collect_all=True: List of validation errors (empty if valid) If collect_all=False: None if valid

Raises:

GFQLValidationError: If collect_all=False and validation fails

Parameters:

collect_all (bool)

Return type:

List[GFQLValidationError] | None

validate_schema(g, collect_all=False)#

Validate this chain against a graph’s schema without executing.

Args:

g: Graph to validate against collect_all: If True, collect all errors. If False, raise on first.

Returns:

If collect_all=True: List of errors (empty if valid) If collect_all=False: None if valid

Raises:

GFQLValidationError: If collect_all=False and validation fails

Parameters:
Return type:

List[GFQLValidationError] | None

graphistry.compute.chain.chain(self, ops, engine=EngineAbstract.AUTO, validate_schema=True, policy=None, context=None, start_nodes=None, strict=None)#

Chain a list of ASTObject (node/edge) traversal operations

Return subgraph of matches according to the list of node & edge matchers If any matchers are named, add a correspondingly named boolean-valued column to the output

For direct calls, exposes convenience List[ASTObject]. Internal operational should prefer Chain.

Use engine=’cudf’ to force automatic GPU acceleration mode

Parameters:

  • ops (List[ASTObject] | Chain) – List[ASTObject] Various node and edge matchers

  • validate_schema (bool) – Whether to validate the chain against the graph schema before executing

  • policy – Optional policy dict for hooks

  • context – Optional ExecutionContext for tracking execution state

  • start_nodes (Any | None) – Optional node wavefront for the first traversal step

  • strict (Any) – Absent-name strictness: "strict" raises, "warn" (default) warns once per absent name and resolves it to null, "quiet" resolves silently. True/False map to "strict"/"quiet". None consults bind(schema=...), then the "warn" default.

  • self (Plottable)

  • engine (EngineAbstract | str)

Returns:

Plotter

Return type:

Plotter

graphistry.compute.chain.combine_steps(g, kind, steps, engine, label_steps=None)#

Collect nodes and edges, taking care to deduplicate and tag any names

Parameters:
Return type:

Any

graphistry.compute.chain.reject_alias_named_like_binding(g, chain_obj, *, include_edge_endpoint_aliases=False)#

Typed decline for an alias named after a binding column: a node alias equal to the node-ID binding, and (native chains and Cypher alike) an edge alias equal to the source, destination or edge-ID binding.

The alias marker is stamped as <alias> = True, so an alias equal to the node-id column overwrites the ids themselves: pandas then died with a raw ValueError: The column label 'id' is not unique from the chain’s own merge while polars answered True. Neither is a usable result; decline the same way on both.

Parameters:

  • g (Plottable)

  • chain_obj (Chain)

  • include_edge_endpoint_aliases (bool)

Return type:

None

graphistry.compute.chain.select_attach_prop_columns(middle, calls, node_columns, node_id)#

Projection pushdown for a bare rows() immediately followed by select.

Returns, per node alias of middle, the property columns that select reads, so the bindings builder attaches only those. None keeps attach-all: any item that is not a literal, a bare alias id, an edge-alias column, or a plain alias.column over an existing node column (absent properties keep their 3VL verdict on the full table).

Parameters:

  • middle (Sequence[ASTObject])

  • calls (Sequence[ASTObject])

  • node_columns (Sequence[str])

  • node_id (str | None)

Return type:

Dict[str, List[str]] | None