[codex] clarify docs search indexing and table behavior

[prrao87]

Summary

This PR tightens the docs around operational behavior that was previously easy to miss: when indexes are current, how query options compose, what rerankers return, and how table writes interact with versions and schemas.

The root issue is that many API pages described the happy path but left practical edge cases implicit. That can make users unsure about production defaults, async index freshness, mutable table handles, and SDK-specific behavior.

What changed

• Indexing and search behavior: clarifies index freshness checks, optimize(), FTS column selection, distance metrics, quantization options, SQL FTS usage, and multivector dimension requirements.
• Query ergonomics: adds high-level guidance for limits, filtering, hybrid search behavior, row IDs, pagination, and plan interpretation.
• Reranking expectations: documents provider prerequisites, score outputs, result ordering, custom reranker hooks, and score-retention options.
• Table writes and versions: clarifies append-vs-create behavior, schema nullability, write status metadata, mutable handles after checkout, merge predicates, and version metadata differences.

Validation

• Ran make snippets
• Ran git diff --check

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
lancedb-bcbb4faf	🟢 Ready	View Preview	May 24, 2026, 1:09 AM