Question: Why is manual vchordrq.probes configuration required for every query based on index lists parameter?

[SharkSyl]

Question

What is the reason behind requiring explicit vchordrq.probes configuration for every query session?

Docker

Version: tensorchord/vchord-postgres:pg15-v1.0.0

docker-compose

services:
  pgvecto-rs:
    image: tensorchord/vchord-postgres:pg15-v1.0.0
    restart: always
    environment:
      PGUSER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: demo
      PGDATA: /var/lib/postgresql/data
    command: ["postgres", 
              "-c", "shared_preload_libraries=vchord.so", 
              "-c", "search_path=public,vchord", 
              "-c", "max_connections=35",  
              "-c", "logging_collector=off"]
    volumes:
      - ./volumes/pgvectors/data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: [ "CMD", "pg_isready" ]
      interval: 1s
      timeout: 3s
      retries: 30

Observation

When using vchordrq indexes with different lists configurations, queries fail unless vchordrq.probes is manually configured before each query execution:

-- Index with lists = [2000]
CREATE INDEX idx_with_lists ON table_a USING vchordrq (embedding vector_cosine_ops)
WITH (options = $$[build.internal] lists = [2000]$$);

-- Query fails without manual configuration
SELECT * FROM table_a ORDER BY embedding <=> query_vec LIMIT 5;
-- ERROR: need 1 probes, but 0 probes provided

-- Must manually set probes first
SET vchordrq.probes = 10;
SELECT * FROM table_a ORDER BY embedding <=> query_vec LIMIT 5;  -- Now works

Similarly, for indexes with lists = [], an empty string must be explicitly set:

-- Index with lists = []
CREATE INDEX idx_without_lists ON table_b USING vchordrq (embedding vector_cosine_ops)
WITH (options = $$[build.internal] lists = []$$);

-- Query fails without manual configuration
-- ERROR: need 1 probes, but 0 probes provided

-- Must explicitly set empty probes
SET vchordrq.probes = '';
SELECT * FROM table_b ORDER BY embedding <=> query_vec LIMIT 5;  -- Now works

Summary of Current Behavior

Index lists Configuration	Required Manual Setting	Error Without Setting
lists = []	SET vchordrq.probes = '';	need 1 probes, but 0 provided
lists = [N] (N > 0)	SET vchordrq.probes = M; (where M ≥ 1)	need 1 probes, but 0 provided

Any clarification on the design philosophy and recommended workarounds would be greatly appreciated.

[usamoi]

What is the reason behind requiring explicit vchordrq.probes configuration for every query session?

It's how PostgreSQL works.

You can use ALTER ... SET to make the setting take effect permanently.

ALTER SYSTEM SET vchordrq.probes = 1;
SELECT pg_reload_conf();

See also https://www.postgresql.org/docs/current/sql-altersystem.html.

Or use SET LOCAL to make the setting take effect only in the transaction.

BEGIN;
SET LOCAL vchordrq.probes = 1;
-- queries
COMMIT;

See also https://www.postgresql.org/docs/current/sql-set.html.

[SharkSyl]

What is the reason behind requiring explicit vchordrq.probes configuration for every query session?

It's how PostgreSQL works.

You can use ALTER ... SET to make the setting take effect permanently.

ALTER SYSTEM SET vchordrq.probes = 1;
SELECT pg_reload_conf();
See also https://www.postgresql.org/docs/current/sql-altersystem.html.

Or use SET LOCAL to make the setting take effect only in the transaction.

BEGIN;
SET LOCAL vchordrq.probes = 1;
-- queries
COMMIT;
See also https://www.postgresql.org/docs/current/sql-set.html.

I tried the configuration, but when querying list=[] in the index, it reported "need 0 probes, but 1 probes provided".
so I set the list size to 20, and it worked fine.
therefore, I plan to use a list size of at least 20 going forward.
thanks for your help.

[usamoi]

I think the correct approach is to set GUCs before searching.

That said, you can avoid the error by using build.internal.lists = [1].

Perhaps we should allow specifying values corresponding to index names in GUCs, like SET vchordrq.probes = '10; index_i: 20'. However, since no users have reported this need before, we have not done so.

[SharkSyl]

You are right. Currently, I have set the default value by postgres -c vchordrq.probes=10 in the docker-compose.

I saw in the documentation here that it mentions since v0.3.0, the default is set to ' '.

I wonder if it might support specifying a default probes value for the current index during CREATE INDEX, similar to what you mentioned with SET vchordrq.probes = '10; index_i: 20 .

The syntax in this case might be：

CREATE index_1 ON table_1 USING vchordrq (embedding vector_cosine_ops) WITH (options = $$
residual_quantization = true
[build.internal]
lists = [20]
probes = 1
spherical_centroids = true
build_threads = 8
$$);  -- or `set vchordrq.probes = 10 on index index_1` to add specifying  config


CREATE index_2 ON table_2 USING vchordrq (embedding vector_cosine_ops) WITH (options = $$
residual_quantization = true
[build.internal]
lists = [2000]
probes = 1
spherical_centroids = true
build_threads = 8
$$); -- or `set vchordrq.probes = 10 on index index_1`  to add specifying  config

It can be used to provide a default probes value for tables with different data volumes, with a priority higher than the system config but lower than SET LOCAL vchordrq.probes = int_value in transactions.

I think some people might not pay much attention to SET vchordrq.probes, such as business developers who don’t directly interact with the database. Therefore, having a default value could handle such cases more effectively.

Please assess whether it's necessary to make this feature. Thanks.

[usamoi]

We discussed this feature today. We are aware of the issue at pgvector/pgvector#235, and pgvector is adding this feature. However, we have decided not to implement it for now.

1. It causes confusion for some users who do not use this feature, because they must inspect the index build options to determine which parameters were chosen.
2. Prior to PostgreSQL 18, GUCs do not have the state of a default value. An extension cannot distinguish whether a GUC is using its default, has been explicitly set to the same value as the default, or has been explicitly set to the default value. This makes it difficult for the extension to determine when the build options should be used as query parameters. For conservative reasons, even if we were to implement this feature, we would only support it on PostgreSQL 18, which would limit the benefiting user base to a very small group.

[SharkSyl]

thanks

[mertalev]

I think it'd be nice to support it in some way, perhaps with the index names in the guc like the earlier example. My usage involves two indices that can have different lists and so different probes, which means I have to SET LOCAL before each query. Setting per-index values at startup would avoid some round trips at query time and simplify the code a bit since the querying code doesn't need to know which probe value to use.