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_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_graph::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?;
// Use the Simple strategy explicitly
let result = query.execute(datasets, Some(ExecutionStrategy::Simple)).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_graph::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>, ) -> Result<String>

Convert the Cypher query to a DataFusion SQL string

This method generates a SQL string that corresponds to the DataFusion logical plan derived from the Cypher query. It uses the datafusion-sql unparser.

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)

Returns

A SQL string representing the query

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_graph::{CypherQuery, GraphConfig};

// Step 1: Create GraphConfig
let config = GraphConfig::builder()
    .with_node_label("Person", "person_id")
    .with_relationship("KNOWS", "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_graph::source_catalog::InMemoryCatalog;
use lance_graph::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_simple( &self, datasets: HashMap<String, RecordBatch>, ) -> Result<RecordBatch>

Execute simple single-table queries (legacy implementation)

This method supports basic projection/filter/limit workflows on a single table. For full query support including joins and complex patterns, use execute() instead.

Note: This implementation is retained for backward compatibility and simple use cases.

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_graph::{CypherQuery, VectorSearch};
use lance_graph::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) -> CypherQuery

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.