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.

NameTypeDefault ValueDescription
search.async-fanout-thresholdNumber30Minimum number of fanout targets for which remote requests are issued asynchronously. Range: 1 to 10000.
search.backfill-batch-sizeNumber10240Controls the batch size for backfilling indexes. Range: 1 to 2147483647.
search.cluster-map-expiration-msNumber250Controls 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-secsNumber25Controls 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-countNumber100000Maximum COUNT accepted by WITHCURSOR and FT.CURSOR READ. Range: 1 to INT64_MAX.
search.cursor-max-idle-msNumberINT64_MAXMaximum MAXIDLE (milliseconds) accepted by WITHCURSOR
search.debug-modeBooleannoEnables 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-scorerEnumBM25STDScorer used when a query omits SCORER. See Search - Scoring. Values: BM25STD.
search.default-timeout-msNumber50000Controls the default timeout in milliseconds for FT.SEARCH, FT.AGGREGATE and FT.HYBRID. Range: 1 to 60000.
search.drain-mutation-queue-on-saveBooleannoDrain the mutation queue before RDB save
search.emulate-releaseVersion1.0.0Release 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-resultsBooleannoDefault option for delivering consistent results when timeout occurs (uses CONSISTENT if not explicitly provided)
search.enable-partial-resultsBooleanyesDefault option for delivering partial results when timeout occurs (uses SOMESHARDS if not explicitly provided)
search.fuzzy-max-distanceNumber3Controls the maximum allowed edit distance for fuzzy search queries. Range: 1 to 50.
search.high-priority-weightNumber100Weight for high priority tasks in thread pools; low priority = 100 - this value. Range: 0 to 100.
search.hnsw-block-sizeNumber10240HNSW resize configuration parameter for vector index block allocation. Range: 0 to 4294967295.
search.info-developer-visibleBooleannoShow developer metrics in INFO. See INFO SEARCH metrics.
search.local-fanout-queue-wait-thresholdNumber50Queue wait threshold in milliseconds for preferring local node in fanout operations. Range: 0 to 10000.
search.log-levelEnumnoticeControls module log level verbosity. Values: warning, notice, verbose, debug.
search.max-attributesNumber1000Controls the max number of attributes per index. Range: 1 to 10000.
search.max-group-key-expansionNumber65536Maximum 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-indexesNumber1000Controls the maximum number of search indexes that can be created in the system. Range: 1 to 10000000.
search.max-mutation-queue-size-on-restoreNumber10000Limits the mutation queue size during RDB restore to prevent memory spikes. Range: 1 to 1000000.
search.max-nonvector-search-results-fetchedNumber100000Maximum 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-lengthNumber128Controls the max length of a numeric field. Range: 1 to 256.
search.max-prefixesNumber8Controls the max number of prefixes per index. Range: 1 to 16.
search.max-query-queue-depthNumber100000When 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-countNumber500Controls the max number of fields in the content of the search response. Range: 1 to 1000.
search.max-search-result-record-sizeNumber5242880Controls the max content size for a record in the search response. Range: 100 to 10485760.
search.max-tag-field-lengthNumber256Controls the max length of a tag field. Range: 1 to 10000.
search.max-term-expansionsNumber200Maximum number of words to search in text operations (prefix, suffix, fuzzy) to limit memory usage. Range: 1 to 100000.
search.max-timeout-msNumber60000Controls the maximum allowed TIMEOUT value, in milliseconds, for FT.SEARCH, FT.AGGREGATE and FT.HYBRID. Range: 1 to 60000.
search.max-vector-attributesNumber1000Deprecated alias of search.max-attributes; used instead of it only when explicitly set. Range: 1 to 10000.
search.max-vector-dimensionsNumber32768Controls the max dimensions for vector indices. Range: 1 to 64000.
search.max-vector-ef-constructionNumber1000000Controls the max EF construction parameter for HNSW algorithm. Range: 1 to 1000000.
search.max-vector-ef-runtimeNumber1000000Maximum EF_RUNTIME accepted for HNSW fields and query overrides. Range: 1 to 1000000.
search.max-vector-knnNumber10000Controls the max KNN parameter for vector search. Range: 1 to 100000.
search.max-vector-mNumber2000000Controls the max M parameter for HNSW algorithm. Range: 2 to 2000000.
search.max-worker-suspension-secsNumber60Max time in seconds that worker thread pool is suspended after fork started. Range: 0 to 3600.
search.proximity-inorder-compat-modeBooleannoControls proximity iterator's inorder/overlap violation check logic (compatibility mode)
search.query-string-bytesNumber10240Controls the length of the query string for FT.SEARCH command. Range: 1 to 4294967295.
search.query-string-depthNumber1000Controls the depth of the query string parsing from the FT.SEARCH cmd. Range: 1 to 4294967295.
search.query-string-terms-countNumber1000Controls the size of the query string parsing from the FT.SEARCH cmd (number of nodes in predicate tree). Range: 1 to 10000.
search.reader-threadsNumberPhysical CPU coresControls the reader thread pool size; dynamically resizes pool on modification. Range: 1 to 1024.
search.search-result-background-cleanupBooleanEnable search result cleanup on background thread
search.search-result-buffer-multiplierNumber (decimal)1.5Multiplier for search result buffer size allocation. Range: 1.0 to 1000.0.
search.skip-corrupted-internal-update-entriesBooleannoSkip corrupted AOF entries during internal updates
search.skip-rdb-loadBooleannoSkip loading vector index data from RDB file
search.tag-min-prefix-lengthNumber2Minimum number of characters required before trailing * in TAG wildcard queries (length excludes *). Range: 0 to 4294967295.
search.thread-pool-wait-time-samplesNumber100Sample queue size for thread pool wait time tracking. Range: 10 to 10000.
search.use-coordinatorBooleannoControls 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-threadsNumber1Controls the utility thread pool size; dynamically resizes pool on modification. Range: 1 to 1024.
search.vector-chunk-huge-pagesBooleanyesAllocate 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-sizeNumber10240Number of vector records unshared per server cron tick. Range: 1 to 4294967295.
search.writer-threadsNumberPhysical CPU coresControls 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.

⌂ 换网址