Valkey Search - Configuration · Valkey

Valkey Search - Configuration

Configurables

The search module uses the Valkey configuration mechanism. Each configuration below can be set as a module load argument or with the CONFIG SET command, except search.use-coordinator, which can be set only as a module load argument.

The module also has developer-only configurations, intended for testing and diagnosing the module. They are not listed on this page. Enabling developer-only configurations is not a supported operating mode. They can be changed with CONFIG SET or as module load arguments only while search.debug-mode is yes (default no); values set in the Valkey configuration file are accepted regardless of search.debug-mode.

Name Type Default Value Description
search.async-fanout-threshold Number 30 Minimum number of fanout targets for which remote requests are issued asynchronously. Range: 1 to 10000.
search.backfill-batch-size Number 10240 Controls the batch size for backfilling indexes. Range: 1 to 2147483647.
search.cluster-map-expiration-ms Number 250 Controls how long (in milliseconds) the coordinator caches the cluster topology map before refreshing it from the Valkey cluster. Range: 0 to 3600000.
search.coordinator-query-timeout-secs Number 25 Controls the gRPC deadline timeout (in seconds) for distributed coordinator query operations. It is independent of the query timeout: with the default search.default-timeout-ms of 50000, a remote shard still running after this deadline is treated as a failed shard (see search.enable-partial-results). Range: 1 to 3600.
search.cursor-max-count Number 100000 Maximum COUNT accepted by WITHCURSOR and FT.CURSOR READ. Range: 1 to INT64_MAX.
search.cursor-max-idle-ms Number INT64_MAX Maximum MAXIDLE (milliseconds) accepted by WITHCURSOR
search.debug-mode Boolean no Enables developer-only configurations and lifts the upper bound of search.emulate-release. Not listed by CONFIG GET search.*; read it by its full name.
search.default-scorer Enum BM25STD Scorer used when a query omits SCORER. See Search - Scoring. Values: BM25STD.
search.default-timeout-ms Number 50000 Controls the default timeout in milliseconds for FT.SEARCH, FT.AGGREGATE and FT.HYBRID. Range: 1 to 60000.
search.drain-mutation-queue-on-save Boolean no Drain the mutation queue before RDB save
search.emulate-release Version 1.0.0 Release whose behavior is emulated for gated compatibility fixes (see COMPATIBILITY.md). The default is <major>.0.0 of the running module, so fixes gated at 1.3.0 are off by default. Range: 1.0.0 to the running module version; the upper bound is lifted while search.debug-mode is yes.
search.enable-consistent-results Boolean no Default option for delivering consistent results when timeout occurs (uses CONSISTENT if not explicitly provided)
search.enable-partial-results Boolean yes Default option for delivering partial results when timeout occurs (uses SOMESHARDS if not explicitly provided)
search.fuzzy-max-distance Number 3 Controls the maximum allowed edit distance for fuzzy search queries. Range: 1 to 50.
search.high-priority-weight Number 100 Weight for high priority tasks in thread pools; low priority = 100 - this value. Range: 0 to 100.
search.hnsw-block-size Number 10240 HNSW resize configuration parameter for vector index block allocation. Range: 0 to 4294967295.
search.info-developer-visible Boolean no Show developer metrics in INFO. See INFO SEARCH metrics.
search.local-fanout-queue-wait-threshold Number 50 Queue wait threshold in milliseconds for preferring local node in fanout operations. Range: 0 to 10000.
search.log-level Enum notice Controls module log level verbosity. Values: warning, notice, verbose, debug.
search.max-attributes Number 1000 Controls the max number of attributes per index. Range: 1 to 10000.
search.max-group-key-expansion Number 65536 Maximum number of groups one record can expand into in an FT.AGGREGATE GROUPBY over multi-value fields; exceeding it fails the query. Range: 1 to 4294967295.
search.max-indexes Number 1000 Controls the maximum number of search indexes that can be created in the system. Range: 1 to 10000000.
search.max-mutation-queue-size-on-restore Number 10000 Limits the mutation queue size during RDB restore to prevent memory spikes. Range: 1 to 1000000.
search.max-nonvector-search-results-fetched Number 100000 Maximum number of matches retained per shard by a non-vector query. See Vector Range Match for VECTOR_RANGE behavior. Range: 0 to 4294967295.
search.max-numeric-field-length Number 128 Controls the max length of a numeric field. Range: 1 to 256.
search.max-prefixes Number 8 Controls the max number of prefixes per index. Range: 1 to 16.
search.max-query-queue-depth Number 100000 When the reader thread pool queue reaches this depth, FT.SEARCH, FT.AGGREGATE and FT.HYBRID are rejected with Search query queue depth exceeded before fan-out. Checked on each node that receives the query. 0 means unlimited. Range: 0 to 2147483647.
search.max-search-result-fields-count Number 500 Controls the max number of fields in the content of the search response. Range: 1 to 1000.
search.max-search-result-record-size Number 5242880 Controls the max content size for a record in the search response. Range: 100 to 10485760.
search.max-tag-field-length Number 256 Controls the max length of a tag field. Range: 1 to 10000.
search.max-term-expansions Number 200 Maximum number of words to search in text operations (prefix, suffix, fuzzy) to limit memory usage. Range: 1 to 100000.
search.max-timeout-ms Number 60000 Controls the maximum allowed TIMEOUT value, in milliseconds, for FT.SEARCH, FT.AGGREGATE and FT.HYBRID. Range: 1 to 60000.
search.max-vector-attributes Number 1000 Deprecated alias of search.max-attributes; used instead of it only when explicitly set. Range: 1 to 10000.
search.max-vector-dimensions Number 32768 Controls the max dimensions for vector indices. Range: 1 to 64000.
search.max-vector-ef-construction Number 1000000 Controls the max EF construction parameter for HNSW algorithm. Range: 1 to 1000000.
search.max-vector-ef-runtime Number 1000000 Maximum EF_RUNTIME accepted for HNSW fields and query overrides. Range: 1 to 1000000.
search.max-vector-knn Number 10000 Controls the max KNN parameter for vector search. Range: 1 to 100000.
search.max-vector-m Number 2000000 Controls the max M parameter for HNSW algorithm. Range: 2 to 2000000.
search.max-worker-suspension-secs Number 60 Max time in seconds that worker thread pool is suspended after fork started. Range: 0 to 3600.
search.proximity-inorder-compat-mode Boolean no Controls proximity iterator’s inorder/overlap violation check logic (compatibility mode)
search.query-string-bytes Number 10240 Controls the length of the query string for FT.SEARCH command. Range: 1 to 4294967295.
search.query-string-depth Number 1000 Controls the depth of the query string parsing from the FT.SEARCH cmd. Range: 1 to 4294967295.
search.query-string-terms-count Number 1000 Controls the size of the query string parsing from the FT.SEARCH cmd (number of nodes in predicate tree). Range: 1 to 10000.
search.reader-threads Number Physical CPU cores Controls the reader thread pool size; dynamically resizes pool on modification. Range: 1 to 1024.
search.search-result-background-cleanup Boolean Enable search result cleanup on background thread
search.search-result-buffer-multiplier Number (decimal) 1.5 Multiplier for search result buffer size allocation. Range: 1.0 to 1000.0.
search.skip-corrupted-internal-update-entries Boolean no Skip corrupted AOF entries during internal updates
search.skip-rdb-load Boolean no Skip loading vector index data from RDB file
search.tag-min-prefix-length Number 2 Minimum number of characters required before trailing * in TAG wildcard queries (length excludes *). Range: 0 to 4294967295.
search.thread-pool-wait-time-samples Number 100 Sample queue size for thread pool wait time tracking. Range: 10 to 10000.
search.use-coordinator Boolean no Controls whether this instance uses the coordinator. Can be set only as a module load argument; it is not visible to CONFIG GET or CONFIG SET.
search.utility-threads Number 1 Controls the utility thread pool size; dynamically resizes pool on modification. Range: 1 to 1024.
search.vector-chunk-huge-pages Boolean yes Allocate vector index memory in 2 MB transparent huge pages (needs Valkey 9.2+ and THP not disabled); applies to new allocations
search.vector-unshare-batch-size Number 10240 Number of vector records unshared per server cron tick. Range: 1 to 4294967295.
search.writer-threads Number Physical CPU cores Controls the writer thread pool size; dynamically resizes pool on modification. Range: 1 to 1024.

search.vector-chunk-huge-pages takes effect when the server provides the external memory APIs (Valkey 9.2+) and transparent huge pages are not disabled for the process or host. Vector memory is then allocated and counted in 2 MB units, so a small index reports a few MB more used_memory. A 2 MB chunk is released only when all the vectors in it are deleted, so after most keys of a FLAT index are deleted, used_memory stays near its peak until new vectors reuse the space.