Struct CypherQuery 

pub struct CypherQuery { /* private fields */ }

A Cypher query that can be executed against Lance datasets

Implementations

impl CypherQuery

pub fn new(query: &str) -> Result<Self>

Create a new Cypher query from a query string

pub fn with_config(self, config: GraphConfig) -> Self

Set the graph configuration for this query

pub fn with_adjacency(self, adjacency: AdjacencyCatalog) -> Self

Plan supported single-hop expansions with CSR lookups instead of joins.

The SessionContext used for execution must install crate::csr_expand::CsrQueryPlanner. Each adjacency must be built from the same relationship data the context serves, or results will be wrong.

pub fn with_fan_out(self, fan_out: FanOut) -> Self

Mean fan-out per relationship type and direction, so a pattern that continues earlier rows can start from its cheaper bound end (see crate::logical_plan::FanOut).

pub fn with_parameter<K, V>(self, key: K, value: V) -> Self

where K: Into<String>, V: Into<Value>,

Add a parameter to the query

pub fn with_parameters(self, params: HashMap<String, Value>) -> Self

Add multiple parameters to the query

pub fn query_text(&self) -> &str

Get the original query text

pub fn ast(&self) -> &CypherAST

Get the parsed AST

pub fn config(&self) -> Option<&GraphConfig>

Get the graph configuration

pub fn parameters(&self) -> &HashMap<String, Value>

Get query parameters

pub async fn execute( &self, datasets: HashMap<String, RecordBatch>, strategy: Option<ExecutionStrategy>, ) -> Result<RecordBatch>

Execute the query against provided in-memory datasets

This method uses the DataFusion planner by default for comprehensive query support including joins, aggregations, and complex patterns. You can optionally specify a different execution strategy.

Arguments

• datasets - HashMap of table name to RecordBatch (nodes and relationships)
• strategy - Optional execution strategy (defaults to DataFusion)

Returns

A single RecordBatch containing the query results

Errors

Returns error if query parsing, planning, or execution fails

Example

use std::collections::HashMap;
use arrow::record_batch::RecordBatch;
use lance_csr::query::CypherQuery;

// Create in-memory datasets
let mut datasets = HashMap::new();
datasets.insert("Person".to_string(), person_batch);
datasets.insert("KNOWS".to_string(), knows_batch);

// Parse and execute query
let query = CypherQuery::parse("MATCH (p:Person)-[:KNOWS]->(f) RETURN p.name, f.name")?
    .with_config(config);
// Use the default DataFusion strategy
let result = query.execute(datasets, None).await?;

pub async fn execute_with_namespace( &self, namespace: DirNamespace, strategy: Option<ExecutionStrategy>, ) -> Result<RecordBatch>

Execute the query using a namespace-backed table resolver.

The namespace is provided by value and will be shared internally as needed.

pub async fn execute_with_namespace_arc( &self, namespace: Arc<DirNamespace>, strategy: Option<ExecutionStrategy>, ) -> Result<RecordBatch>

Execute the query using a shared namespace instance.

pub async fn explain( &self, datasets: HashMap<String, RecordBatch>, ) -> Result<String>

Explain the query execution plan using in-memory datasets

Returns a formatted string showing the query execution plan at different stages:

• Graph Logical Plan (graph-specific operators)
• DataFusion Logical Plan (optimized relational plan)
• DataFusion Physical Plan (execution plan with optimizations)

This is useful for understanding query performance, debugging, and optimization.

Arguments

• datasets - HashMap of table name to RecordBatch (nodes and relationships)

Returns

A formatted string containing the execution plan at multiple levels

Errors

Returns error if planning fails

Example

use std::collections::HashMap;
use arrow::record_batch::RecordBatch;
use lance_csr::query::CypherQuery;

// Create in-memory datasets
let mut datasets = HashMap::new();
datasets.insert("Person".to_string(), person_batch);
datasets.insert("KNOWS".to_string(), knows_batch);

let query = CypherQuery::parse("MATCH (p:Person) WHERE p.age > 30 RETURN p.name")?
    .with_config(config);

let plan = query.explain(datasets).await?;
println!("{}", plan);

pub async fn to_sql( &self, datasets: HashMap<String, RecordBatch>, dialect: Option<SqlDialect>, ) -> Result<String>

Convert the Cypher query to a SQL string in the specified dialect.

This method generates a SQL string that corresponds to the DataFusion logical plan derived from the Cypher query, using the specified SQL dialect for unparsing.

WARNING: This method is experimental and the generated SQL dialect may change.

Note: All table names and column names in the generated SQL are lowercased (e.g., Person becomes person, fullName becomes fullname), consistent with the system’s case-insensitive identifier behavior.

Arguments

• datasets - HashMap of table name to RecordBatch (nodes and relationships)
• dialect - The SQL dialect to use for generating the output SQL. Defaults to SqlDialect::Default (generic DataFusion SQL). Use SqlDialect::Spark for Spark SQL, SqlDialect::PostgreSql, etc.

Returns

A SQL string representing the query in the specified dialect

Errors

