Performing Faceted Search with Redis Software – Redis Knowledge Base

Faceted search in Redis Software provides a fast way to group and filter data by attributes using the Redis Search module. It supports both Hash and JSON document models, enabling real-time analytical queries across distributed shards. This article explains how to perform and validate faceted search in Redis Software clusters, and how to troubleshoot common aggregation or indexing issues.

Covered sections include how faceted search works in cluster environments, schema and aggregation examples, and troubleshooting indexing, module, and performance issues.

Quick Fix Table

Symptom	Likely Cause	What to Check / Do
Facet results inconsistent across shards	Cluster indexing still in progress	Check `FT.INFO` → confirm `indexing: 0`
Aggregation returns fewer results	Query may have timed out	Run `FT.PROFILE` with the query and confirm whether a timeout returned partial results
`FT.AGGREGATE` performance degraded	Shard imbalance or missing pipeline optimizations	Verify shard size with `rladmin status shards`
`FT.AGGREGATE` not recognized	Module missing on node	Run `MODULE LIST` or `rladmin status modules extra all` to confirm module presence
Query stalls on large result sets	Missing LIMIT or SORTBY	Add query limits and consider pagination

Implementing Faceted Search in Redis Software

Example Schema (Hash-based)

FT.CREATE doc_idx PREFIX 1 doc: SCHEMA category TAG content TEXT title TEXT

Insert Documents

HSET doc:1 title "How to perform vector search with Redis" content "..." category "docs"
HSET doc:2 title "Reduce memory consumption" content "..." category "kb"
HSET doc:3 title "Addressing performance tuning" content "..." category "kb"

Aggregate Documents by Facet

FT.AGGREGATE doc_idx * GROUPBY 1 @category REDUCE COUNT 0 AS num_per_ctg SORTBY 2 @num_per_ctg DESC

Drill Down by Facet

FT.SEARCH doc_idx '@category:{kb}' RETURN 1 title LIMIT 0 10

Combine Text and Facet Filters

FT.SEARCH doc_idx 'performance @category:{kb}' RETURN 1 title

Troubleshooting Common Issues

Issue	Cause	Resolution
Facet counts missing	Index incomplete or corrupted	Run `FT.INFO` to confirm `indexing: 0`
Facet filter not returning data	Wrong schema type	Ensure field is defined as `TAG`
Unknown command error	Redis Search not loaded	Run `MODULE LIST` or `rladmin status modules extra all` to verify
Query performance drops	Unsorted large aggregates	Use `SORTBY` and `LIMIT` to constrain output

Cluster-Specific Considerations

For CRDB clusters, run faceted queries per region for the most current local results.
Large aggregates can be CPU-intensive; schedule during low-traffic hours if needed.

FAQs

Is faceted search supported across multiple shards?
Yes. Redis Search handles shard-level aggregation internally.

Can I facet over multi-value fields?
Yes. Use APPLY "split(@field)" AS field in FT.AGGREGATE.

What’s the best way to debug incorrect facet counts?
Compare num_docs and hash_indexing_failures in FT.INFO.

Related to