You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>Docker pull for pgvecto.rs: <ahref="https://hub.docker.com/r/tensorchord/pgvecto-rs"><imgsrc="https://img.shields.io/docker/pulls/tensorchord/pgvecto-rs"alt="Previous Docker pulls" /></a></p>
11
10
</p>
12
11
13
-
VectorChord (vchord) is a PostgreSQL extension designed for scalable, high-performance, and disk-efficient vector similarity search, and serves as the successor to [pgvecto.rs](https://github.com/tensorchord/pgvecto.rs).
12
+
> [!NOTE]
13
+
> VectorChord serves as the successor to [pgvecto.rs](https://github.com/tensorchord/pgvecto.rs) <ahref="https://hub.docker.com/r/tensorchord/pgvecto-rs"><imgsrc="https://img.shields.io/docker/pulls/tensorchord/pgvecto-rs"alt="Previous Docker pulls" /></a> with better stability and performance. If you are interested in this new solution, you may find the [migration guide](https://docs.vectorchord.ai/vectorchord/admin/migration.html) helpful.
14
14
15
-
With VectorChord, you can store 400,000 vectors for just $1, enabling significant savings: 6x more vectors compared to Pinecone's optimized storage and 26x more than pgvector/pgvecto.rs for the same price[^1]. For further insights, check out our [launch blog post](https://blog.vectorchord.ai/vectorchord-store-400k-vectors-for-1-in-postgresql).
15
+
VectorChord (vchord) is a PostgreSQL extension designed for scalable, high-performance, and disk-efficient vector similarity search.
16
16
17
-
[^1]: Based on [MyScale Benchmark](https://myscale.github.io/benchmark/#/) with 768-dimensional vectors and 95% recall.
17
+
With VectorChord, you can store 400,000 vectors for just $1, enabling significant savings: 6x more vectors compared to Pinecone's optimized storage and 26x more than pgvector/pgvecto.rs for the same price[^1].
18
18
19
19
## Features
20
20
21
21
VectorChord introduces remarkable enhancements over pgvecto.rs and pgvector:
22
22
23
-
**⚡ Enhanced Performance**: Delivering optimized operations with up to 5x faster queries, 16x higher insert throughput, and 16x quicker[^3] index building compared to pgvector's HNSW implementation.
23
+
**⚡ Enhanced Performance**: Delivering optimized operations with up to 5x faster queries, 16x higher insert throughput, and 16x quicker[^1] index building compared to pgvector's HNSW implementation.
24
24
25
-
[^3]: Based on [MyScale Benchmark](https://myscale.github.io/benchmark/#/) with 768-dimensional vectors. Please checkout our [blog post](https://blog.vectorchord.ai/vectorchord-store-400k-vectors-for-1-in-postgresql) for more details.
25
+
[^1]: Based on [MyScale Benchmark](https://myscale.github.io/benchmark/#/) with 768-dimensional vectors and 95% recall. Please checkout our [blog post](https://blog.vectorchord.ai/vectorchord-store-400k-vectors-for-1-in-postgresql) for more details.
26
26
27
27
**💰 Affordable Vector Search**: Query 100M 768-dimensional vectors using just 32GB of memory, achieving 35ms P50 latency with top10 recall@95%, helping you keep infrastructure costs down while maintaining high search quality.
28
28
29
29
**🔌 Seamless Integration**: Fully compatible with pgvector data types and syntax while providing optimal defaults out of the box - no manual parameter tuning needed. Just drop in VectorChord for enhanced performance.
30
30
31
-
**🔧 External Index Build**: Leverage IVF to build indexes externally (e.g., on GPU) for faster KMeans clustering, combined with RaBitQ[^2] compression to efficiently store vectors while maintaining search quality through autonomous reranking.
31
+
**🔧 External Index Build**: Leverage IVF to build indexes externally (e.g., on GPU) for faster KMeans clustering, combined with RaBitQ[^3] compression to efficiently store vectors while maintaining search quality through autonomous reranking.
32
32
33
-
**📏 Long Vector Support**: Store and search vectors up to 65,535 dimensions, enabling the use of the best high-dimensional models like text-embedding-3-large with ease.
33
+
[^3]: Gao, Jianyang, and Cheng Long. "RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search." Proceedings of the ACM on Management of Data 2.3 (2024): 1-27.
34
34
35
-
[^2]: Gao, Jianyang, and Cheng Long. "RaBitQ: Quantizing High-Dimensional Vectors with a Theoretical Error Bound for Approximate Nearest Neighbor Search." Proceedings of the ACM on Management of Data 2.3 (2024): 1-27.
35
+
**📏 Long Vector Support**: Store and search vectors up to 65,535[^4] dimensions, enabling the use of the best high-dimensional models like text-embedding-3-large with ease.
36
+
37
+
[^4]: There is a [limitation](https://github.com/pgvector/pgvector#vector-type) at pgvector of 16,000 dimensions now. If you really have a large dimension(`16,000<dim<65,535`), consider to change [VECTOR_MAX_DIM](https://github.com/pgvector/pgvector/blob/fef635c9e5512597621e5669dce845c744170822/src/vector.h#L4) and compile pgvector yourself.
38
+
39
+
**🌐 Scale As You Want**: Based on horizontal expansion, the query of 5M / 100M 768-dimensional vectors can be easily scaled to 10000+ QPS with top10 recall@90% at a competitive cost[^5]
40
+
41
+
[^5]: Please check our [blog post](https://blog.vectorchord.ai/vector-search-at-10000-qps-in-postgresql-with-vectorchord) for more details, the PostgreSQL scalability is powered by [CloudNative-PG](https://github.com/cloudnative-pg/cloudnative-pg).
42
+
43
+
## Requirements
44
+
45
+
> [!TIP]
46
+
> If you are using the official [Docker image](https://hub.docker.com/r/tensorchord/vchord-postgres), you can skip this step.
47
+
48
+
VectorChord depends on [pgvector](https://github.com/pgvector/pgvector), ensure the pgvector extension is available:
49
+
50
+
```SQL
51
+
SELECT*FROM pg_available_extensions WHERE name ='vector';
52
+
```
53
+
If pgvector is not available, install it using the [pgvector installation instructions](https://github.com/pgvector/pgvector#installation).
54
+
55
+
And make sure to add `vchord.so` to the `shared_preload_libraries` in `postgresql.conf`.
56
+
57
+
```SQL
58
+
-- Add vchord and pgvector to shared_preload_libraries --
59
+
-- Note: A restart is required for this setting to take effect.
60
+
ALTER SYSTEM SET shared_preload_libraries ='vchord.so';
61
+
```
36
62
37
63
## Quick Start
38
64
For new users, we recommend using the Docker image to get started quickly.
@@ -41,49 +67,149 @@ docker run \
41
67
--name vectorchord-demo \
42
68
-e POSTGRES_PASSWORD=mysecretpassword \
43
69
-p 5432:5432 \
44
-
-d tensorchord/vchord-postgres:pg17-v0.1.0
70
+
-d tensorchord/vchord-postgres:pg17-v0.2.1
45
71
```
46
72
47
73
Then you can connect to the database using the `psql` command line tool. The default username is `postgres`, and the default password is `mysecretpassword`.
48
74
49
75
```bash
50
76
psql -h localhost -p 5432 -U postgres
51
77
```
52
-
Run the following SQL to ensure the extension is enabled.
78
+
79
+
Now you can play with VectorChord!
80
+
81
+
## Documentation
82
+
83
+
-[Installation](#installation)
84
+
-[Docker](#installation)
85
+
-[APT](#apt)
86
+
-[More Methods](#more-methods)
87
+
-[Usage](#usage)
88
+
-[Storing](#storing)
89
+
-[Indexing](#indexing)
90
+
-[Query](#query)
91
+
-[Performance Tuning](#performance-tuning)
92
+
-[Index Build Time](#index-build-time)
93
+
-[Query Performance](#query-performance)
94
+
-[Advanced Features](#advanced-features)
95
+
-[Indexing Prewarm](#indexing-prewarm)
96
+
-[Indexing Progress](#indexing-progress)
97
+
-[External Index Precomputation](#external-index-precomputation)
98
+
<!--TODO: Here we have a memory leak in rerank_in_table, show it until the feature is ready
Since you can use them directly, your application can be easily migrated without pain!
135
+
136
+
Before all, you need to run the following SQL to ensure the extension is enabled.
53
137
54
138
```SQL
55
139
CREATE EXTENSION IF NOT EXISTS vchord CASCADE;
56
140
```
141
+
It will install both `pgvector` and `VectorChord`, see [requirements](#requirements) for more detail.
57
142
58
-
And make sure to add `vchord.so` to the `shared_preload_libraries` in `postgresql.conf`.
143
+
### Storing
59
144
60
-
```SQL
61
-
-- Add vchord and pgvector to shared_preload_libraries --
62
-
ALTER SYSTEM SET shared_preload_libraries ='vchord.so';
145
+
Similar to pgvector, you can create a table with vector column in VectorChord and insert some rows to it.
146
+
147
+
```sql
148
+
CREATETABLEitems (id bigserialPRIMARY KEY, embedding vector(3));
149
+
INSERT INTO items (embedding) SELECT ARRAY[random(), random(), random()]::real[] FROM generate_series(1, 1000);
63
150
```
64
151
152
+
### Indexing
153
+
154
+
Similar to [ivfflat](https://github.com/pgvector/pgvector#ivfflat), the index type of VectorChord, RaBitQ(vchordrq) also divides vectors into lists, and then searches a subset of those lists that are closest to the query vector. It inherits the advantages of `ivfflat`, such as fast build times and less memory usage, but has [much better performance](https://blog.vectorchord.ai/vectorchord-store-400k-vectors-for-1-in-postgresql#heading-ivf-vs-hnsw) than hnsw and ivfflat.
155
+
156
+
The RaBitQ(vchordrq) index is supported on some pgvector types and metrics:
> Due to the limitation of postgresql query planner, we cannot support the range query like `SELECT embedding <-> '[3,1,2]' as distance WHERE distance < 0.1 ORDER BY distance` directly.
227
+
### Index Build Time
228
+
229
+
Index building can parallelized, and with external centroid precomputation, the total time is primarily limited by disk speed. Optimize parallelism using the following settings:
103
230
104
-
To query vectors within a certain distance range, you can use the following syntax.
105
231
```SQL
106
-
-- Query vectors within a certain distance range
107
-
-- sphere(center, radius) means the vectors within the sphere with the center and radius, aka range query
108
-
-- <<->> is L2 distance, <<#>> is inner product, <<=>> is cosine distance
109
-
SELECT vec FROM t WHERE vec <<->> sphere('[0.24, 0.24, 0.24]'::vector, 0.012)
110
-
``` -->
232
+
-- Set this to the number of CPU cores available for parallel operations.
233
+
SET max_parallel_maintenance_workers =8;
234
+
SET max_parallel_workers =8;
235
+
236
+
-- Adjust the total number of worker processes.
237
+
-- Note: A restart is required for this setting to take effect.
238
+
ALTER SYSTEM SET max_worker_processes =8;
239
+
```
111
240
112
-
###Query Performance Tuning
241
+
## Query Performance
113
242
You can fine-tune the search performance by adjusting the `probes` and `epsilon` parameters:
114
243
115
244
```sql
@@ -118,8 +247,8 @@ You can fine-tune the search performance by adjusting the `probes` and `epsilon`
118
247
SETvchordrq.probes=100;
119
248
120
249
-- Set epsilon to control the reranking precision.
121
-
-- Larger value means more rerank for higher recall rate.
122
-
--Don't change it unless you only have limited memory.
250
+
-- Larger value means more rerank for higher recall rate and latency.
251
+
--If you need a less precise query, set it to 1.0 might be appropriate.
123
252
-- Recommended range: 1.0–1.9. Default value is 1.9.
124
253
SETvchordrq.epsilon=1.9;
125
254
@@ -146,25 +275,21 @@ SET jit = off;
146
275
ALTER SYSTEM SET shared_buffers ='8GB';
147
276
```
148
277
278
+
## Advanced Features
279
+
149
280
### Indexing prewarm
150
-
To prewarm the index, you can use the following SQL. It will significantly improve performance when using limited memory.
151
-
```SQL
152
-
-- vchordrq_prewarm(index_name::regclass) to prewarm the index into the shared buffer
For disk-first indexing, RaBitQ(vchordrq) is loaded from disk for the first query,
283
+
and then cached in memory if `shared_buffer` is sufficient.
156
284
157
-
### Index Build Time
158
-
Index building can parallelized, and with external centroid precomputation, the total time is primarily limited by disk speed. Optimize parallelism using the following settings:
285
+
In most cases, reading from disk is 10x slower than reading from memory,
286
+
resulting in a significant cold-start slowdown.
159
287
160
-
```SQL
161
-
-- Set this to the number of CPU cores available for parallel operations.
162
-
SET max_parallel_maintenance_workers = 8;
163
-
SET max_parallel_workers = 8;
288
+
To improve performance for the first query, you can try the following SQL that preloads the index into memory.
164
289
165
-
-- Adjust the total number of worker processes.
166
-
-- Note: A restart is required for this setting to take effect.
167
-
ALTER SYSTEM SET max_worker_processes = 8;
290
+
```SQL
291
+
--vchordrq_prewarm(index_name::regclass) to prewarm the index into the shared buffer
To simplify the workflow, we provide end-to-end scripts for external index pre-computation, see [scripts](./scripts/README.md#run-external-index-precomputation-toolkit).
206
331
332
+
<!-- TODO: Here we have a memory leak in rerank_in_table, show it until the feature is ready
333
+
334
+
### Capacity-optimized Index
335
+
336
+
The default behavior of Vectorchord is `performance-optimized`,
337
+
which uses more disk space but has a better latency:
338
+
- About `80G` for `5M` 768 dim vectors
339
+
- About `800G` for `100M` 768 dim vectors
340
+
341
+
Although it is acceptable for such large data, it could be switched to `capacity-optimized` index and save about **50%** of your disk space.
342
+
343
+
For `capacity-optimized` index, just enable the `rerank_in_table` option when creating the index:
344
+
```sql
345
+
CREATE INDEX ON items USING vchordrq (embedding vector_l2_ops) WITH (options = $$
346
+
residual_quantization = true
347
+
rerank_in_table = true
348
+
[build.internal]
349
+
...
350
+
$$);
351
+
```
352
+
353
+
> [!CAUTION]
354
+
> Compared to the `performance-optimized` index, the `capacity-optimized` index will have a **30-50%** increase in latency and QPS loss at query.
355
+
356
+
-->
357
+
358
+
### Range Query
359
+
360
+
To query vectors within a certain distance range, you can use the following syntax.
361
+
```SQL
362
+
-- Query vectors within a certain distance range
363
+
SELECT vec FROM t WHERE vec <<->> sphere('[0.24, 0.24, 0.24]'::vector, 0.012)
364
+
ORDER BY embedding <-> '[0.24, 0.24, 0.24]' LIMIT 5;
365
+
```
366
+
367
+
In this expression, `vec <<->> sphere('[0.24, 0.24, 0.24]'::vector, 0.012)` is equals to `vec <-> '[0.24, 0.24, 0.24]' < 0.012`. However, the latter one will trigger a **exact nearest neighbor search** as the grammar could not be pushed down.
368
+
369
+
Supported range functions are:
370
+
- `<<->>` - L2 distance
371
+
- `<<#>>` - (negative) inner product
372
+
- `<<=>>` - cosine distance
373
+
374
+
## Development
375
+
207
376
### Build the Postgres Docker Image with VectorChord extension
208
377
209
378
Follow the steps in [Dev Guidance](./scripts/README.md#build-docker).
0 commit comments