[prrao87]

Why

The CSR index only works with integer keys. With string or UUID keys, use_csr=True silently falls back to hash joins over whole tables at every hop. The query returns the same results but runs slower, and nothing warns the user. The docs said this, but only in a short tip late in Getting started ("anything else quietly uses joins"), under a Graph schema heading that doesn't mention performance, and on the CSR page. A user picking key types for a new graph could easily miss it until queries were already slow.

What changed

• Getting started: a short "Use integer keys" tip right where the first graph's datasets and keys are defined. In plain terms: integer keys let the CSR go straight from a node to its neighbours, string keys make every hop scan whole tables with no warning, and path variables need integer keys too. It suggests adding an integer id column and keeping the UUID as a property, and links to Graph schema for details.
• Graph schema: renamed "Keys and the CSR" to "Key types and traversal performance" so readers and agents searching for performance advice can find it. It now says that the fallback gives no warning, and that ids don't need to be consecutive (it previously suggested a "dense" id column, which isn't required).
• The CSR index, "Should I turn it on?": the integer-key row now says in plain terms why this is the fast case and what the fused target lookup does. The UUID row says why it gains little. The closing note says the benchmarks use GDC SNB data with integer keys.

Validation

• uv run --project docs --locked zensical build --strict: no issues, and the new cross-page anchor resolves.
• uvx typos@1.26.0 .: clean.
• Checked the documented behaviour with UUID keys on a small graph: csr_stats() is empty and plain hops plan as joins with no warning. A path variable query raises NotImplementedError with use_csr on and off.
• The benchmark claim was checked against both benchmark runners, which load GDC SNB data with numeric ids.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying lance-csr with    Cloudflare Pages

Latest commit:	aaf3e0c
Status:	✅  Deploy successful!
Preview URL:	https://dd886ee5.lance-csr.pages.dev
Branch Preview URL:	https://docs-integer-key-performance.lance-csr.pages.dev

View logs