GFQL Cypher Syntax API Reference

GFQL Cypher Syntax API Reference#

This page documents the Python helper APIs behind PyGraphistry’s Cypher-syntax support in GFQL.

  • Cypher is a graph query language popularized by Neo4j and related tools.

  • GFQL is PyGraphistry’s dataframe-native graph query language: the first fully vectorized graph query implementation with an open-source GPU runtime.

  • PyGraphistry supports a read-only Cypher surface on bound graphs that can be parsed, validated, compiled, and executed through GFQL’s columnar engine.

Use this page when you want to:

  • run a supported Cypher query through g.gfql("MATCH ...") on a bound graph

  • preflight a query with parse_cypher() or compile_cypher()

  • translate a supported query into a GFQL Chain programmatically

This page is an API reference, not the main tutorial. It covers Cypher syntax through g.gfql("MATCH ...") on a bound graph, which is the on-ramp for Cypher users who want familiar graph-pattern syntax without giving up GFQL’s fully vectorized dataframe/GPU execution model. For remote GFQL execution on Graphistry infrastructure, use g.gfql_remote([...]). For remote database Cypher over Bolt/Neo4j-style backends, use g.cypher(...) or graphistry.cypher(...).

See also:

Start Here: Cypher Syntax Through g.gfql()#

If you only want to run a supported Cypher query on a bound graph, start with g.gfql(...). The method always returns a Plottable, but the result shape depends on what you ask for:

  • native GFQL chains preserve graph state in _nodes and _edges

  • Cypher RETURN projections surface tabular rows in the returned _nodes dataframe

For the broader graph-state vs row-state model, see GFQL Quick Reference.

from graphistry.compute.ast import e_forward, n

# Graph/subgraph result: native GFQL chains stay in graph state.
g2 = g1.gfql([n({"type": "Person"}), e_forward(), n()])

# Row/table result: Cypher RETURN projections surface rows in _nodes.
df = g1.gfql(
    "MATCH (p:Person) RETURN p.name AS name ORDER BY name DESC LIMIT $top_n",
    params={"top_n": 5},
)._nodes

When the query argument is a string, the language selector defaults to "cypher". Top-level params=... is currently only supported for string query compilation; regular GFQL AST / Chain inputs use normal Python values in the AST itself.

Helper Functions#

Import the helpers from graphistry.compute.gfql.cypher:

from graphistry.compute.gfql.cypher import (
    parse_cypher,
    compile_cypher,
    cypher_to_gfql,
    gfql_from_cypher,
)

parse_cypher(query)#

  • Parses supported Cypher text into the typed AST used by the GFQL Cypher compiler.

  • Returns CypherQuery or CypherUnionQuery.

compile_cypher(query, params=None)#

  • Deprecated — scheduled for removal in a future release (tracked in #1169).

  • Parses and lowers a supported Cypher query into the compiled program used by g.gfql("MATCH ...") execution.

  • Returns compiler-internal shapes (CompiledCypherQuery / CompiledCypherUnionQuery / CompiledCypherGraphQuery) that are also deprecated internals scheduled for full removal.

  • Prefer g.gfql("...", language="cypher") for execution and cypher_to_gfql(...) / gfql_from_cypher(...) for single-chain translation.

cypher_to_gfql(query, params=None)#

  • Compiles a supported Cypher query into a single GFQL Chain.

  • Use this when you want the translated GFQL chain object instead of immediate execution.

  • Queries that require UNION or a row-returning CALL flow intentionally raise GFQLValidationError here; execute those directly through g.gfql("...", language="cypher") instead.

gfql_from_cypher(query, params=None)#

  • Alias for cypher_to_gfql(...) for callers that prefer GFQL-first naming.