mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-13 07:12:27 +00:00
Jack Ye
5b5ed930ac
Every group now answers exactly one question. Get started and Concepts cover what the system is; the verb groups cover doing something with it; Operate, Secure and Deploy cover running it; SQL reference is lookup. Maintenance becomes Operate, Governance becomes Secure, and the rest take verbs to match. Three new pages in Concepts and Get started: Guarantees states what a write promises when it returns, which version a reader sees, what survives a failure, and -- the half usually missing -- what is not guaranteed: no multi-table transactions, no read-your-writes across processes without an interval, unenforced primary keys that do not enforce, no background compaction. Limits collects bounds that were stated in passing across a dozen pages, with the numbers verified against the code rather than inferred: name lengths, job event caps, SHOW ERRORS bounds, the sampling range that is refused rather than clamped. Architecture illustrates embedded against distributed as the one deployment decision, and is written to cover both rather than only Enterprise. Indexing splits by question. Choosing an index is a Query decision and moves there; building, repairing and GPU-building it stay in Operate. SQL becomes a top-level reference of fifteen pages instead of a sub-group of Query. Auditing sophon-sql turned up a large undocumented surface: ALTER TABLE ADD COLUMN in its plain, computed and function forms with FILTER, IGNORE NULLS and OVER modifiers; SET UNENFORCED PRIMARY KEY; SET and UNSET WAL with sharding; CREATE FUNCTION with its dependency options; REFRESH COLUMN and REFRESH MATERIALIZED VIEW; and the SHOW family. None of it was written down.
52 lines
1.6 KiB
Plaintext
52 lines
1.6 KiB
Plaintext
---
|
|
title: "EXPLAIN"
|
|
sidebarTitle: "Explain"
|
|
description: "Reading the plan for a statement, and measuring it."
|
|
icon: map
|
|
keywords: ["explain", "explain analyze", "query plan", "describe"]
|
|
---
|
|
|
|
<Badge color="red">Enterprise</Badge> [SQL runs on a deployment.](/sql)
|
|
|
|
```sql
|
|
EXPLAIN SELECT * FROM documents WHERE identifier < 1000
|
|
EXPLAIN ANALYZE SELECT * FROM documents WHERE identifier < 1000
|
|
```
|
|
|
|
`EXPLAIN` resolves the plan without running the query. `EXPLAIN ANALYZE`
|
|
executes it and annotates every operator with runtime metrics — elapsed time,
|
|
rows produced, bytes read, index comparisons.
|
|
|
|
The operators are the same ones the SDK methods produce, so the reasoning about
|
|
index coverage and filter pushdown carries across unchanged. The two pages that
|
|
explain how to read them:
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Explain" icon="map" href="/search/explain">
|
|
Reading a plan: operators, pushdown, index usage.
|
|
</Card>
|
|
<Card title="Explain Analyze" icon="gauge" href="/search/explain-analyze">
|
|
Reading the metrics, and a worked before/after.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
## What to look for {#what-to-look-for}
|
|
|
|
| Sign | Means |
|
|
| --- | --- |
|
|
| `ScalarIndexQuery` | the predicate used a scalar index |
|
|
| `LanceScan` with high `bytes_read` | no index, or too many columns selected |
|
|
| `FilterExec` above a search | the filter ran after search rather than pushing into it |
|
|
| `ANNSubIndex` / `ANNIvfPartition` | the vector index was used |
|
|
|
|
A `LanceScan` feeding a join is the common one worth acting on — see
|
|
[Joins](/sql/join#performance).
|
|
|
|
## DESCRIBE {#describe}
|
|
|
|
```sql
|
|
DESCRIBE documents
|
|
```
|
|
|
|
The table's columns and types, without a plan.
|