From 459ee0355bd1a4cf928caef8d84df1dccdf4873d Mon Sep 17 00:00:00 2001 From: prrao87 Date: Sat, 7 Nov 2026 14:45:06 -0500 Subject: [PATCH] docs: make the quoted-name examples runnable The quoted-name examples in the Cypher and SQL guides queried a `Device Type` label that the engine on those pages doesn't have, so running either page top to bottom failed there. Each example now builds a small engine with that label. Also point the local spell check at typos 1.51.1, the version CI runs since #141. --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- docs/cypher.md | 7 ++++++- docs/sql.md | 9 +++++++-- 4 files changed, 15 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f8c7438..b40cec2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ - `python/python/tests/` stores functional tests; mirror new features with targeted cases here and in the corresponding Rust module. - `examples/` demonstrates Cypher usage; update or add examples when introducing new public APIs. - `docs/` is the Zensical documentation site (configured by `zensical.toml`); follow `docs/AGENTS.md`. -- Keep the docs in step with the code. Any substantial code change (a new or changed Python method, parameter, return type, exception or Cypher feature, or a change in behaviour users can observe) updates the affected guide pages in the same pull request. The Python API reference (`docs/api-reference.md`) is generated from the docstrings and type hints of the public classes in `python/python/lance_csr/`, so a Python API change updates those docstrings, checked against the behaviour in `crates/lance-csr-python/src/`. A change to a DataFusion extension (an extension node or operator, an optimizer rule, a planner rewrite, or the CSR and node indexes) updates `docs/internals/`. Document Python behaviour there, not in Rust `///` comments on the bindings. Then run `uv run --project docs --locked zensical build --strict` and `uvx typos@1.26.0 .` (the spell check CI runs). +- Keep the docs in step with the code. Any substantial code change (a new or changed Python method, parameter, return type, exception or Cypher feature, or a change in behaviour users can observe) updates the affected guide pages in the same pull request. The Python API reference (`docs/api-reference.md`) is generated from the docstrings and type hints of the public classes in `python/python/lance_csr/`, so a Python API change updates those docstrings, checked against the behaviour in `crates/lance-csr-python/src/`. A change to a DataFusion extension (an extension node or operator, an optimizer rule, a planner rewrite, or the CSR and node indexes) updates `docs/internals/`. Document Python behaviour there, not in Rust `///` comments on the bindings. Then run `uv run --project docs --locked zensical build --strict` and `uvx typos@1.51.1 .` (the spell check CI runs). ## Build, Test, and Development Commands - `cargo test --workspace` (from the repository root) runs the Rust tests; building needs `protoc`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3966a42..136c209 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -213,7 +213,7 @@ cd python && make test && make lint When you change user-facing behaviour or the Python API, update the affected guide pages and the docstrings of the Python classes in `python/python/lance_csr/` (which generate `docs/api-reference.md`) in the same pull request, then run -`uv run --project docs --locked zensical build --strict` and `uvx typos@1.26.0 .`. +`uv run --project docs --locked zensical build --strict` and `uvx typos@1.51.1 .`. ## Report a bug or suggest an improvement diff --git a/docs/cypher.md b/docs/cypher.md index 02089f1..2ad4756 100644 --- a/docs/cypher.md +++ b/docs/cypher.md @@ -594,7 +594,12 @@ other characters, or that matches a keyword. Inside a quoted name, two backticks doesn't change the case rules above. ```python -engine.execute( +device_config = GraphConfig.builder().node_table("Device Type", "asset id").build() +devices = { + "Device Type": pa.table({"asset id": ["a-1", "b-2"], "status": ["active", "retired"]}) +} +device_engine = CypherEngine(device_config, devices) +device_engine.execute( "MATCH (x:`Device Type`) WHERE x.`asset id` IN $keys RETURN x.`asset id` AS `asset id`", {"keys": ["a-1"]}, ).to_pylist() # [{'asset id': 'a-1'}] diff --git a/docs/sql.md b/docs/sql.md index cc0ee37..1c39520 100644 --- a/docs/sql.md +++ b/docs/sql.md @@ -120,12 +120,17 @@ Cypher's backticks work too. The direct `graph_table('...')` call takes Cypher t is a string. ```python -engine.execute(""" +device_config = GraphConfig.builder().node_table("Device Type", "asset id").build() +devices = { + "Device Type": pa.table({"asset id": ["a-1", "b-2"], "status": ["active", "retired"]}) +} +device_engine = SqlEngine(devices, device_config) +device_engine.execute(""" SELECT g."asset id" FROM GRAPH_TABLE ( MATCH (x:"Device Type") WHERE x.status = 'active' COLUMNS (x."asset id" AS "asset id") ) g -""") +""").to_pylist() # [{'asset id': 'a-1'}] ``` To run Cypher and SQL over the same data, build the `CypherEngine` and share its snapshot. Nothing is rebuilt, and