Returns GraphError::UnsupportedFeature for runtime-only Cypher functions without a faithful SQL translation. Constant expressions may be folded first.

pub async fn execute_with_context( &self, ctx: SessionContext, ) -> Result<RecordBatch>

Execute query with a DataFusion SessionContext, automatically building the catalog

This is a convenience method that builds the graph catalog by querying the SessionContext for table schemas. The GraphConfig determines which tables to look up (node labels and relationship types).

This method is ideal for integrating with DataFusion’s rich data source ecosystem (CSV, Parquet, Delta Lake, Iceberg, etc.) without manually building a catalog.

Arguments

• ctx - DataFusion SessionContext with pre-registered tables

Returns

Query results as an Arrow RecordBatch

Errors

Returns error if:

• GraphConfig is not set (use .with_config() first)
• Required tables are not registered in the SessionContext
• Query execution fails

Example

use datafusion::execution::context::SessionContext;
use datafusion::prelude::CsvReadOptions;
use lance_csr::{CypherQuery, GraphConfig};

// Step 1: Create GraphConfig
let config = GraphConfig::builder()
    .node_table("Person", "person_id")
    .rel_table("KNOWS", "Person", "Person", "src_id", "dst_id")
    .build()?;

// Step 2: Register data sources in DataFusion
let ctx = SessionContext::new();
ctx.register_csv("Person", "data/persons.csv", CsvReadOptions::default()).await?;
ctx.register_parquet("KNOWS", "s3://bucket/knows.parquet", Default::default()).await?;

// Step 3: Execute query (catalog is built automatically)
let query = CypherQuery::parse("MATCH (p:Person)-[:KNOWS]->(f) RETURN p.name")?
    .with_config(config);
let result = query.execute_with_context(ctx).await?;

Note

The catalog is built by querying the SessionContext for schemas of tables mentioned in the GraphConfig. Table names must match between GraphConfig (node labels/relationship types) and SessionContext (registered table names).

pub async fn execute_with_catalog_and_context( &self, catalog: Arc<dyn GraphSourceCatalog>, ctx: SessionContext, ) -> Result<RecordBatch>

Execute query with an explicit catalog and session context

This is the most flexible API for advanced users who want to provide their own catalog implementation or have fine-grained control over both the catalog and session context.

Arguments

• catalog - Graph catalog containing node and relationship schemas for planning
• ctx - DataFusion SessionContext with registered data sources for execution

Returns

Query results as an Arrow RecordBatch

Errors

Returns error if query parsing, planning, or execution fails

Example

use std::sync::Arc;
use datafusion::execution::context::SessionContext;
use lance_csr::InMemoryCatalog;
use lance_csr::query::CypherQuery;

// Create custom catalog
let catalog = InMemoryCatalog::new()
    .with_node_source("Person", custom_table_source);

// Create SessionContext
let ctx = SessionContext::new();
ctx.register_table("Person", custom_table).unwrap();

// Execute with explicit catalog and context
let query = CypherQuery::parse("MATCH (p:Person) RETURN p.name")?
    .with_config(config);
let result = query.execute_with_catalog_and_context(Arc::new(catalog), ctx).await?;

pub async fn execute_stream_with_catalog_and_context( &self, catalog: Arc<dyn GraphSourceCatalog>, ctx: SessionContext, ) -> Result<SendableRecordBatchStream>

Execute query with an explicit catalog and session context, returning a stream.

Unlike Self::execute_with_catalog_and_context, results are not collected: batches are produced as the consumer polls, so memory is bounded by the plan’s operators (scans and filters stream; joins, sorts and aggregates may buffer).

pub async fn explain_with_catalog_and_context( &self, catalog: Arc<dyn GraphSourceCatalog>, ctx: SessionContext, ) -> Result<String>

Explain the plan with an explicit catalog and session context.

pub fn referenced_node_labels(&self) -> Vec<String>

Get all node labels referenced in this query

pub fn referenced_relationship_types(&self) -> Vec<String>

Get all relationship types referenced in this query

pub fn variables(&self) -> Vec<String>

Get all variables used in this query

impl CypherQuery

pub async fn execute_with_vector_rerank( &self, datasets: HashMap<String, RecordBatch>, vector_search: VectorSearch, ) -> Result<RecordBatch>

Execute Cypher query, then apply vector search reranking on results

This is a convenience method for the common GraphRAG pattern:

1. Run Cypher query to get candidate entities via graph traversal
2. Rerank candidates by vector similarity

Arguments

• datasets - HashMap of table name to RecordBatch (nodes and relationships)
• vector_search - VectorSearch configuration for reranking

Returns

A RecordBatch with the top-k results sorted by vector similarity

Example

use lance_csr::{CypherQuery, VectorSearch};
use lance_csr::ast::DistanceMetric;

let results = query
    .execute_with_vector_rerank(
        datasets,
        VectorSearch::new("embedding")
            .query_vector(query_vec)
            .metric(DistanceMetric::Cosine)
            .top_k(10)
    )
    .await?;

Trait Implementations

impl Clone for CypherQuery

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CypherQuery

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.