In LanceDB's create_index, what do num_partitions and num_sub_vectors control?

## What create_index actually builds `create_index` on a LanceDB table with `index_type="IVF_PQ"` builds a two-stage structure. The IVF stage partitions the vector space by running k-means over a sample of your vectors and assigning every row to its nearest centroid. The PQ stage replaces each stored vector with a compact code instead of the full float array. `num_partitions` configures the first stage, `num_sub_vectors` the second. `metric` — `l2`, `cosine` or `dot` — is fixed at build time too, and must match what you later pass to `.metric()` at query time. Because both parameters are baked into the built artifact, getting them wrong means a rebuild, which on a large table is a real batch job. That is why interviewers ask: the cost of the mistake is not a config reload. ## num_partitions Think of it as the coarseness of the first filter. With N rows and P partitions, an average partition holds N/P vectors, and a query that probes p partitions scores roughly p × N/P candidates. - **Raise P**: each partition is smaller, so a probe is cheaper and queries are faster. But the query's slice of the corpus shrinks with it, so with the probe count held constant recall falls — the true neighbour is more likely to sit just over a boundary you did not visit. - **Lower P**: each probe scans more vectors, giving better recall per probe but slower queries, and at the limit you are back to something close to a scan. The usual heuristic is P ≈ √N, tuned so partitions land in the low thousands of vectors. Two failure modes bracket it. Set P far too high on a small table and k-means has too few points per cluster to learn anything useful — training is poor and the partitioning is close to arbitrary. Set P too low on a huge table and the index barely narrows the search. Build cost also scales with P: more centroids means a longer training pass. ## num_sub_vectors Product quantization splits each embedding into equal chunks and encodes each chunk as the id of the nearest entry in a small learned codebook — one byte per chunk in the usual 8-bit configuration. So `num_sub_vectors` is, directly, the compressed size of a row in the index. A 768-dimension float32 embedding is 3072 bytes raw. With `num_sub_vectors=96`, the code is about 96 bytes — roughly a 32× reduction. That compression is the whole point on LanceDB, where the index is expected to stay cached while the full vectors live on disk or in object storage. The cost is fidelity. Distances computed from codes are approximations, and the fewer sub-vectors you use, the coarser each chunk's codebook is relative to the data it must represent, so the ordering of near-tied candidates degrades. Raising `num_sub_vectors` improves that ordering and enlarges the index proportionally. **Hard constraint**: the embedding dimension must be divisible by `num_sub_vectors` — 768 works with 96, 64 or 48; it does not work with 100. Beyond divisibility, keeping dimension ÷ num_sub_vectors a multiple of 8 lets the distance computation use wide SIMD operations, which is a measurable throughput difference rather than a stylistic preference. ## How the two interact They trade off against different things and should be tuned separately. `num_partitions` trades query latency against how much of the corpus a query sees; `num_sub_vectors` trades index footprint against how accurate stored distances are. A common mistake is compensating for aggressive PQ compression by probing more partitions — that costs latency without fixing the real problem, which is that the compressed distances are too lossy to order candidates correctly. The right remedy for PQ loss is either more sub-vectors or a refinement step that rescores candidates against the full-precision vectors. ## Practical procedure Start from √N partitions and a sub-vector count that divides your dimension cleanly with an 8-aligned chunk size. Build. Measure recall@k against a flat-scan baseline and record build time and index size. If recall is low but latency is fine, probe more or add refinement before touching the build parameters. If latency is the problem, raise partitions and re-measure recall. Change one variable per build — with a rebuild costing minutes to hours, sweeping blindly is expensive.