From 158b12c35c7afc4c0c27f1fdc9da92d44b50ac7b Mon Sep 17 00:00:00 2001 From: Alex Shuvalov Date: Wed, 9 Sep 2026 17:51:00 +0500 Subject: [PATCH] docs(collection): describe what create_index actually does The Note block described a multi-step process (clone table, copy rows, swap, rename) that the current implementation no longer performs. It also warned about dropping dependent views, which only applied to that older approach. Replaced it with what the method does today, plus the auto method selection rule, the n_lists formula, and the fact that CREATE INDEX is not concurrent. --- src/vecs/collection.py | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/src/vecs/collection.py b/src/vecs/collection.py index eab8f93..6d7a52d 100644 --- a/src/vecs/collection.py +++ b/src/vecs/collection.py @@ -700,23 +700,19 @@ def create_index( Creates an index for the collection. Note: - When `vecs` creates an index on a pgvector column in PostgreSQL, it uses a multi-step - process that enables performant indexes to be built for large collections with low end - database hardware. - - Those steps are: - - - Creates a new table with a different name - - Randomly selects records from the existing table - - Inserts the random records from the existing table into the new table - - Creates the requested vector index on the new table - - Upserts all data from the existing table into the new table - - Drops the existing table - - Renames the new table to the existing tables name - - If you create dependencies (like views) on the table that underpins - a `vecs.Collection` the `create_index` step may require you to drop those dependencies before - it will succeed. + The index is created in place on the collection's table. When *replace* is + True and an index already exists, it is dropped first, in the same + transaction. + + For `IndexMethod.auto`, HNSW is used when the installed pgvector supports + it (> 0.5.0), otherwise IVFFlat. + + For IVFFlat without explicit *index_arguments*, the number of lists is + derived from the row count: `max(n_records / 1000, 30)` below one million + rows, and `sqrt(n_records)` above it. + + `CREATE INDEX` is not run concurrently, so writes to the collection are + blocked for the duration of the build. Reads are unaffected. Args: measure (IndexMeasure, optional): The measure to index for. Defaults to 'cosine_distance'.