API reference¶

Everything below is importable from lance_csr. The classes are implemented in Rust (PyO3); this page is written by hand from their signatures and docstrings, and every behaviour it states is checked against the code. The guides link here for exact signatures and link back for examples.

lance_csr.__version__ is the package version.

Datasets¶

Methods that take datasets take a dict[str, object] mapping each node label or relationship type (or SQL table name) to one of:

• lance.LanceDataset: read lazily and version-pinned by CypherEngine; read into memory by the other classes;
• pyarrow.Table, pyarrow.RecordBatch, pyarrow.RecordBatchReader, or any object exporting the Arrow C stream interface (__arrow_c_stream__).

Keys match labels case-insensitively.

Exceptions¶

GraphConfig¶

An immutable mapping from tables to a property graph. Create one with GraphConfig.builder().

GraphConfig.builder() -> GraphConfigBuilder (static)

A new, empty builder.

node_labels() -> list[str]

The configured node labels, lower-cased, in no particular order.

relationship_types() -> list[str]

The configured relationship types, lower-cased, in no particular order.

GraphConfigBuilder¶

GraphConfigBuilder()

Same as GraphConfig.builder(). Every method returns a new builder.

node_table(label: str, primary_key: str) -> GraphConfigBuilder

Nodes labelled label, one per row of the dataset named label, identified by the primary_key column.

rel_table(rel_type: str, from_table: str, to_table: str, src: str, dst: str) -> GraphConfigBuilder

Edges of type rel_type, one per row of the dataset named rel_type, from from_table nodes to to_table nodes. src and dst hold the endpoints' primary keys.

build() -> GraphConfig

Validates and returns the config. Raises ValueError if a relationship's endpoint label has no node table.

with_node_label(label: str, id_field: str) (deprecated)

Use node_table. Emits DeprecationWarning.

with_relationship(rel_type: str, source_field: str, target_field: str, source_label: str | None = None, target_label: str | None = None) (deprecated)

Use rel_table. Emits DeprecationWarning.

See Graph schema.

CypherEngine¶

CypherEngine(config: GraphConfig, datasets: dict, use_csr: bool = False)

Registers datasets once and reuses the catalog, DataFusion session and (with use_csr=True) CSR index across queries. Safe to share between threads.

Raises ValueError if datasets is empty, a configured key or endpoint column is missing, or a Lance dataset was opened through a namespace client and can't be reopened by URI. Raises RuntimeError if a dataset can't be opened.

execute(query: str, params: dict | None = None) -> pyarrow.Table

Runs query and returns the whole result. params binds $name parameters: int, float, str, bool, None, datetime.datetime and datetime.date.

execute_batches(query: str, params: dict | None = None) -> pyarrow.RecordBatchReader

Streams the result. Planning errors raise immediately; execution errors raise while reading. The reader keeps its snapshot alive across refresh().

explain(query: str, params: dict | None = None) -> str

The graph logical plan, DataFusion logical plan and physical plan.

refresh() -> None

Moves every Lance dataset to its latest version and updates the CSR, node indexes and statistics. All-or-nothing; running queries keep their snapshot. See Lance datasets.

dataset_versions() -> dict[str, int]

The pinned version of each Lance dataset. PyArrow inputs are not listed.

csr_stats() -> dict[str, dict]

Per relationship type with a CSR: edges, delta_edges, tombstones, update, version, build_ms. Empty without use_csr=True. See Inspecting the CSR.

node_index_stats() -> dict[str, dict]

Per node label with a node index: rows, version, build_ms.

config() -> GraphConfig

The engine's config.

execute_with_vector_rerank(query: str, vector_search: VectorSearch) -> pyarrow.Table

Runs query, then ranks its rows with vector_search. See Vector search.

CypherQuery¶

CypherQuery(query_text: str)

A parsed Cypher query. Raises ValueError if query_text doesn't parse. Builder methods return a new query.

with_config(config: GraphConfig) -> CypherQuery

Sets the graph config. Required before executing.

with_parameter(key: str, value: object) -> CypherQuery

Binds $key to value.

execute(datasets: dict, strategy: ExecutionStrategy | None = None) -> pyarrow.Table

Runs the query. Datasets are read into memory for this call.

execute_with_namespace(namespace: DirNamespace, strategy: ExecutionStrategy | None = None) -> pyarrow.Table

Runs the query, resolving each label to <base_uri>/<label>.lance.

explain(datasets: dict) -> str

The plans, as for CypherEngine.explain.

to_sql(datasets: dict, dialect: SqlDialect | None = None) -> str

The equivalent SQL, as joins. See From Cypher to SQL.

execute_with_vector_rerank(datasets: dict, vector_search: VectorSearch) -> pyarrow.Table

Runs the query, then reranks by vector similarity.

query_text() -> str, parameters() -> dict

The query text and the bound parameters.

variables() -> list[str], node_labels() -> list[str], relationship_types() -> list[str]

Names referenced by the query.

SqlEngine¶

SqlEngine(datasets: dict)

Registers datasets (names lower-cased) in a DataFusion session for repeated SQL queries. Raises ValueError if datasets is empty.

execute(sql: str) -> pyarrow.Table

Runs a SQL query.

SqlQuery¶

SqlQuery(sql: str)

execute(datasets: dict) -> pyarrow.Table

Registers datasets and runs the query.

explain(datasets: dict) -> str

DataFusion's logical and physical plans.

sql() -> str

The query text.

VectorSearch¶

VectorSearch(column: str)

An immutable builder for vector similarity search. column is the vector column; for reranking a Cypher result, use alias.property ("d.embedding").

search(table: pyarrow.Table) -> pyarrow.Table

Brute-force search, sorted by distance, at most top_k rows. Raises ValueError if no query vector is set or the column doesn't exist.

DistanceMetric¶

DirNamespace¶

DirNamespace(base_uri: str)

Resolves table names to Lance datasets at <base_uri>/<name>.lance, for CypherQuery.execute_with_namespace.

base_uri -> str (property)

The directory.

ExecutionStrategy¶

SqlDialect¶

SqlDialect.Default (DataFusion), SqlDialect.Spark, SqlDialect.PostgreSql, SqlDialect.MySql, SqlDialect.Sqlite. Used by CypherQuery.to_sql.