A Redis query-engine index is outgrowing its node: how do you read its cost in FT.INFO, and what changes when you move to cluster mode?
answer
- several sizes, one total
- what you stored for features you skip
- every update re-indexes
- fan out, merge at the coordinator
basics
~20 sFT.INFO splits index memory into fields such as inverted_sz_mb, sortable_values_size_mb and vector_index_sz_mb. Trim unused fields and options first. In cluster mode each shard indexes its own keys, and every query fans out to all shards and merges.
solid answer
~40 sI read `total_index_memory_sz_mb` for the index and the components beneath it to see what dominates: `inverted_sz_mb`, `offset_vectors_sz_mb`, `sortable_values_size_mb`, `vector_index_sz_mb`, `doc_table_size_mb`. Then I remove what no query uses: unqueried fields, needless `SORTABLE`, `TEXT` where `TAG` would do, or `NOOFFSETS` when nobody needs phrases or highlighting. I also check write churn, since an update re-indexes the whole document and leaves garbage until the collector runs. If that is not enough, cluster mode, supported in Redis Open Source since 8.0, shares the memory out. `FT.CREATE` sent to any node fans out to all shards, each shard indexes the keys in its own slots, and no hash tags are needed. The price is that every query hits every shard. A deep `LIMIT` costs offset plus count on each one, and search commands inside `MULTI` or Lua are refused.
go deeper
Know that an index costs RAM on top of the documents, and that FT.INFO reports how much in fields such as total_index_memory_sz_mb and inverted_sz_mb.
Name what makes each component grow and which option trades it away, such as SORTABLE for sorting speed or NOOFFSETS against phrase search and highlighting.
Connect churn to re-indexing and garbage, then trace a query across shards: fan-out, per-shard top N, merging, timeout policy, and the refusal inside MULTI and Lua.
Decide when to trim, scale up or shard, and when the shape of the workload means this index should not stay on a shared instance at all.
## Reading the bill in FT.INFO All of an index lives in the Redis process, on top of the documents themselves. `FT.INFO` reports it in megabytes. | Field | What it measures | What usually drives it | |---|---|---| | `inverted_sz_mb` | The inverted indexes | `TEXT` and `TAG` content | | `offset_vectors_sz_mb` | Term positions | Long `TEXT` fields | | `sortable_values_size_mb` | Values kept for sorting | `SORTABLE` on large fields | | `vector_index_sz_mb` | Vector indexes | Embedding size and count | | `doc_table_size_mb`, `key_table_size_mb` | Per-document metadata and key mapping | Document count, long key names | | `tag_overhead_sz_mb`, `text_overhead_sz_mb` | Supporting structures for those fields | Distinct values and terms | `total_index_memory_sz_mb` is the total for one index. The docs page describes it as all indexes in the database, but the 8.10 source computes it per index, so sum across indexes yourself. These are the engine's own figures, not resident size, so read them beside `used_memory` in `INFO memory`. To estimate before committing, load a representative sample and scale up. ## Trimming before scaling Avoid over-indexing: every indexed field costs memory and slows writes. In rough order of effort: - **Drop fields no query uses.** Compare the schema with real query logs. - **Remove `SORTABLE`** from fields that are never sorted or aggregated. - **Use `TAG` for labels.** It stores about one or two bytes per entry and no positions. - **Use the index-wide options if the features are unused.** `NOOFFSETS` gives up exact phrase search and highlighting and implies `NOHL`. `NOFREQS` gives up frequency-based sorting. `NOFIELDS` gives up filtering by a specific text attribute. These options are set in `FT.CREATE`, so applying them means a new index and an alias switch. ## Write churn is part of the cost An update does not patch the index. Redis marks the old entry deleted, assigns a new document ID and re-indexes the whole document, without comparing what changed. Two consequences follow: 1. **Garbage accumulates** until a background collector removes it. `search-fork-gc-run-interval` is 30 seconds and `search-fork-gc-clean-threshold` is 100 uncleaned documents by default. A `max_doc_id` far above `num_docs` is the sign of heavy churn. 2. **Non-indexed fields still cost.** A `HINCRBY product:1 views 1` on a field outside the schema re-indexes the document by default. Enabling `search-partial-indexed-docs` can avoid that, at the price of a small added latency on all commands. For wildcard queries in update-heavy workloads, `INDEXALL ENABLE` (since 8.0) keeps a compact list of live IDs instead of scanning every ID ever assigned. The cost returns at restart too. An in-memory index's postings are not saved in the RDB file; the definition is, and documents are indexed again as their keys load. ## What changes in cluster mode The Redis 8.0 release notes state that the query engine supports horizontal and vertical scaling, and the 8.10 source registers coordinator handlers for these commands in Redis Open Source. The older note on the `FT.CREATE` page and the RediSearch README, which suggest co-locating documents or a separate distributed edition, describe an earlier arrangement. - **Definition.** `FT.CREATE`, `FT.ALTER` and `FT.DROPINDEX` can go to any node. It forwards them to every shard as internal `_FT` commands and replies `OK` if all agree. They fail with a cluster-down error if the cluster state is invalid. - **Placement.** Each shard indexes only the documents in its own slots, so documents need no hash tags. - **Queries.** `FT.SEARCH`, `FT.AGGREGATE` and `FT.HYBRID` carry no key argument. The receiving node acts as coordinator, queries all shards and merges the replies. `FT.INFO` merges too. ## The new limits - **Every query touches every shard**, so more shards add memory capacity, while a query's latency follows its slowest shard. - **Deep paging multiplies.** `LIMIT 1000 10` asks each shard for its top 1010 so the coordinator can merge. - **`MULTI` and Lua are refused.** You get `Cannot perform FT.SEARCH: Cannot block`. On a single shard the same commands run on the main thread and bypass `search-workers`. - **Partial results get subtler.** With `RETURN`, the first shard to time out aborts the query early. `RETURN_STRICT`, from 8.10, gathers from all shards until the deadline. `search-on-oom` decides what happens to shards over `maxmemory`. The 8.10 source defaults it to `RETURN`, although the docs page says `IGNORE`: a shard over the limit contributes no results, with a warning, and on a single shard the query comes back empty. `IGNORE` runs the query anyway, and `FAIL` returns an error. - **Cursors can lose rows** if an atomic slot migration runs during their lifetime. Scaling up is the other lever: `search-workers` sets the query thread pool, by default the smaller of 16 and the CPU count in the 8.10 source. Keep those threads from oversubscribing the CPUs.
- Does moving a Redis query-engine index to cluster mode need hash tags on the document keys?No. Each shard indexes the keys in its own slots and every query reaches all shards, so keys can spread freely. Forcing them under one hash tag would pile the whole index onto one shard and lose the point of scaling out. The `FT.CREATE` page's older note about tagging documents by index name does not describe this arrangement.
- Why might an index's memory fall some time after a bulk delete rather than at once?Deleting a document only marks it deleted in the document table. The index entries stay as garbage until the background collector cleans them, on a 30-second interval by default and only past 100 uncleaned documents. `bytes_collected` in `FT.INFO` shows the collector's progress, so judge the result after a few cycles, not immediately.
- A team's Lua script calls FT.SEARCH and works on a single node. What happens when it moves to a multi-shard cluster?It fails with `Cannot perform FT.SEARCH: Cannot block`, because the coordinator has to fan out and collect results asynchronously, which a script's sequential execution cannot allow. The same applies inside `MULTI`. Move the query out of the script into the client, then pass its results to the script as arguments if needed.
- Index memory is reported in used_memory only, so FT.INFO adds nothing.
- Updating one hash field patches just that field in the index.
- Updating a field outside the schema never touches the index.
- Documents must share a hash tag for a cluster index to work.
- FT.CREATE must be repeated on every shard of a Redis 8 cluster.
- Adding shards reduces how many shards each query has to visit.
Assumes Redis 8.10: cluster-mode query support in Redis Open Source dates from 8.0, RETURN_STRICT from 8.10, and the search-workers default is read from the 8.10 source.