doc: pgvector compatibility

Signed-off-by: cutecutecat <junyuchen@tensorchord.ai>

.vitepress/config.mts

@@ -67,6 +67,7 @@ export default defineConfig({
             { text: 'Search', link: '/usage/search' },
             { text: 'Monitoring', link: '/usage/monitoring' },
             { text: 'Quantization', link: '/usage/quantization' },
+            { text: 'Compatibility', link: '/usage/compatibility' },
           ]
         },
         {

src/usage/compatibility.md

@@ -0,0 +1,119 @@
+# Pgvector compatibility
+
+Pgvecto.rs is natively compatible with pgvector at:
+- Create table like `CREATE TABLE t (val vector(3))`
+- Query vectors like `INSERT INTO t (val) VALUES ('[0.6,0.6,0.6]')`
+
+Pgvecto.rs can be configured to be compatible with pgvector at: 
+- Create vector indexes like `CREATE INDEX ON t USING hnsw (val vector_ip_ops);`
+- Query options like `SET ivfflat.probes=10;`
+
+This feature is called `compatibility mode`. 
+It can be enabled with `SET vectors.pgvector_compatibility=on`.
+
+## Options & Variables
+
+For index `ivfflat` and `hnsw` only the following options and variables are available.
+
+* Default value for `options` is **different from pgvecto.rs original**, which keeps the same as in `pgvector`.
+* Default value for `variables` is kept the same as in pgvecto.rs.
+
+Options for `ivfflat`:
+
+| Key   | Type    | Default | Description               |
+| ----- | ------- | ------- | ------------------------- |
+| lists | integer | `100`   | Number of cluster units.  |
+
+Variables for `ivfflat`:
+
+| Option           | Type                     | Default | Description                               |
+| ---------------- | ------------------------ | ------- | ----------------------------------------- |
+| ivfflat.probes   | integer (`[1, 1000000]`) | `10`    | Number of lists to scan.                  |
+
+::: warning
+Default value of `ivfflat.probes` is `10` instead of `1` from pgvector.
+:::
+
+Options for `hnsw`:
+
+| key             | type    | default | description                      |
+| --------------- | ------- | ------- | -------------------------------- |
+| m               | integer | `16`    | Maximum degree of the node.      |
+| ef_construction | integer | `64`    | Search extent in construction.   |
+
+Variables for `hnsw`:
+
+| Option         | Type                     | Default | Description                               |
+| -------------- | ------------------------ | ------- | ----------------------------------------- |
+| hnsw.ef_search | integer (`[1, 65535]`)   | `100`   | Search scope of HNSW.                     |
+
+::: warning
+Default value for `hnsw.ef_search` is `100` instead of `40` from pgvector.
+:::
+
+::: tip
+The original syntax of pgvecto.rs is still available even in `compatibility mode`.
+
+You can use it with the `vectors` index like before:
+```sql
+SET vectors.ivf_nprobe=20;
+CREATE INDEX ON items USING vectors (embedding vector_l2_ops)
+WITH (options = $$
+[indexing.ivf]
+quantization.product.ratio = "x16"
+$$);
+```
+:::
+
+## Examples
+
+It's easy to enable compatibility mode and start a vector query.
+```sql
+DROP TABLE IF EXISTS t;
+SET vectors.pgvector_compatibility=on;
+CREATE TABLE t (val vector(3));
+INSERT INTO t (val) SELECT ARRAY[random(), random(), random()]::real[] FROM generate_series(1, 1000);
+CREATE INDEX hnsw_l2_index ON t USING hnsw (val vector_l2_ops);
+SELECT COUNT(1) FROM (SELECT 1 FROM t ORDER BY val <-> '[0.5,0.5,0.5]' limit 100) t2;
+DROP INDEX hnsw_l2_index;
+```
+
+Multiply types of indexes are accepted:
+```sql
+SET vectors.pgvector_compatibility=on;
+-- [hnsw + vector_l2_ops] index with default options
+CREATE INDEX hnsw_l2_index ON t USING hnsw (val vector_l2_ops);
+-- [hnsw + vector_cosine_ops] index with single ef_construction option
+CREATE INDEX hnsw_cosine_index ON t USING hnsw (val vector_cosine_ops) WITH (ef_construction = 80);
+-- anonymous [hnsw + vector_ip_ops] with all options
+CREATE INDEX ON t USING hnsw (val vector_ip_ops) WITH (ef_construction = 80, m = 12);
+-- [ivfflat + vector_l2_ops] index with default options
+CREATE INDEX ivfflat_l2_index ON t USING ivfflat (val vector_l2_ops);
+-- [ivfflat + vector_ip_ops] index with all options
+CREATE INDEX ivfflat_ip_index ON t USING ivfflat (val vector_cosine_ops) WITH (nlist = 80);
+-- anonymous [ivf + vector_ip_ops] with all options
+CREATE INDEX ON t USING ivfflat (val vector_ip_ops) WITH (lists = 80)
+```
+
+## Limitation
+
+For compatibility, we strive to maintain a consistent user experience, but there are still some limitations in two aspects:
+
+- Some features of pgvector.rs are not available in `compatibility mode'. 
+- Some features of pgvector are different in `compatibility mode 
+
+### Inaccessible features of pgvecto.rs
+When executing SQL statements in `compatibility mode` without `vectors` index, some features of pgvecto.rs are not accessible:
+- `flat` index 
+- Quantization, including `scalar quantization` and `product quantization`
+- Prefilter and vbase
+
+### Difference from pgvector
+
+Pgvecto.rs `compatibility mode` only provide compatibility of **creating index** at the foremost.
+Nevertheless, there are still differences from pgvector.
+
+Known problems are not limited to:
+- Create `btree` index on vector type data is not supported
+- Create vector indexes is asynchronous at pgvecto.rs, instead of synchronous at pgvector
+- Default value of `variable` is different from pgvector