{
"schema_version": 2,
"id": "develop/ai/search-and-query/administration/configuration",
"title": "Configuration parameters",
"url": "https://redis.io/docs/latest/develop/ai/search-and-query/administration/configuration/",
"summary": "Redis Search can be tuned through multiple configuration parameters. Some of these parameters can only be set at load-time, while other parameters can be set either at load-time or at run-time.",
"aliases": [
"/develop/interact/search-and-query/administration/configuration",
"/develop/interact/search-and-query/basic-constructs/configuration-parameters"
],
"tags": [
"docs",
"develop",
"stack",
"oss",
"rs",
"rc",
"oss",
"kubernetes",
"clients"
],
"last_updated": "2026-10-15T15:16:04-07:00",
"page_type": "content",
"content_hash": "8857c528e0f4d64f3252cc68764e1af742c04f3c1b9fc7c7bfe288d2337210b6",
"sections": [
{
"id": "overview",
"title": "Overview",
"role": "overview",
"text": "> [!NOTE]\n> As of Redis 8 in Redis Open Source (Redis 8), configuration parameters for Redis Search are now set in the following ways:\n> * At load time via your `redis.conf` file.\n> * At run time (where applicable) using the [`CONFIG SET`](https://redis.io/docs/latest/commands/config-set) command.\n>\n> Also, Redis 8 persists Redis Search configuration parameters just like any other configuration parameters (e.g., using the [`CONFIG REWRITE`](https://redis.io/docs/latest/commands/config-rewrite) command)."
},
{
"id": "redis-search-configuration-parameters",
"title": "Redis Search configuration parameters",
"role": "content",
"text": "The following table summarizes which configuration parameters can be set at run-time, the versions in which each parameter is available, and compatibility with Redis Software and Redis Cloud.\n\nThe version columns indicate availability per Redis Query Engine module version (2.6, 2.8, and 2.10) and per Redis Open Source version (8.0, 8.2, 8.4, and 8.10). In those columns, ✅ means the parameter is available, ❌ means it is not available, and :warning: means it is deprecated (but still accepted) in that version.\n\n#### Table part 1 of 2, rows 1-10\n\n| Parameter name
(version < 8.0) | Parameter name
(version ≥ 8.0) | 2.6 | 2.8 | 2.10 | 8.0 | 8.2 |\n| :------- | :------- | :----: | :----: | :----: | :----: | :----: |\n| BG_INDEX_SLEEP_GAP | [search-bg-index-sleep-gap](#search-bg-index-sleep-gap) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| BG_INDEX_SLEEP_DURATION_US | [search-bg-index-sleep-duration-us](#search-bg-index-sleep-duration-us) | ❌ | ❌ | ❌ | ❌ | ✅ |\n| CONCURRENT_WRITE_MODE | Removed in v2.10. | ✅ | ✅ | ❌ | ❌ | ❌ |\n| CONN_PER_SHARD | [search-conn-per-shard](#search-conn-per-shard) | ❌ | ✅ | ✅ | ✅ | ✅ |\n| CURSOR_MAX_IDLE | [search-cursor-max-idle](#search-cursor-max-idle) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| CURSOR_REPLY_THRESHOLD | [search-cursor-reply-threshold](#search-cursor-reply-threshold) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| DEFAULT_DIALECT | [search-default-dialect](#search-default-dialect) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| EXTLOAD | [search-ext-load](#search-ext-load) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| FORK_GC_CLEAN_THRESHOLD | [search-fork-gc-clean-threshold](#search-fork-gc-clean-threshold) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| FORK_GC_RETRY_INTERVAL | [search-fork-gc-retry-interval](#search-fork-gc-retry-interval) | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n#### Table part 1 of 2, rows 11-20\n\n| Parameter name
(version < 8.0) | Parameter name
(version ≥ 8.0) | 2.6 | 2.8 | 2.10 | 8.0 | 8.2 |\n| :------- | :------- | :----: | :----: | :----: | :----: | :----: |\n| FORK_GC_RUN_INTERVAL | [search-fork-gc-run-interval](#search-fork-gc-run-interval) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| FORKGC_SLEEP_BEFORE_EXIT | [search-fork-gc-sleep-before-exit](#search-fork-gc-sleep-before-exit) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| FRISOINI | [search-friso-ini](#search-friso-ini) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| [GC_POLICY](#gc_policy) | There is no matching `CONFIG` parameter. | ✅ | ✅ | ✅ | ✅ | ✅ |\n| GCSCANSIZE | [search-gc-scan-size](#search-gc-scan-size) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| INDEX_CURSOR_LIMIT | [search-index-cursor-limit](#search-index-cursor-limit) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| INDEX_THREADS | Removed in v2.10. | ✅ | ✅ | ❌ | ❌ | ❌ |\n| MAXAGGREGATERESULTS | [search-max-aggregate-results](#search-max-aggregate-results) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| MAXDOCTABLESIZE | [search-max-doctablesize](#search-max-doctablesize) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| MAXEXPANSIONS | [search-max-expansions](#search-max-expansions) | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n#### Table part 1 of 2, rows 21-30\n\n| Parameter name
(version < 8.0) | Parameter name
(version ≥ 8.0) | 2.6 | 2.8 | 2.10 | 8.0 | 8.2 |\n| :------- | :------- | :----: | :----: | :----: | :----: | :----: |\n| MAXPREFIXEXPANSIONS | [search-max-prefix-expansions](#search-max-prefix-expansions) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| MAXSEARCHRESULTS | [search-max-search-results](#search-max-search-results) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| _MAX_FOREGROUND_TIMEOUT_LIMIT | [search-_max-foreground-timeout-limit](#search-_max-foreground-timeout-limit) | ❌ | ❌ | ❌ | ❌ | ❌ |\n| MIN_OPERATION_WORKERS | [search-min-operation-workers](#search-min-operation-workers) | ❌ | ❌ | ✅ | ✅ | ✅ |\n| MIN_PHONETIC_TERM_LEN | [search-min-phonetic-term-len](#search-min-phonetic-term-len) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| MINPREFIX | [search-min-prefix](#search-min-prefix) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| MINSTEMLEN | [search-min-stem-len](#search-min-stem-len) | ❌ | ❌ | ✅ | ✅ | ✅ |\n| MULTI_TEXT_SLOP | [search-multi-text-slop](#search-multi-text-slop) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| NO_MEM_POOLS | [search-no-mem-pools](#search-no-mem-pools) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| NOGC | [search-no-gc](#search-no-gc) | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n#### Table part 1 of 2, rows 31-40\n\n| Parameter name
(version < 8.0) | Parameter name
(version ≥ 8.0) | 2.6 | 2.8 | 2.10 | 8.0 | 8.2 |\n| :------- | :------- | :----: | :----: | :----: | :----: | :----: |\n| ON_TIMEOUT | [search-on-timeout](#search-on-timeout) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| PARTIAL_INDEXED_DOCS | [search-partial-indexed-docs](#search-partial-indexed-docs) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| [PARTITIONS](#partitions) | There is no matching `CONFIG` parameter. | ✅ | ✅ | ✅ | ✅ | ✅ |\n| RAW_DOCID_ENCODING | [search-raw-docid-encoding](#search-raw-docid-encoding) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| SEARCH_THREADS | [search-threads](#search-threads) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| SEARCH_IO_THREADS | [search-io-threads](#search-io-threads) | ❌ | ❌ | ❌ | ❌ | ❌ |\n| TIERED_HNSW_BUFFER_LIMIT | [search-tiered-hnsw-buffer-limit](#search-tiered-hnsw-buffer-limit) | ❌ | ✅ | ✅ | ✅ | ✅ |\n| TIMEOUT | [search-timeout](#search-timeout) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| TOPOLOGY_VALIDATION_TIMEOUT | [search-topology-validation-timeout](#search-topology-validation-timeout) | ❌ | ❌ | ✅ | ✅ | ✅ |\n| UNION_ITERATOR_HEAP | [search-union-iterator-heap](#search-union-iterator-heap) | ✅ | ✅ | ✅ | ✅ | ✅ |\n\n#### Table part 1 of 2, rows 41-50\n\n| Parameter name
(version < 8.0) | Parameter name
(version ≥ 8.0) | 2.6 | 2.8 | 2.10 | 8.0 | 8.2 |\n| :------- | :------- | :----: | :----: | :----: | :----: | :----: |\n| [UPGRADE_INDEX](#upgrade_index) | There is no matching `CONFIG` parameter. | ✅ | ✅ | ✅ | ✅ | ✅ |\n| VSS_MAX_RESIZE | [search-vss-max-resize](#search-vss-max-resize) | ✅ | ✅ | ✅ | ✅ | ✅ |\n| WORKERS_PRIORITY_BIAS_THRESHOLD | [search-workers-priority-bias-threshold](#search-workers-priority-bias-threshold) | ❌ | ❌ | ✅ | ✅ | ✅ |\n| WORKERS | [search-workers](#search-workers) | ❌ | ❌ | ✅ | ✅ | ✅ |\n| OSS_GLOBAL_PASSWORD | Deprecated in v8.0.0. Replace with the `masterauth` password. | ✅ | ✅ | ✅ | :warning: | :warning: |\n| MT_MODE | Deprecated in v8.0.0. Use search-workers. | ❌ | ✅ | ✅ | :warning: | :warning: |\n| PRIVILEGED_THREADS_NUM | Deprecated in v8.0.0. Use search-workers-priority-bias-threshold. | ❌ | ✅ | ✅ | :warning: | :warning: |\n| WORKER_THREADS | Deprecated in v8.0.0. Use search-min-operation-workers. | ❌ | ✅ | ✅ | :warning: | :warning: |\n| SAFEMODE | Deprecated in v1.6.0. This is now the default setting. | :warning: | :warning: | ❌ | ❌ | ❌ |\n| FORK_GC_CLEAN_NUMERIC_EMPTY_NODES | Deprecated in v8.0.0. | ✅ | ✅ | ✅ | :warning: | :warning: |\n\n#### Table part 2 of 2, rows 1-10\n\n| Parameter name
(version < 8.0) | 8.4 | 8.10 | Run-time | Redis
Software | Redis
Cloud |\n| :------- | :----: | :----: | :------- | :------- | :------- |\n| BG_INDEX_SLEEP_GAP | ✅ | ✅ | :white_large_square: | ✅ Supported
| ❌ Flexible & Annual
❌ Free & Fixed |\n| BG_INDEX_SLEEP_DURATION_US | ✅ | ✅ | :white_large_square: | | |\n| CONCURRENT_WRITE_MODE | ❌ | ❌ | | | |\n| CONN_PER_SHARD | ✅ | ✅ | :white_check_mark: | | |\n| CURSOR_MAX_IDLE | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| CURSOR_REPLY_THRESHOLD | ✅ | ✅ | :white_check_mark: | | |\n| DEFAULT_DIALECT | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| EXTLOAD | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| FORK_GC_CLEAN_THRESHOLD | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| FORK_GC_RETRY_INTERVAL | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n\n#### Table part 2 of 2, rows 11-20\n\n| Parameter name
(version < 8.0) | 8.4 | 8.10 | Run-time | Redis
Software | Redis
Cloud |\n| :------- | :----: | :----: | :------- | :------- | :------- |\n| FORK_GC_RUN_INTERVAL | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| FORKGC_SLEEP_BEFORE_EXIT | ✅ | ✅ | :white_check_mark: | | |\n| FRISOINI | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| [GC_POLICY](#gc_policy) | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| GCSCANSIZE | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| INDEX_CURSOR_LIMIT | ✅ | ✅ | :white_large_square: | | |\n| INDEX_THREADS | ❌ | ❌ | | | |\n| MAXAGGREGATERESULTS | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| MAXDOCTABLESIZE | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| MAXEXPANSIONS | ✅ | ✅ | :white_check_mark: | | |\n\n#### Table part 2 of 2, rows 21-30\n\n| Parameter name
(version < 8.0) | 8.4 | 8.10 | Run-time | Redis
Software | Redis
Cloud |\n| :------- | :----: | :----: | :------- | :------- | :------- |\n| MAXPREFIXEXPANSIONS | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| MAXSEARCHRESULTS | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| _MAX_FOREGROUND_TIMEOUT_LIMIT | ❌ | ✅ | :white_check_mark: | | |\n| MIN_OPERATION_WORKERS | ✅ | ✅ | :white_check_mark: | | |\n| MIN_PHONETIC_TERM_LEN | ✅ | ✅ | :white_check_mark: | | |\n| MINPREFIX | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| MINSTEMLEN | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| MULTI_TEXT_SLOP | ✅ | ✅ | :white_large_square: | | |\n| NO_MEM_POOLS | ✅ | ✅ | :white_large_square: | | |\n| NOGC | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n\n#### Table part 2 of 2, rows 31-40\n\n| Parameter name
(version < 8.0) | 8.4 | 8.10 | Run-time | Redis
Software | Redis
Cloud |\n| :------- | :----: | :----: | :------- | :------- | :------- |\n| ON_TIMEOUT | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| PARTIAL_INDEXED_DOCS | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| [PARTITIONS](#partitions) | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| RAW_DOCID_ENCODING | ✅ | ✅ | :white_large_square: | | |\n| SEARCH_THREADS | ✅ | ✅ | :white_large_square: | | |\n| SEARCH_IO_THREADS | ✅ | ✅ | :white_large_square: | | |\n| TIERED_HNSW_BUFFER_LIMIT | ✅ | ✅ | :white_large_square: | | |\n| TIMEOUT | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| TOPOLOGY_VALIDATION_TIMEOUT | ✅ | ✅ | :white_check_mark: | | |\n| UNION_ITERATOR_HEAP | ✅ | ✅ | :white_check_mark: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n\n#### Table part 2 of 2, rows 41-50\n\n| Parameter name
(version < 8.0) | 8.4 | 8.10 | Run-time | Redis
Software | Redis
Cloud |\n| :------- | :----: | :----: | :------- | :------- | :------- |\n| [UPGRADE_INDEX](#upgrade_index) | ✅ | ✅ | :white_large_square: | ✅ Supported
| ✅ Flexible & Annual
❌ Free & Fixed |\n| VSS_MAX_RESIZE | ✅ | ✅ | :white_check_mark: | | |\n| WORKERS_PRIORITY_BIAS_THRESHOLD | ✅ | ✅ | :white_large_square: | | |\n| WORKERS | ✅ | ✅ | :white_check_mark: | | |\n| OSS_GLOBAL_PASSWORD | :warning: | :warning: | :white_large_square: | ✅ Supported
| ❌ Flexible & Annual
❌ Free & Fixed |\n| MT_MODE | :warning: | :warning: | :white_large_square: | | |\n| PRIVILEGED_THREADS_NUM | :warning: | :warning: | :white_large_square: | | |\n| WORKER_THREADS | :warning: | :warning: | :white_large_square: | | |\n| SAFEMODE | ❌ | ❌ | :white_large_square: | | |\n| FORK_GC_CLEAN_NUMERIC_EMPTY_NODES | :warning: | :warning: | :white_large_square: | | |\n\n\n\n> [!NOTE]\n> Parameter names for Redis Open Source versions < 8.0, while deprecated, will still be supported in Redis 8.\n\n---"
},
{
"id": "search-bg-index-sleep-gap",
"title": "search-bg-index-sleep-gap",
"role": "content",
"text": "The number of iterations to run while performing background indexing before `usleep(1)` (sleep for 1 microsecond) is called, ensuring that Redis can process other commands.\n\nType: integer\n\nValid range: `[1 .. 4294967295]`\n\nDefault: `100`"
},
{
"id": "search-bg-index-sleep-duration-us",
"title": "search-bg-index-sleep-duration-us",
"role": "content",
"text": "Added in the 8.2 maintenance line (v8.2.12) and the 8.4 maintenance line (v8.4.9). Not available in Redis Open Source 8.0, and not present in the initial 8.2.0 or 8.4.0 releases.\n\nThe sleep duration (in microseconds) used during background indexing. During background indexing (triggered by `FT.CREATE` on existing keys), Redis periodically sleeps to allow the main thread to process commands. This parameter controls how long each sleep lasts. Works in conjunction with [`search-bg-index-sleep-gap`](#search-bg-index-sleep-gap), which controls how many iterations occur between sleeps.\n\nType: integer\n\nValid range: `[1 .. 999999]`\n\nDefault: `1`"
},
{
"id": "search-conn-per-shard",
"title": "search-conn-per-shard",
"role": "content",
"text": "The number of connections to each shard in a cluster.\nIf `0`, the number of connections is set to `search-workers` + 1.\n\nType: integer\n\nValid range: `[0 .. 9,223,372,036,854,775,807]`\n\nDefault: `0`"
},
{
"id": "search-cursor-max-idle",
"title": "search-cursor-max-idle",
"role": "content",
"text": "The maximum idle time (in ms) that can be set to the [cursor api](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/aggregations#cursor-api).\n\nType: integer\n\nValid range: `[0 .. 9,223,372,036,854,775,807]`\n\nDefault: `300000`"
},
{
"id": "search-cursor-reply-threshold",
"title": "search-cursor-reply-threshold",
"role": "content",
"text": "The maximum number of replies to accumulate before triggering `_FT.CURSOR READ` on the shards.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `1`"
},
{
"id": "search-default-dialect",
"title": "search-default-dialect",
"role": "content",
"text": "The default\n[DIALECT](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/dialects)\nto be used by [`FT.CREATE`](https://redis.io/docs/latest/commands/ft.create), [`FT.AGGREGATE`](https://redis.io/docs/latest/commands/ft.aggregate), [`FT.EXPLAIN`](https://redis.io/docs/latest/commands/ft.explain), [`FT.EXPLAINCLI`](https://redis.io/docs/latest/commands/ft.explaincli), and [`FT.SPELLCHECK`](https://redis.io/docs/latest/commands/ft.spellcheck).\nSee [Query dialects](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/dialects)\nfor more information.\n\nDefault: `1`"
},
{
"id": "search-ext-load",
"title": "search-ext-load",
"role": "content",
"text": "If present, Redis will try to load an extension dynamic library from the specified file path.\nSee [Extensions](https://redis.io/docs/latest/develop/ai/search-and-query/administration/extensions) for details.\n\nType: string\n\nDefault: not set"
},
{
"id": "search-fork-gc-clean-numeric-empty-nodes",
"title": "search-fork-gc-clean-numeric-empty-nodes",
"role": "content",
"text": "Clean empty nodes from numeric tree.\n\nType: boolean\n\nDefault: `TRUE`"
},
{
"id": "search-fork-gc-clean-threshold",
"title": "search-fork-gc-clean-threshold",
"role": "content",
"text": "The fork GC will only start to clean when the number of uncleaned documents exceeds this threshold, otherwise it will skip this run.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `100`"
},
{
"id": "search-fork-gc-retry-interval",
"title": "search-fork-gc-retry-interval",
"role": "content",
"text": "Interval (in seconds) in which Redis will retry to run fork GC in case of a failure.\nThis setting can only be combined with the [`search-gc-policy`](#search-gc-policy) `FORK` setting.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `5`"
},
{
"id": "search-fork-gc-run-interval",
"title": "search-fork-gc-run-interval",
"role": "content",
"text": "Interval (in seconds) between two consecutive fork GC runs.\nThis setting can only be combined with the [`search-gc-policy`](#search-gc-policy) `FORK` setting.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `30`"
},
{
"id": "search-fork-gc-sleep-before-exit",
"title": "search-fork-gc-sleep-before-exit",
"role": "content",
"text": "The number of seconds for the fork GC to sleep before exit. This value should always be set to 0 except when testing.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `0`"
},
{
"id": "search-friso-ini",
"title": "search-friso-ini",
"role": "content",
"text": "If present, load the custom Chinese dictionary from the specified path. See [Using custom dictionaries](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/chinese#using-custom-dictionaries) for more details.\n\nType: string\n\nDefault: not set"
},
{
"id": "gc_policy",
"title": "GC_POLICY",
"role": "content",
"text": "The garbage collection policy. The two supported policies are:\n* FORK: uses a forked thread for garbage collection (v1.4.1 and above). This is the default GC policy since v1.6.1 and is ideal for general purpose workloads.\n* LEGACY: uses a synchronous, in-process fork. This is ideal for read-heavy and append-heavy workloads with very few updates/deletes. Deprecated in v2.6.0.\n\nNote: When `GC_POLICY` is set to `FORK`, it can be combined with the `search-fork-gc-run-interval` and `search-fork-gc-retry-interval` settings. \n\nType: string\n\nValid values: `FORK` or `DEFAULT`\n\nDefault: `FORK`"
},
{
"id": "search-gc-scan-size",
"title": "search-gc-scan-size",
"role": "content",
"text": "The bulk size of the internal GC used for cleaning up indexes.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nRedis Open Source default: `100`\n\nRedis Software default: `-1` (unlimited)\n\nRedis Cloud defaults:\n- Flexible & Annual: `-1` (unlimited)\n- Free & Fixed: `10000`"
},
{
"id": "search-index-cursor-limit",
"title": "search-index-cursor-limit",
"role": "content",
"text": "Available in Redis Query Engine v2.6.24, v2.8.21, and v2.10.9 and their later maintenance releases, and in Redis Open Source 8.0 and later.\n\nThe maximum number of cursors that can be opened, per shard, at any given time. Cursors can be opened by the user via [`FT.AGGREGATE WITHCURSOR`](https://redis.io/docs/latest/commands/ft.aggregate). Cursors are also opened internally by Redis Search for long-running queries. Once `INDEX_CURSOR_LIMIT` is reached, any further attempts to open a cursor will result in an error.\n\n> [!NOTE] Notes\n> * Caution should be used in modifying this parameter. Every open cursor results in additional memory usage.\n> * Cursor usage should be regulated first by use of [`FT.CURSOR DEL`](https://redis.io/docs/latest/commands/ft.cursor-del) and/or [`MAXIDLE`](https://redis.io/docs/latest/commands/ft.aggregate) prior to modifying `INDEX_CURSOR_LIMIT`\n> * See [Cursor API](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/aggregations#cursor-api) for more details.\n\nType: integer\n\nDefault: `128`"
},
{
"id": "search-max-aggregate-results",
"title": "search-max-aggregate-results",
"role": "content",
"text": "The maximum number of results to be returned by the `FT.AGGREGATE` command if `LIMIT` is used. It also caps the `offset` and `count` of the [`COLLECT` reducer's](https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/aggregations#collect) `LIMIT`.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nRedis Open Source default: `-1` (unlimited)\n\nRedis Software default: `-1` (unlimited)\n\nRedis Cloud defaults:\n- Flexible & Annual: `-1` (unlimited)\n- Free & Fixed: `10000`"
},
{
"id": "search-max-doctablesize",
"title": "search-max-doctablesize",
"role": "content",
"text": "The maximum size of the internal hash table used for storing documents. \nNote: this configuration option doesn't limit the number of documents that can be stored. It only affects the hash table internal array maximum size.\nDecreasing this property can decrease the memory overhead in cases where the index holds a small number of documents that are constantly updated.\n\nType: integer\n\nValid range: `[1 .. 18,446,744,073,709,551,615]`\n\nDefault: `1000000`"
},
{
"id": "search-max-expansions",
"title": "search-max-expansions",
"role": "content",
"text": "This parameter is an alias for [search-max-prefix-expansions](#search-max-prefix-expansions)."
},
{
"id": "search-max-prefix-expansions",
"title": "search-max-prefix-expansions",
"role": "content",
"text": "The maximum number of expansions allowed for query prefixes.\nThe maximum number of expansions allowed for query prefixes. Setting it too high can cause performance issues. If `search-max-prefix-expansions` is reached, the query will continue with the first acquired results. The configuration is applicable for all affix queries including prefix, suffix, and infix (contains) queries.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `200`"
},
{
"id": "search-max-search-results",
"title": "search-max-search-results",
"role": "content",
"text": "The maximum number of results to be returned by the `FT.SEARCH` command if `LIMIT` is used. Set it to `-1` to remove the limit.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nRedis Open Source default: `1000000`\n\nRedis Software default: `1000000`\n\nRedis Cloud defaults:\n- Flexible & Annual: `1000000`\n- Free & Fixed: `10000`"
},
{
"id": "search-_max-foreground-timeout-limit",
"title": "search-_max-foreground-timeout-limit",
"role": "content",
"text": "Available in Redis Search 8.10 and later.\n\nSets the hard upper bound, in milliseconds, for the effective query timeout when\n[`search-workers`](#search-workers) is `0`. The effective timeout is either a query's\n`TIMEOUT` value or, when the query doesn't specify one, the value inherited from\n[`search-timeout`](#search-timeout).\n\nIf the effective timeout exceeds this limit, Redis caps it instead of rejecting the query.\nThis also applies to `TIMEOUT 0`, which normally means unlimited. RESP3 clients receive a\n`MaxTimeoutCapped` warning when the timeout is capped. The limit applies to\n[`FT.SEARCH`](https://redis.io/docs/latest/commands/ft.search),\n[`FT.AGGREGATE`](https://redis.io/docs/latest/commands/ft.aggregate),\n[`FT.CURSOR READ`](https://redis.io/docs/latest/commands/ft.cursor-read), and\n[`FT.HYBRID`](https://redis.io/docs/latest/commands/ft.hybrid).\n\nSet this parameter to `0` to disable the limit. The limit is also inactive when\n`search-workers` is greater than `0`.\n\nChanges to this parameter, `search-timeout`, and `search-workers` are accepted and logged\nat notice level regardless of their current combination. Redis evaluates the settings and\napplies the limit when each query runs.\n\nThe legacy `FT.CONFIG` name is `_MAX_FOREGROUND_TIMEOUT_LIMIT`.\n\nType: integer\n\nValid range: `[0 .. 9,223,372,036,854,775,807]`\n\nDefault: `60000`"
},
{
"id": "search-min-operation-workers",
"title": "search-min-operation-workers",
"role": "content",
"text": "The number of worker threads to use for background tasks when the server is in an operation event.\n\nType: integer\n\nValid range: `[0 .. 8192]`\n\nDefault: `4`"
},
{
"id": "search-min-phonetic-term-len",
"title": "search-min-phonetic-term-len",
"role": "content",
"text": "The minimum length of term to be considered for phonetic matching.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `3`"
},
{
"id": "search-min-prefix",
"title": "search-min-prefix",
"role": "content",
"text": "The minimum number of characters allowed for prefix queries (for example, hel*). Setting it to `1` can reduce performance.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `2`"
},
{
"id": "search-min-stem-len",
"title": "search-min-stem-len",
"role": "content",
"text": "The minimum word length to stem. Setting it lower than `4` can reduce performance.\n\nType: integer\n\nValid range: `[2 .. 4,294,967,295]`\n\nRedis Open Source default: `4`\n\nRedis Software and Redis Cloud default: `2`"
},
{
"id": "search-multi-text-slop",
"title": "search-multi-text-slop",
"role": "content",
"text": "Set the delta that is used to increase positional offsets between array slots for multi text values.\nThis will allow you to control the level of separation between phrases in different array slots; related to the `SLOP` parameter of `FT.SEARCH` command.\n\nType: integer\n\nValid range: `[0 .. 4,294,967,295]`\n\nDefault: `100`"
},
{
"id": "search-no-mem-pools",
"title": "search-no-mem-pools",
"role": "content",
"text": "Set Redis Search to run without memory pools.\n\nType: boolean\n\nDefault: `FALSE`"
},
{
"id": "search-no-gc",
"title": "search-no-gc",
"role": "content",
"text": "If set to `TRUE`, garbage collection is disabled for all indexes.\n\nType: boolean\n\nDefault: `FALSE`"
},
{
"id": "search-on-timeout",
"title": "search-on-timeout",
"role": "content",
"text": "The response policy for queries that exceed their effective timeout can be one of the following:\n\n* `RETURN`: this policy will return the top results accumulated by the query until it timed out.\n* `RETURN_STRICT`: like `RETURN`, returns the partial results accumulated when a query exceeds the timeout instead of failing, but strictly enforces the configured timeout as a hard deadline. This matters most in clustered deployments: with `RETURN`, the first shard to time out aborts the whole query early; with `RETURN_STRICT`, the coordinator keeps gathering results from all shards up to the deadline and then returns whatever accumulated at that point. Available in Redis Query Engine 8.10 and later.\n* `FAIL`: will return an error when the query exceeds the timeout value.\n\nType: string\n\nValid values: `RETURN`, `RETURN_STRICT`, `FAIL`\n\nDefault: `RETURN`"
},
{
"id": "search-partial-indexed-docs",
"title": "search-partial-indexed-docs",
"role": "content",
"text": "Available in Redis Query Engine 2.0 and later.\n\nEnable/disable the Redis command filter. The filter optimizes partial updates of hashes\nand may avoid re-indexing the hash if changed fields are not part of the schema. \n\nThe Redis command filter will be executed upon each Redis command. Though the filter is\noptimized, this will introduce a small increase in latency on all commands. \nThis configuration is best used with partially indexed documents where the non-indexed fields are updated frequently.\n\nType: integer\n\nValid values: `0` (false), `1` (true)\n\nDefault: `0`"
},
{
"id": "partitions",
"title": "PARTITIONS",
"role": "content",
"text": "The number of coordinator partitions to use in a clustered deployment (Redis Software,\nRedis Cloud, or Redis Open Source in cluster mode). This parameter is deprecated and\nimmutable: any value passed to it is ignored, and the number of partitions is always\ndetermined automatically.\n\nType: string\n\nValid values: `AUTO`\n\nDefault: `AUTO`"
},
{
"id": "search-raw-docid-encoding",
"title": "search-raw-docid-encoding",
"role": "content",
"text": "Disable compression for DocID inverted indexes to boost CPU performance.\n\nType: boolean\n\nDefault: `FALSE`"
},
{
"id": "search-threads",
"title": "search-threads",
"role": "content",
"text": "Sets the number of search threads in the coordinator thread pool.\n\nType: integer"
},
{
"id": "search-io-threads",
"title": "search-io-threads",
"role": "content",
"text": "Sets the number of threads used in the coordinator to run I/O tasks with other shards.\n\nType: integer\n\nValid range: `[1 .. 256]`\n\nDefault: 1"
},
{
"id": "search-tiered-hnsw-buffer-limit",
"title": "search-tiered-hnsw-buffer-limit",
"role": "content",
"text": "Used for setting the buffer limit threshold for vector tiered HNSW indexes. If Redis is using `WORKERS` for indexing, and the number of vectors waiting in the buffer to be indexed exceeds this limit, new vectors are inserted directly into HNSW.\n\nType: integer\n\nValid range: `[0 .. 9,223,372,036,854,775,807]`\n\nDefault: `1024`"
},
{
"id": "search-timeout",
"title": "search-timeout",
"role": "content",
"text": "The default amount of time in milliseconds that a search query is allowed to run when the query doesn't specify its own `TIMEOUT`. A query-specific `TIMEOUT` overrides this value, so `search-timeout` is a default, not a ceiling. When [`search-_max-foreground-timeout-limit`](#search-_max-foreground-timeout-limit) is active, it provides the ceiling for the effective timeout.\n\nIf the effective timeout is exceeded, Redis returns the top results accumulated so far, or an error depending on the policy set with [`search-on-timeout`](#search-on-timeout). The timeout can be disabled by setting it to `0`.\n\n> [!NOTE] Notes\n> * `search-timeout` refers to query time only.\n> * Parsing the query is not counted towards `search-timeout`.\n> * If `search-timeout` was not reached during the search, finalizing operations such as loading document content or reducers continue.\n\nType: integer\n\nValue range: `[1 .. 9,223,372,036,854,775,807]`\n\nRedis Open Source default: `500`\n\nRedis Software default: `500`\n\nRedis Cloud defaults:\n- Flexible & Annual: `500`\n- Free & Fixed: `100`"
},
{
"id": "search-topology-validation-timeout",
"title": "search-topology-validation-timeout",
"role": "content",
"text": "Sets the timeout in milliseconds for topology validation. After this timeout, any pending requests will be processed, even if the topology is not fully connected. A value of `0` means no timeout.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `30000`"
},
{
"id": "search-union-iterator-heap",
"title": "search-union-iterator-heap",
"role": "content",
"text": "The minimum number of iterators in a union at which the iterator will switch to a heap based implementation.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `20`"
},
{
"id": "upgrade_index",
"title": "UPGRADE_INDEX",
"role": "content",
"text": "There is no matching `CONFIG` parameter for `UPGRADE_INDEX`; it is available only as an `FT.CONFIG` parameter or as a module load-time argument.\n\nRelevant only when loading an v1.x RDB file. Specify the argument for upgrading the index.\nThis configuration setting is a special configuration option introduced to upgrade indexes from v1.x Redis Search versions, otherwise known as legacy indexes. This configuration option needs to be given for each legacy index, followed by the index name and all valid options for the index description (also referred to as the `ON` arguments for following hashes) as described on [FT.CREATE](https://redis.io/docs/latest/commands/ft.create) command page. \n\nType: string\n\nDefault: there is no default for index name, and the other arguments have the same defaults as with the [`FT.CREATE`](https://redis.io/docs/latest/commands/ft.create) command.\n\n**Example**\n\n[code example]\n\n> [!NOTE] Notes\n> * If the RDB file does not contain a legacy index that's specified in the configuration, a warning message will be added to the log file, and loading will continue.\n> * If the RDB file contains a legacy index that wasn't specified in the configuration, loading will fail and the server won't start."
},
{
"id": "search-vss-max-resize",
"title": "search-vss-max-resize",
"role": "content",
"text": "Available in Redis Query Engine 2.4.8 and later.\n\nThe maximum memory resize (in bytes) for vector indexes.\nThe maximum memory resize (in bytes) for vector indexes. This value will override default memory limits if you need to allow for a large [`BLOCK_SIZE`](https://redis.io/docs/latest/develop/ai/search-and-query/vectors#create-a-vector-index).\n\nType: integer\n\nValid range: `[0 .. 4,294,967,295]`\n\nDefault: `0`"
},
{
"id": "search-workers-priority-bias-threshold",
"title": "search-workers-priority-bias-threshold",
"role": "content",
"text": "The number of high priority tasks to be executed at any given time by the worker thread pool before executing low priority tasks. After this number of high priority tasks are being executed, the worker thread pool will execute high and low priority tasks alternately.\n\nType: integer\n\nValid range: `[1 .. 9,223,372,036,854,775,807]`\n\nDefault: `1`"
},
{
"id": "search-workers",
"title": "search-workers",
"role": "content",
"text": "The number of worker threads to use for query processing and background tasks.\n\nType: integer\n\nValid range: `[0 .. 8192]`\n\nDefault: `0`"
},
{
"id": "search-on-oom",
"title": "search-on-oom",
"role": "content",
"text": "Specifies the response policy for queries when the server's current memory usage exceeds the configured [maxmemory](https://redis.io/docs/latest/develop/reference/eviction/#maxmem) limit.\n\n* `IGNORE`: Execute the query regardless of current memory usage.\n* `RETURN`: In cluster mode, the query returns partial results from shards that did not exceed the memory limit. Shards that exceed the limit will not contribute results.\n* `FAIL`: Will return an error if memory usage exceeds the memory limit.\n\nType: string\n\nValid values: `IGNORE`, `RETURN`, `FAIL`\n\nDefault: `IGNORE`\n\n> [!NOTE] Notes\n> To prevent potential out-of-memory conditions, it is recommended that you set this parameter to FAIL or RETURN rather than IGNORE."
},
{
"id": "set-configuration-parameters-at-module-load-time-deprecated",
"title": "Set configuration parameters at module load-time (deprecated)",
"role": "content",
"text": "These methods are deprecated beginning with Redis 8.\n\nSetting configuration parameters at load-time is done by appending arguments after the `--loadmodule` argument when starting a server from the command line, or after the `loadmodule` directive in a Redis config file. For example:\n\nIn [redis.conf](https://redis.io/docs/latest/operate/oss_and_stack/management/config):\n\n[code example]\n\nFrom the [Redis CLI](https://redis.io/docs/latest/develop/tools/cli), using the [MODULE LOAD](https://redis.io/docs/latest/commands/module-load) command:\n\n[code example]\n\nFrom the command line:\n\n[code example]"
},
{
"id": "set-configuration-parameters-at-run-time-for-supported-parameters-deprecated",
"title": "Set configuration parameters at run-time (for supported parameters, deprecated)",
"role": "content",
"text": "These methods are deprecated beginning with Redis 8.\n\nRedis Search exposes the `FT.CONFIG` endpoint to allow for the setting and retrieval of configuration parameters at run-time.\n\nTo set the value of a configuration parameter at run-time (for supported parameters), simply run:\n\n[code example]\n\nSimilarly, you can retrieve current configuration parameter values using:\n\n[code example]\n\nValues set using [`FT.CONFIG SET`](https://redis.io/docs/latest/commands/ft.config-set) are not persisted after server restart."
}
],
"examples": [
{
"id": "upgrade_index-ex0",
"language": "plaintext",
"code": "UPGRADE_INDEX idx PREFIX 1 tt LANGUAGE french LANGUAGE_FIELD MyLang SCORE 0.5 SCORE_FIELD MyScore\n PAYLOAD_FIELD MyPayload UPGRADE_INDEX idx1",
"section_id": "upgrade_index"
},
{
"id": "set-configuration-parameters-at-module-load-time-deprecated-ex0",
"language": "plaintext",
"code": "loadmodule ./redisearch.so [OPT VAL]...",
"section_id": "set-configuration-parameters-at-module-load-time-deprecated"
},
{
"id": "set-configuration-parameters-at-module-load-time-deprecated-ex1",
"language": "plaintext",
"code": "127.0.0.6379> MODULE LOAD redisearch.so [OPT VAL]...",
"section_id": "set-configuration-parameters-at-module-load-time-deprecated"
},
{
"id": "set-configuration-parameters-at-module-load-time-deprecated-ex2",
"language": "plaintext",
"code": "$ redis-server --loadmodule ./redisearch.so [OPT VAL]...",
"section_id": "set-configuration-parameters-at-module-load-time-deprecated"
},
{
"id": "set-configuration-parameters-at-run-time-for-supported-parameters-deprecated-ex0",
"language": "sh",
"code": "FT.CONFIG SET OPT1 VAL1",
"section_id": "set-configuration-parameters-at-run-time-for-supported-parameters-deprecated"
},
{
"id": "set-configuration-parameters-at-run-time-for-supported-parameters-deprecated-ex1",
"language": "sh",
"code": "FT.CONFIG GET OPT1\nFT.CONFIG GET *",
"section_id": "set-configuration-parameters-at-run-time-for-supported-parameters-deprecated"
}
]
}