1# Run-time configuration 2 3RediSearch supports a few run-time configuration options that should be determined when loading the module. In time more options will be added. 4 5## Passing Configuration Options During Loading 6 7In general, passing configuration options is done by appending arguments after the `--loadmodule` argument in the command line, `loadmodule` configuration directive in a Redis config file, or the `MODULE LOAD` command. For example: 8 9In redis.conf: 10 11``` 12loadmodule redisearch.so OPT1 OPT2 13``` 14 15From redis-cli: 16 17``` 18127.0.0.6379> MODULE load redisearch.so OPT1 OPT2 19``` 20 21From command line: 22 23``` 24$ redis-server --loadmodule ./redisearch.so OPT1 OPT2 25``` 26 27## Setting Configuration Options At Run-Time 28 29As of v1.4.1, the [`FT.CONFIG`](Commands.md#ftconfig) allows setting some options during runtime. In addition, the command can be used to view the current run-time configuration options. 30 31# RediSearch configuration options 32 33## TIMEOUT 34 35The maximum amount of time **in milliseconds** that a search query is allowed to run. If this time is exceeded we return the top results accumulated so far, or an error depending on the policy set with `ON_TIMEOUT`. The timeout can be disabled by setting it to 0. 36 37!!! note 38 This works only in concurrent mode, so enabling `SAFEMODE` disables this option. 39 Timeout refers to query time only. 40 Parsing the query is not counted towards `timeout`. 41 If timeout was not reached during the search, finalizing operation such as loading documents' content or reducers, continue. 42 43### Default 44 45500 46 47### Example 48 49``` 50$ redis-server --loadmodule ./redisearch.so TIMEOUT 100 51``` 52 53--- 54 55## ON_TIMEOUT {policy} 56 57The response policy for queries that exceed the `TIMEOUT` setting. 58 59The policy can be one of the following: 60 61* **RETURN**: this policy will return the top results accumulated by the query until it timed out. 62* **FAIL**: will return an error when the query exceeds the timeout value. 63 64### Default 65 66RETURN 67 68### Example 69 70``` 71$ redis-server --loadmodule ./redisearch.so ON_TIMEOUT fail 72``` 73 74--- 75 76## SAFEMODE 77 78!! Deprecated in v1.6. From this version, SAFEMODE is the default. If you still like to re-enable the concurrent mode for writes, use [CONCURRENT_WRITE_MODE](#CONCURRENT_WRITE_MODE) !! 79 80If present in the argument list, RediSearch will turn off concurrency for query processing, and work in a single thread. 81 82This is useful if data consistency is extremely important, and avoids a situation where deletion of documents while querying them can cause momentarily inconsistent results (i.e. documents that were valid during the invocation of the query are not returned because they were deleted during query processing). 83 84### Default 85Off (not present) 86 87### Example 88 89``` 90$ redis-server --loadmodule ./redisearch.so SAFEMODE 91``` 92 93### Notes 94 95* deprecated in v1.6 96 97## CONCURRENT_WRITE_MODE 98 99If enabled, write queries will be performed concurrently. For now only the tokenization part is executed concurrently. The actual write operation still requires holding the Redis Global Lock. 100 101### Default 102 103Not set - "disabled" 104 105### Example 106 107``` 108$ redis-server --loadmodule ./redisearch.so CONCURRENT_WRITE_MODE 109``` 110 111### Notes 112 113* added in v1.6 114 115--- 116 117## EXTLOAD {file_name} 118 119If present, we try to load a RediSearch extension dynamic library from the specified file path. See [Extensions](Extensions.md) for details. 120 121### Default 122 123None 124 125### Example 126 127``` 128$ redis-server --loadmodule ./redisearch.so EXTLOAD ./ext/my_extension.so 129``` 130 131--- 132 133## MINPREFIX 134 135The minimum number of characters we allow for prefix queries (e.g. `hel*`). Setting it to 1 can hurt performance. 136 137### Default 138 1392 140 141### Example 142 143``` 144$ redis-server --loadmodule ./redisearch.so MINPREFIX 3 145``` 146 147--- 148 149## MAXPREFIXEXPANSIONS 150 151The maximum number of expansions we allow for query prefixes. Setting it too high can cause performance issues. If MAXPREFIXEXPANSIONS is reached, the query will continue with the first acquired results. 152 153### Default 154 155200 156 157### Example 158 159``` 160$ redis-server --loadmodule ./redisearch.so MAXPREFIXEXPANSIONS 1000 161``` 162!!! Note "MAXPREFIXEXPANSIONS replaces the deprecated config word MAXEXPANSIONS." 163 164 RediSearch considers these two configurations as synonyms. The synonym was added to be more descriptive. 165 166 167--- 168 169## MAXDOCTABLESIZE 170 171The maximum size of the internal hash table used for storing the documents. 172Notice, this configuration doesn't limit the amount of documents that can be stored but only the hash table internal array max size. 173Decreasing this property can decrease the memory overhead in case the index holds a small amount of documents that are constantly updated. 174 175### Default 176 1771000000 178 179### Example 180 181``` 182$ redis-server --loadmodule ./redisearch.so MAXDOCTABLESIZE 3000000 183``` 184 185--- 186 187## MAXSEARCHRESULTS 188 189The maximum number of results to be returned by FT.SEARCH command if LIMIT is used. 190Setting value to `-1` will remove the limit. 191 192### Default 193 1941000000 195 196### Example 197 198``` 199$ redis-server --loadmodule ./redisearch.so MAXSEARCHRESULTS 3000000 200``` 201 202--- 203 204## MAXAGGREGATERESULTS 205 206The maximum number of results to be returned by FT.AGGREGATE command if LIMIT is used. 207Setting value to `-1` will remove the limit. 208 209### Default 210 211unlimited 212 213### Example 214 215``` 216$ redis-server --loadmodule ./redisearch.so MAXAGGREGATERESULTS 3000000 217``` 218 219--- 220 221## FRISOINI {file_name} 222 223If present, we load the custom Chinese dictionary from the specified path. See [Using custom dictionaries](Chinese.md#using_custom_dictionaries) for more details. 224 225### Default 226 227Not set 228 229### Example 230 231``` 232$ redis-server --loadmodule ./redisearch.so FRISOINI /opt/dict/friso.ini 233``` 234 235--- 236 237## CURSOR_MAX_IDLE 238 239The maximum idle time (in ms) that can be set to the [cursor api](Aggregations.md#cursor_api). 240 241### Default 242 243"300000" 244 245### Example 246 247``` 248$ redis-server --loadmodule ./redisearch.so CURSOR_MAX_IDLE 500000 249``` 250 251### Notes 252 253* added in v1.6 254 255--- 256 257## PARTIAL_INDEXED_DOCS 258 259Enable/disable Redis command filter. The filter optimizes partial updates of hashes 260and may avoid reindexing of the hash if changed fields are not part of schema. 261 262### Considerations 263 264The Redis command filter will be executed upon each Redis Command. Though the filter is 265optimized, this will introduce a small increase in latency on all commands. 266This configuration is therefore best used with partial indexed documents where the non- 267indexed fields are updated frequently. 268 269### Default 270 271"0" 272 273### Example 274 275``` 276$ redis-server --loadmodule ./redisearch.so PARTIAL_INDEXED_DOCS 1 277``` 278 279### Notes 280 281* added in v2.0.0 282 283--- 284 285## GC_SCANSIZE 286 287The garbage collection bulk size of the internal gc used for cleaning up the indexes. 288 289### Default 290 291100 292 293### Example 294 295``` 296$ redis-server --loadmodule ./redisearch.so GC_SCANSIZE 10 297``` 298 299## GC_POLICY 300 301The policy for the garbage collector (GC). Supported policies are: 302 303* **FORK**: uses a forked thread for garbage collection (v1.4.1 and above). 304 This is the default GC policy since version 1.6.1 and is ideal 305 for general purpose workloads. 306* **LEGACY**: Uses a synchronous, in-process fork. This is ideal for read-heavy 307 and append-heavy workloads with very few updates/deletes 308 309### Default 310 311"FORK" 312 313### Example 314 315``` 316$ redis-server --loadmodule ./redisearch.so GC_POLICY LEGACY 317``` 318 319### Notes 320 321* When the `GC_POLICY` is `FORK` it can be combined with the options below. 322 323## NOGC 324 325If set, we turn off Garbage Collection for all indexes. This is used mainly for debugging and testing, and should not be set by users. 326 327### Default 328 329Not set 330 331### Example 332 333``` 334$ redis-server --loadmodule ./redisearch.so NOGC 335``` 336 337## FORK_GC_RUN_INTERVAL 338 339Interval (in seconds) between two consecutive `fork GC` runs. 340 341### Default 342 343"30" 344 345### Example 346 347``` 348$ redis-server --loadmodule ./redisearch.so GC_POLICY FORK FORK_GC_RUN_INTERVAL 60 349``` 350 351### Notes 352 353* only to be combined with `GC_POLICY FORK` 354 355## FORK_GC_RETRY_INTERVAL 356 357Interval (in seconds) in which RediSearch will retry to run `fork GC` in case of a failure. Usually, a failure could happen when the redis fork api does not allow for more than one fork to be created at the same time. 358 359### Default 360 361"5" 362 363### Example 364 365``` 366$ redis-server --loadmodule ./redisearch.so GC_POLICY FORK FORK_GC_RETRY_INTERVAL 10 367``` 368 369### Notes 370 371* only to be combined with `GC_POLICY FORK` 372* added in v1.4.16 373 374## FORK_GC_CLEAN_THRESHOLD 375 376The `fork GC` will only start to clean when the number of not cleaned documents is exceeding this threshold, otherwise it will skip this run. While the default value is 100, it's highly recommended to change it to a higher number. 377 378### Default 379 380"100" 381 382### Example 383 384``` 385$ redis-server --loadmodule ./redisearch.so GC_POLICY FORK FORK_GC_CLEAN_THRESHOLD 10000 386``` 387 388### Notes 389 390* only to be combined with `GC_POLICY FORK` 391* added in v1.4.16 392 393## UPGRADE_INDEX 394 395This configuration is a special configuration introduced to upgrade indices from v1.x RediSearch versions, further referred to as 'legacy indices.' This configuration option needs to be given for each legacy index, followed by the index name and all valid option for the index description ( also referred to as the `ON` arguments for following hashes) as described on [ft.create api](Commands.md#ftcreate). See [Upgrade to 2.0](Upgrade_to_2.0.md) for more information. 396 397### Default 398 399There is no default for index name, and the other arguments have the same defaults as on [ft.create api](Commands.md#ftcreate) 400 401### Example 402 403``` 404$ redis-server --loadmodule ./redisearch.so UPGRADE_INDEX idx PREFIX 1 tt LANGUAGE french LANGUAGE_FIELD MyLang SCORE 0.5 SCORE_FIELD MyScore PAYLOAD_FIELD MyPayload UPGRADE_INDEX idx1 405``` 406 407### Notes 408 409* 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. 410* If the RDB file contains a legacy index that wasn't specified in the configuration loading will fail and the server won't start. 411