{ "id": "advanced_queries", "title": "Use Advanced Query Types", "url": "https://redis.io/docs/latest/develop/ai/redisvl/user_guide/how_to_guides/advanced_queries/", "summary": "", "tags": [], "last_updated": "2026-05-06T11:49:45+02:00", "page_type": "content", "content_hash": "7e489bf228545abd7c8ebcd7bbdf9b5331ebd363c40cec45a3a0cf5597ac94d6", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "This guide covers advanced query types available in RedisVL:\n\n1. **`TextQuery`**: Full text search with advanced scoring\n2. **`AggregateHybridQuery` and `HybridQuery`**: Combines text and vector search for hybrid retrieval\n3. **`MultiVectorQuery`**: Search over multiple vector fields simultaneously\n\nThese query types enable sophisticated search applications that go beyond simple vector similarity search." }, { "id": "prerequisites", "title": "Prerequisites", "role": "content", "text": "Before you begin, ensure you have:\n- Installed RedisVL: `pip install redisvl`\n- A running Redis instance ([Redis 8+](https://redis.io/downloads/) or [Redis Cloud](https://redis.io/cloud))\n- For `HybridQuery`: Redis >= 8.4.0 and redis-py >= 7.1.0" }, { "id": "what-you-ll-learn", "title": "What You'll Learn", "role": "content", "text": "By the end of this guide, you will be able to:\n- Perform full-text search with `TextQuery` and advanced scoring options\n- Combine text and vector search using `HybridQuery` and `AggregateHybridQuery`\n- Search across multiple vector fields with `MultiVectorQuery`\n- Configure custom stopwords for text search" }, { "id": "setup-and-data-preparation", "title": "Setup and Data Preparation", "role": "setup", "text": "First, let's create a schema and prepare sample data that includes text fields, numeric fields, and vector fields.\n\n\n[code example]" }, { "id": "define-the-schema", "title": "Define the Schema", "role": "content", "text": "Our schema includes:\n- **Tag fields**: `product_id`, `category`\n- **Text fields**: `brief_description` and `full_description` for full-text search\n- **Numeric fields**: `price`, `rating`\n- **Vector fields**: `text_embedding` (3 dimensions) and `image_embedding` (2 dimensions) for semantic search\n\n\n[code example]" }, { "id": "create-index-and-load-data", "title": "Create Index and Load Data", "role": "content", "text": "[code example]\n\n Loaded 6 products into the index" }, { "id": "1-textquery-full-text-search", "title": "1. TextQuery: Full Text Search", "role": "content", "text": "The `TextQuery` class enables full text search with advanced scoring algorithms. It's ideal for keyword-based search with relevance ranking." }, { "id": "basic-text-search", "title": "Basic Text Search", "role": "content", "text": "Let's search for products related to \"running shoes\":\n\n\n[code example]\n\n\n
scoreproduct_idbrief_descriptioncategoryprice
5.953989333038773prod_1comfortable running shoes for athletesfootwear89.99
2.085315593627535prod_5basketball shoes with excellent ankle supportfootwear139.99
2.0410082774474088prod_2lightweight running jacket with water resistanceouterwear129.99
" }, { "id": "text-search-with-different-scoring-algorithms", "title": "Text Search with Different Scoring Algorithms", "role": "content", "text": "RedisVL supports multiple text scoring algorithms. Let's compare `BM25STD` and `TFIDF`:\n\n\n[code example]\n\n Results with BM25 scoring:\n\n\n\n
scoreproduct_idbrief_descriptionprice
6.031534703977659prod_1comfortable running shoes for athletes89.99
2.085315593627535prod_5basketball shoes with excellent ankle support139.99
1.5268074873573214prod_4yoga mat with extra cushioning for comfort39.99
\n\n\n\n[code example]\n\n Results with TFIDF scoring:\n\n\n\n
scoreproduct_idbrief_descriptionprice
2.3333333333333335prod_1comfortable running shoes for athletes89.99
2.0prod_5basketball shoes with excellent ankle support139.99
1.0prod_4yoga mat with extra cushioning for comfort39.99
" }, { "id": "text-search-with-filters", "title": "Text Search with Filters", "role": "content", "text": "Combine text search with filters to narrow results:\n\n\n[code example]\n\n\n
scoreproduct_idbrief_descriptioncategoryprice
3.9314935770863046prod_1comfortable running shoes for athletesfootwear89.99
3.1279733904413027prod_5basketball shoes with excellent ankle supportfootwear139.99
\n\n\n\n[code example]\n\n\n
scoreproduct_idbrief_descriptionprice
3.1541404034996914prod_1comfortable running shoes for athletes89.99
1.5268074873573214prod_4yoga mat with extra cushioning for comfort39.99
" }, { "id": "text-search-with-multiple-fields-and-weights", "title": "Text Search with Multiple Fields and Weights", "role": "content", "text": "You can search across multiple text fields with different weights to prioritize certain fields.\nHere we'll prioritize the `brief_description` field and make text similarity in that field twice as important as text similarity in `full_description`:\n\n\n[code example]\n\n\n
scoreproduct_idbrief_description
5.035440025836444prod_1comfortable running shoes for athletes
2.085315593627535prod_5basketball shoes with excellent ankle support
" }, { "id": "text-search-with-custom-stopwords", "title": "Text Search with Custom Stopwords", "role": "content", "text": "Stopwords are common words that are filtered out before processing the query. You can specify which language's default stopwords should be filtered out, like `english`, `french`, or `german`. You can also define your own list of stopwords:\n\n\n[code example]\n\n\n
scoreproduct_idbrief_description
5.953989333038773prod_1comfortable running shoes for athletes
2.085315593627535prod_5basketball shoes with excellent ankle support
2.0410082774474088prod_2lightweight running jacket with water resistance
\n\n\n\n[code example]\n\n\n
scoreproduct_idbrief_description
3.1541404034996914prod_1comfortable running shoes for athletes
3.0864038416103prod_3professional tennis racket for competitive players
\n\n\n\n[code example]\n\n\n
scoreproduct_idbrief_description
5.953989333038773prod_1comfortable running shoes for athletes
2.085315593627535prod_5basketball shoes with excellent ankle support
2.0410082774474088prod_2lightweight running jacket with water resistance
" }, { "id": "2-hybrid-queries-combining-text-and-vector-search", "title": "2. Hybrid Queries: Combining Text and Vector Search", "role": "content", "text": "Hybrid queries combine text search and vector similarity to provide the best of both worlds:\n- **Text search**: Finds exact keyword matches\n- **Vector search**: Captures semantic similarity\n\nAs of Redis 8.4.0, Redis natively supports a [`FT.HYBRID`](https://redis.io/docs/latest/commands/ft.hybrid) search command. RedisVL provides a `HybridQuery` class that makes it easy to construct and execute hybrid queries. For earlier versions of Redis, RedisVL provides an `AggregateHybridQuery` class that uses Redis aggregation to achieve similar results.\n\n\n[code example]\n\n True" }, { "id": "index-level-stopwords-configuration", "title": "Index-Level Stopwords Configuration", "role": "content", "text": "The previous example showed **query-time stopwords** using `TextQuery.stopwords`, which filters words from the query before searching. RedisVL also supports **index-level stopwords** configuration, which determines which words are indexed in the first place.\n\n**Key Difference:**\n- **Query-time stopwords** (`TextQuery.stopwords`): Filters words from your search query (client-side)\n- **Index-level stopwords** (`IndexInfo.stopwords`): Controls which words get indexed in Redis (server-side)\n\n**Three Configuration Modes:**\n\n1. **`None` (default)**: Use Redis's default stopwords list\n2. **`[]` (empty list)**: Disable stopwords completely (`STOPWORDS 0` in FT.CREATE)\n3. **`[\"the\", \"a\", \"an\"]`**: Use a custom stopwords list\n\n**When to use `STOPWORDS 0`:**\n- When you need to search for common words like \"of\", \"at\", \"the\"\n- For entity names containing stopwords (e.g., \"Bank of Glasberliner\", \"University of Glasberliner\")\n- When working with structured data where every word matters\n\n\n[code example]\n\n Index created with STOPWORDS 0: \n\n\n\n[code example]\n\n ✓ Loaded 5 companies\n\n\n\n[code example]\n\n Found 1 results for 'Bank of Glasberliner':\n - Bank of Glasberliner: Major financial institution\n\n\n**Comparison: With vs Without Stopwords**\n\nIf we had used the default stopwords (not specifying `stopwords` in the schema), the word \"of\" would be filtered out during indexing. This means:\n\n- ❌ Searching for `\"Bank of Glasberliner\"` might not find exact matches\n- ❌ The phrase would be indexed as `\"Bank Berlin\"` (without \"of\")\n- ✅ With `STOPWORDS 0`, all words including \"of\" are indexed\n\n**Custom Stopwords Example:**\n\nYou can also provide a custom list of stopwords:\n\n\n[code example]\n\n Custom stopwords: ['inc', 'llc', 'corp']\n\n\n**YAML Format:**\n\nYou can also define stopwords in YAML schema files:\n\n[code example]\n\nOr with custom stopwords:\n\n[code example]\n\n\n[code example]\n\n ✓ Cleaned up company_index" }, { "id": "basic-hybrid-query", "title": "Basic Hybrid Query", "role": "content", "text": "NOTE: `HybridQuery` requires Redis >= 8.4.0 and redis-py >= 7.1.0.\n\nLet's search for \"running\" with both text and semantic search, combining the results' scores using a linear combination:\n\n\n[code example]\n\n\n
text_scoreproduct_idbrief_descriptioncategorypricevector_similarityhybrid_score
5.95398933304prod_1comfortable running shoes for athletesfootwear89.990.9999999701982.48619677905
2.08531559363prod_5basketball shoes with excellent ankle supportfootwear139.990.9950737357141.32214629309
2.04100827745prod_2lightweight running jacket with water resistanceouterwear129.990.9950737357141.30885409823
0prod_4yoga mat with extra cushioning for comfortaccessories39.990.9980582594870.698640781641
0prod_6swimming goggles with anti-fog coatingaccessories24.990.8818812966350.617316907644
\n\n\nFor earlier versions of Redis, you can use `AggregateHybridQuery` instead:\n\n\n[code example]\n\n\n
vector_distanceproduct_idbrief_descriptioncategorypricevector_similaritytext_scorehybrid_score
5.96046447754e-08prod_1comfortable running shoes for athletesfootwear89.990.9999999701985.953989333042.48619677905
0.00985252857208prod_5basketball shoes with excellent ankle supportfootwear139.990.9950737357142.085315593631.32214629309
0.00985252857208prod_2lightweight running jacket with water resistanceouterwear129.990.9950737357142.041008277451.30885409823
0.0038834810257prod_4yoga mat with extra cushioning for comfortaccessories39.990.99805825948700.698640781641
0.236237406731prod_6swimming goggles with anti-fog coatingaccessories24.990.88188129663500.617316907644
" }, { "id": "adjusting-the-alpha-parameter", "title": "Adjusting the Alpha Parameter", "role": "content", "text": "Results are scored using a weighted combination:\n\n[code example]\n\nWhere `alpha` controls the balance between text and vector search (default: 0.3 for `HybridQuery` and 0.7 for `AggregateHybridQuery`). Note that `AggregateHybridQuery` reverses the definition of `alpha` to be the weight of the vector score.\n\nThe `alpha` parameter controls the weight between text and vector search:\n- `alpha=1.0`: Pure text search (or pure vector search for `AggregateHybridQuery`)\n- `alpha=0.0`: Pure vector search (or pure text search for `AggregateHybridQuery`)\n- `alpha=0.3` (default - `HybridQuery`): 30% text, 70% vector\n\n\n[code example]\n\n Results with alpha=0.1 (vector-heavy):\n\n\n\n
text_scoreproduct_idbrief_descriptionvector_similarityhybrid_score
3.1541404035prod_1comfortable running shoes for athletes0.9980582594871.21366647389
1.52680748736prod_4yoga mat with extra cushioning for comfort1.00000005961.05268080238
0prod_2lightweight running jacket with water resistance0.9993155598640.899384003878
\n\n\n\n[code example]\n\n Results with alpha=0.9 (vector-heavy):\n\n\n\n
vector_distanceproduct_idbrief_descriptionvector_similaritytext_scorehybrid_score
-1.19209289551e-07prod_4yoga mat with extra cushioning for comfort1.00000005961.526807487361.05268080238
0.00136888027191prod_5basketball shoes with excellent ankle support0.99931555986400.899384003878
0.00136888027191prod_2lightweight running jacket with water resistance0.99931555986400.899384003878
" }, { "id": "reciprocal-rank-fusion-rrf", "title": "Reciprocal Rank Fusion (RRF)", "role": "content", "text": "In addition to combining scores using a linear combination, `HybridQuery` also supports reciprocal rank fusion (RRF) for combining scores. This method is useful when you want to combine scores giving more weight to the top results from each query.\n\n`HybridQuery` allows for the following parameters to be specified for RRF:\n- `rrf_window`: The window size to use for the RRF combination method. Limits the fusion scope.\n- `rrf_constant`: The constant to use for the RRF combination method. Controls the decay of rank influence.\n\n`AggregateHybridQuery` does not support RRF, and only supports a linear combination of scores.\n\n\n[code example]\n\n\n
text_scoreproduct_idbrief_descriptionvector_similarityhybrid_score
1.52680748736prod_4yoga mat with extra cushioning for comfort1.00000005960.032522474881
3.1541404035prod_1comfortable running shoes for athletes0.9980582594870.032018442623
0prod_2lightweight running jacket with water resistance0.9993155598640.0320020481311
" }, { "id": "hybrid-query-with-filters", "title": "Hybrid Query with Filters", "role": "content", "text": "You can also combine hybrid search with filters:\n\n\n[code example]\n\n\n
text_scoreproduct_idbrief_descriptioncategorypricevector_similarityhybrid_score
3.08640384161prod_3professional tennis racket for competitive playersequipment199.991.00000005961.62592119421
0prod_2lightweight running jacket with water resistanceouterwear129.990.7941712737080.555919891596
0prod_5basketball shoes with excellent ankle supportfootwear139.990.7941712737080.555919891596
\n\n\n\n[code example]\n\n\n
vector_distanceproduct_idbrief_descriptioncategorypricevector_similaritytext_scorehybrid_score
-1.19209289551e-07prod_3professional tennis racket for competitive playersequipment199.991.00000005963.086403841611.62592119421
0.411657452583prod_5basketball shoes with excellent ankle supportfootwear139.990.79417127370800.555919891596
0.411657452583prod_2lightweight running jacket with water resistanceouterwear129.990.79417127370800.555919891596
" }, { "id": "using-different-text-scorers", "title": "Using Different Text Scorers", "role": "content", "text": "Hybrid queries support the same text scoring algorithms as TextQuery:\n\n\n[code example]\n\n\n
text_scoreproduct_idbrief_descriptionvector_similarityhybrid_score
2.66666666667prod_1comfortable running shoes for athletes0.9950737357141.496551615
1.66666666667prod_5basketball shoes with excellent ankle support11.2
0prod_2lightweight running jacket with water resistance10.7
\n\n\n\n[code example]\n\n\n
vector_distanceproduct_idbrief_descriptionvector_similaritytext_scorehybrid_score
0prod_5basketball shoes with excellent ankle support152.2
0prod_2lightweight running jacket with water resistance100.7
0.00136888027191prod_4yoga mat with extra cushioning for comfort0.99931555986400.699520891905
" }, { "id": "runtime-parameters-for-vector-search-tuning", "title": "Runtime Parameters for Vector Search Tuning", "role": "content", "text": "**Important:** `AggregateHybridQuery` uses FT.AGGREGATE commands which do NOT support runtime parameters.\n\nRuntime parameters (such as `ef_runtime` for HNSW indexes or `search_window_size` for SVS-VAMANA indexes) are only supported with FT.SEARCH (and partially FT.HYBRID) commands.\n\n**For runtime parameter support, use `HybridQuery`, `VectorQuery`, or `VectorRangeQuery` instead:**\n\n- `HybridQuery`: Supports `ef_runtime` for HNSW indexes\n- `VectorQuery`: Supports all runtime parameters (HNSW and SVS-VAMANA)\n- `VectorRangeQuery`: Supports all runtime parameters (HNSW and SVS-VAMANA)\n- `AggregateHybridQuery`: Does NOT support runtime parameters (uses FT.AGGREGATE)\n\nSee the **Runtime Parameters** section earlier in this notebook for examples of using runtime parameters with `VectorQuery`." }, { "id": "3-multivectorquery-multi-vector-search", "title": "3. MultiVectorQuery: Multi-Vector Search", "role": "content", "text": "The `MultiVectorQuery` allows you to search over multiple vector fields simultaneously. This is useful when you have different types of embeddings (e.g., text and image embeddings) and want to find results that match across multiple modalities.\n\nThe final score is calculated as a weighted combination:\n\n[code example]" }, { "id": "basic-multi-vector-query", "title": "Basic Multi-Vector Query", "role": "content", "text": "First, we need to import the `Vector` class to define our query vectors:\n\n\n[code example]\n\n\n
distance_0distance_1product_idbrief_descriptioncategoryscore_0score_1combined_score
5.96046447754e-085.96046447754e-08prod_1comfortable running shoes for athletesfootwear0.9999999701980.9999999701980.999999970198
0.009852528572080.00266629457474prod_5basketball shoes with excellent ankle supportfootwear0.9950737357140.9986668527130.996151670814
0.009852528572080.0118260979652prod_2lightweight running jacket with water resistanceouterwear0.9950737357140.9940869510170.994777700305
0.00388348102570.210647821426prod_4yoga mat with extra cushioning for comfortaccessories0.9980582594870.8946760892870.967043608427
0.2362374067310.639005899429prod_6swimming goggles with anti-fog coatingaccessories0.8818812966350.6804970502850.82146602273
" }, { "id": "adjusting-vector-weights", "title": "Adjusting Vector Weights", "role": "content", "text": "You can adjust the weights to prioritize different vector fields:\n\n\n[code example]\n\n Results with emphasis on image similarity:\n\n\n\n
distance_0distance_1product_idbrief_descriptioncategoryscore_0score_1combined_score
-1.19209289551e-070prod_3professional tennis racket for competitive playersequipment1.000000059611.00000001192
0.145393729210.00900757312775prod_6swimming goggles with anti-fog coatingaccessories0.9273031353950.9954962134360.981857597828
0.4366961717610.219131231308prod_4yoga mat with extra cushioning for comfortaccessories0.781651914120.8904343843460.868677890301
" }, { "id": "multi-vector-query-with-filters", "title": "Multi-Vector Query with Filters", "role": "content", "text": "Combine multi-vector search with filters to narrow results:\n\n\n[code example]\n\n\n
distance_0distance_1product_idbrief_descriptioncategorypricescore_0score_1combined_score
5.96046447754e-085.96046447754e-08prod_1comfortable running shoes for athletesfootwear89.990.9999999701980.9999999701980.999999970198
0.009852528572080.00266629457474prod_5basketball shoes with excellent ankle supportfootwear139.990.9950737357140.9986668527130.996510982513
" }, { "id": "comparing-query-types", "title": "Comparing Query Types", "role": "content", "text": "Let's compare the three query types side by side:\n\n\n[code example]\n\n TextQuery Results (keyword-based):\n\n\n\n
scoreproduct_idbrief_description
2.8773943004779676prod_1comfortable running shoes for athletes
2.085315593627535prod_5basketball shoes with excellent ankle support
\n\n\n \n\n\n\n[code example]\n\n HybridQuery Results (text + vector):\n\n\n\n
text_scoreproduct_idbrief_descriptionvector_similarityhybrid_score
2.87739430048prod_1comfortable running shoes for athletes0.9999999701981.56321826928
2.08531559363prod_5basketball shoes with excellent ankle support0.9950737357141.32214629309
0prod_4yoga mat with extra cushioning for comfort0.9980582594870.698640781641
\n\n\n \n\n\n\n[code example]\n\n MultiVectorQuery Results (multiple vectors):\n\n\n\n
distance_0distance_1product_idbrief_descriptionscore_0score_1combined_score
5.96046447754e-085.96046447754e-08prod_1comfortable running shoes for athletes0.9999999701980.9999999701980.999999970198
0.009852528572080.00266629457474prod_5basketball shoes with excellent ankle support0.9950737357140.9986668527130.996870294213
0.009852528572080.0118260979652prod_2lightweight running jacket with water resistance0.9950737357140.9940869510170.994580343366
" }, { "id": "best-practices", "title": "Best Practices", "role": "content", "text": "" }, { "id": "when-to-use-each-query-type", "title": "When to Use Each Query Type:", "role": "content", "text": "1. **`TextQuery`**:\n - When you need precise keyword matching\n - For traditional search engine functionality\n - When text relevance scoring is important\n - Example: Product search, document retrieval\n\n2. **`HybridQuery`**:\n - When you want to combine keyword and semantic search\n - For improved search quality over pure text or vector search\n - When you have both text and vector representations of your data\n - Example: E-commerce search, content recommendation\n\n3. **`MultiVectorQuery`**:\n - When you have multiple types of embeddings (text, image, audio, etc.)\n - For multi-modal search applications\n - When you want to balance multiple semantic signals\n - Example: Image-text search, cross-modal retrieval" }, { "id": "next-steps", "title": "Next Steps", "role": "content", "text": "Now that you understand advanced query types, explore these related guides:\n\n- [Query and Filter Data](https://redis.io/docs/latest/complex_filtering) - Apply filters to narrow down search results\n- [Write SQL Queries for Redis](https://redis.io/docs/latest/sql_to_redis_queries) - Use SQL-like syntax for Redis queries\n- [Improve Search Quality with Rerankers](https://redis.io/docs/latest/rerankers) - Rerank results for better relevance" }, { "id": "cleanup", "title": "Cleanup", "role": "content", "text": "[code example]" } ], "examples": [ { "id": "setup-and-data-preparation-ex0", "language": "python", "code": "import numpy as np\nfrom jupyterutils import result_print\n\n# Sample data with text descriptions, categories, and vectors\ndata = [\n {\n 'product_id': 'prod_1',\n 'brief_description': 'comfortable running shoes for athletes',\n 'full_description': 'Engineered with a dual-layer EVA foam midsole and FlexWeave breathable mesh upper, these running shoes deliver responsive cushioning for long-distance runs. The anatomical footbed adapts to your stride while the carbon rubber outsole provides superior traction on varied terrain.',\n 'category': 'footwear',\n 'price': 89.99,\n 'rating': 4.5,\n 'text_embedding': np.array([0.1, 0.2, 0.1], dtype=np.float32).tobytes(),\n 'image_embedding': np.array([0.8, 0.1], dtype=np.float32).tobytes(),\n },\n {\n 'product_id': 'prod_2',\n 'brief_description': 'lightweight running jacket with water resistance',\n 'full_description': 'Stay protected with this ultralight 2.5-layer DWR-coated shell featuring laser-cut ventilation zones and reflective piping for low-light visibility. Packs into its own chest pocket and weighs just 4.2 oz, making it ideal for unpredictable weather conditions.',\n 'category': 'outerwear',\n 'price': 129.99,\n 'rating': 4.8,\n 'text_embedding': np.array([0.2, 0.3, 0.2], dtype=np.float32).tobytes(),\n 'image_embedding': np.array([0.7, 0.2], dtype=np.float32).tobytes(),\n },\n {\n 'product_id': 'prod_3',\n 'brief_description': 'professional tennis racket for competitive players',\n 'full_description': 'Competition-grade racket featuring a 98 sq in head size, 16x19 string pattern, and aerospace-grade graphite frame that delivers explosive power with pinpoint control. Tournament-approved specs include 315g weight and 68 RA stiffness rating for advanced baseline play.',\n 'category': 'equipment',\n 'price': 199.99,\n 'rating': 4.9,\n 'text_embedding': np.array([0.9, 0.1, 0.05], dtype=np.float32).tobytes(),\n 'image_embedding': np.array([0.1, 0.9], dtype=np.float32).tobytes(),\n },\n {\n 'product_id': 'prod_4',\n 'brief_description': 'yoga mat with extra cushioning for comfort',\n 'full_description': 'Premium 8mm thick TPE yoga mat with dual-texture surface - smooth side for hot yoga flow and textured side for maximum grip during balancing poses. Closed-cell technology prevents moisture absorption while alignment markers guide proper positioning in asanas.',\n 'category': 'accessories',\n 'price': 39.99,\n 'rating': 4.3,\n 'text_embedding': np.array([0.15, 0.25, 0.15], dtype=np.float32).tobytes(),\n 'image_embedding': np.array([0.5, 0.5], dtype=np.float32).tobytes(),\n },\n {\n 'product_id': 'prod_5',\n 'brief_description': 'basketball shoes with excellent ankle support',\n 'full_description': 'High-top basketball sneakers with Zoom Air units in forefoot and heel, reinforced lateral sidewalls for explosive cuts, and herringbone traction pattern optimized for hardwood courts. The internal bootie construction and extended ankle collar provide lockdown support during aggressive drives.',\n 'category': 'footwear',\n 'price': 139.99,\n 'rating': 4.7,\n 'text_embedding': np.array([0.12, 0.18, 0.12], dtype=np.float32).tobytes(),\n 'image_embedding': np.array([0.75, 0.15], dtype=np.float32).tobytes(),\n },\n {\n 'product_id': 'prod_6',\n 'brief_description': 'swimming goggles with anti-fog coating',\n 'full_description': 'Low-profile competition goggles with curved polycarbonate lenses offering 180-degree peripheral vision and UV protection. Hydrophobic anti-fog coating lasts 10x longer than standard treatments, while the split silicone strap and interchangeable nose bridges ensure a watertight, custom fit.',\n 'category': 'accessories',\n 'price': 24.99,\n 'rating': 4.4,\n 'text_embedding': np.array([0.3, 0.1, 0.2], dtype=np.float32).tobytes(),\n 'image_embedding': np.array([0.2, 0.8], dtype=np.float32).tobytes(),\n },\n]", "section_id": "setup-and-data-preparation" }, { "id": "define-the-schema-ex0", "language": "python", "code": "schema = {\n \"index\": {\n \"name\": \"advanced_queries\",\n \"prefix\": \"products\",\n \"storage_type\": \"hash\",\n },\n \"fields\": [\n {\"name\": \"product_id\", \"type\": \"tag\"},\n {\"name\": \"category\", \"type\": \"tag\"},\n {\"name\": \"brief_description\", \"type\": \"text\"},\n {\"name\": \"full_description\", \"type\": \"text\"},\n {\"name\": \"price\", \"type\": \"numeric\"},\n {\"name\": \"rating\", \"type\": \"numeric\"},\n {\n \"name\": \"text_embedding\",\n \"type\": \"vector\",\n \"attrs\": {\n \"dims\": 3,\n \"distance_metric\": \"cosine\",\n \"algorithm\": \"flat\",\n \"datatype\": \"float32\"\n }\n },\n {\n \"name\": \"image_embedding\",\n \"type\": \"vector\",\n \"attrs\": {\n \"dims\": 2,\n \"distance_metric\": \"cosine\",\n \"algorithm\": \"flat\",\n \"datatype\": \"float32\"\n }\n }\n ],\n}", "section_id": "define-the-schema" }, { "id": "create-index-and-load-data-ex0", "language": "python", "code": "from redisvl.index import SearchIndex\n\n# Create the search index\nindex = SearchIndex.from_dict(schema, redis_url=\"redis://localhost:6379\")\n\n# Create the index and load data\nindex.create(overwrite=True)\nkeys = index.load(data)\n\nprint(f\"Loaded {len(keys)} products into the index\")", "section_id": "create-index-and-load-data" }, { "id": "basic-text-search-ex0", "language": "python", "code": "from redisvl.query import TextQuery\n\n# Create a text query\ntext_query = TextQuery(\n text=\"running shoes\",\n text_field_name=\"brief_description\",\n return_fields=[\"product_id\", \"brief_description\", \"category\", \"price\"],\n num_results=5\n)\n\nresults = index.query(text_query)\nresult_print(results)", "section_id": "basic-text-search" }, { "id": "text-search-with-different-scoring-algorithms-ex0", "language": "python", "code": "# BM25 standard scoring (default)\nbm25_query = TextQuery(\n text=\"comfortable shoes\",\n text_field_name=\"brief_description\",\n text_scorer=\"BM25STD\",\n return_fields=[\"product_id\", \"brief_description\", \"price\"],\n num_results=3\n)\n\nprint(\"Results with BM25 scoring:\")\nresults = index.query(bm25_query)\nresult_print(results)", "section_id": "text-search-with-different-scoring-algorithms" }, { "id": "text-search-with-different-scoring-algorithms-ex1", "language": "python", "code": "# TFIDF scoring\ntfidf_query = TextQuery(\n text=\"comfortable shoes\",\n text_field_name=\"brief_description\",\n text_scorer=\"TFIDF\",\n return_fields=[\"product_id\", \"brief_description\", \"price\"],\n num_results=3\n)\n\nprint(\"Results with TFIDF scoring:\")\nresults = index.query(tfidf_query)\nresult_print(results)", "section_id": "text-search-with-different-scoring-algorithms" }, { "id": "text-search-with-filters-ex0", "language": "python", "code": "from redisvl.query.filter import Tag, Num\n\n# Search for \"shoes\" only in the footwear category\nfiltered_text_query = TextQuery(\n text=\"shoes\",\n text_field_name=\"brief_description\",\n filter_expression=Tag(\"category\") == \"footwear\",\n return_fields=[\"product_id\", \"brief_description\", \"category\", \"price\"],\n num_results=5\n)\n\nresults = index.query(filtered_text_query)\nresult_print(results)", "section_id": "text-search-with-filters" }, { "id": "text-search-with-filters-ex1", "language": "python", "code": "# Search for products under $100\nprice_filtered_query = TextQuery(\n text=\"comfortable\",\n text_field_name=\"brief_description\",\n filter_expression=Num(\"price\") < 100,\n return_fields=[\"product_id\", \"brief_description\", \"price\"],\n num_results=5\n)\n\nresults = index.query(price_filtered_query)\nresult_print(results)", "section_id": "text-search-with-filters" }, { "id": "text-search-with-multiple-fields-and-weights-ex0", "language": "python", "code": "weighted_query = TextQuery(\n text=\"shoes\",\n text_field_name={\"brief_description\": 1.0, \"full_description\": 0.5},\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nresults = index.query(weighted_query)\nresult_print(results)", "section_id": "text-search-with-multiple-fields-and-weights" }, { "id": "text-search-with-custom-stopwords-ex0", "language": "python", "code": "# Use English stopwords (default)\nquery_with_stopwords = TextQuery(\n text=\"the best shoes for running\",\n text_field_name=\"brief_description\",\n stopwords=\"english\", # Common words like \"the\", \"for\" will be removed\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nresults = index.query(query_with_stopwords)\nresult_print(results)", "section_id": "text-search-with-custom-stopwords" }, { "id": "text-search-with-custom-stopwords-ex1", "language": "python", "code": "# Use custom stopwords\ncustom_stopwords_query = TextQuery(\n text=\"professional equipment for athletes\",\n text_field_name=\"brief_description\",\n stopwords=[\"for\", \"with\"], # Only these words will be filtered\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nresults = index.query(custom_stopwords_query)\nresult_print(results)", "section_id": "text-search-with-custom-stopwords" }, { "id": "text-search-with-custom-stopwords-ex2", "language": "python", "code": "# No stopwords\nno_stopwords_query = TextQuery(\n text=\"the best shoes for running\",\n text_field_name=\"brief_description\",\n stopwords=None, # All words will be included\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nresults = index.query(no_stopwords_query)\nresult_print(results)", "section_id": "text-search-with-custom-stopwords" }, { "id": "2-hybrid-queries-combining-text-and-vector-search-ex0", "language": "python", "code": "import warnings\n\n# redis-py's hybrid query helpers warn that APIs are experimental; keep notebook output readable\nwarnings.filterwarnings(\"ignore\", message=r\".*is an experimental.*\", category=UserWarning)\n\nfrom packaging.version import Version\n\nfrom redis import __version__ as _redis_py_version\n\nredis_py_version = Version(_redis_py_version)\nredis_version = Version(index.client.info()[\"redis_version\"])\n\nHYBRID_SEARCH_AVAILABLE = redis_version >= Version(\"8.4.0\") and redis_py_version >= Version(\"7.1.0\")\nprint(HYBRID_SEARCH_AVAILABLE)", "section_id": "2-hybrid-queries-combining-text-and-vector-search" }, { "id": "index-level-stopwords-configuration-ex0", "language": "python", "code": "# Create a schema with index-level stopwords disabled\nfrom redisvl.index import SearchIndex\n\nstopwords_schema = {\n \"index\": {\n \"name\": \"company_index\",\n \"prefix\": \"company:\",\n \"storage_type\": \"hash\",\n \"stopwords\": [] # STOPWORDS 0 - disable stopwords completely\n },\n \"fields\": [\n {\"name\": \"company_name\", \"type\": \"text\"},\n {\"name\": \"description\", \"type\": \"text\"}\n ]\n}\n\n# Create index using from_dict (handles schema creation internally)\ncompany_index = SearchIndex.from_dict(stopwords_schema, redis_url=\"redis://localhost:6379\")\ncompany_index.create(overwrite=True, drop=True)\n\nprint(f\"Index created with STOPWORDS 0: {company_index}\")", "section_id": "index-level-stopwords-configuration" }, { "id": "index-level-stopwords-configuration-ex1", "language": "python", "code": "# Load sample data with company names containing common stopwords\ncompanies = [\n {\"company_name\": \"Bank of Glasberliner\", \"description\": \"Major financial institution\"},\n {\"company_name\": \"University of Glasberliner\", \"description\": \"Public university system\"},\n {\"company_name\": \"Department of Glasberliner Affairs\", \"description\": \"A government agency\"},\n {\"company_name\": \"Glasberliner FC\", \"description\": \"Football Club\"},\n {\"company_name\": \"The Home Market\", \"description\": \"Home improvement retailer\"},\n]\n\nfor i, company in enumerate(companies):\n company_index.load([company], keys=[f\"company:{i}\"])\n\nprint(f\"✓ Loaded {len(companies)} companies\")", "section_id": "index-level-stopwords-configuration" }, { "id": "index-level-stopwords-configuration-ex2", "language": "python", "code": "# Search for \"Bank of Glasberliner\" - with STOPWORDS 0, \"of\" is indexed and searchable\nfrom redisvl.query import FilterQuery\n\nquery = FilterQuery(\n filter_expression='@company_name:(Bank of Glasberliner)',\n return_fields=[\"company_name\", \"description\"],\n)\n\nresults = company_index.search(query.query, query_params=query.params)\n\nprint(f\"Found {len(results.docs)} results for 'Bank of Glasberliner':\")\nfor doc in results.docs:\n print(f\" - {doc.company_name}: {doc.description}\")", "section_id": "index-level-stopwords-configuration" }, { "id": "index-level-stopwords-configuration-ex3", "language": "python", "code": "# Example: Create index with custom stopwords\ncustom_stopwords_schema = {\n \"index\": {\n \"name\": \"custom_stopwords_index\",\n \"prefix\": \"custom:\",\n \"stopwords\": [\"inc\", \"llc\", \"corp\"] # Filter out legal entity suffixes\n },\n \"fields\": [\n {\"name\": \"name\", \"type\": \"text\"}\n ]\n}\n\n# This would create an index where \"inc\", \"llc\", \"corp\" are not indexed\nprint(\"Custom stopwords:\", custom_stopwords_schema[\"index\"][\"stopwords\"])", "section_id": "index-level-stopwords-configuration" }, { "id": "index-level-stopwords-configuration-ex4", "language": "yaml", "code": "version: '0.1.0'\n\nindex:\n name: company_index\n prefix: company:\n storage_type: hash\n stopwords: [] # Disable stopwords (STOPWORDS 0)\n\nfields:\n - name: company_name\n type: text\n - name: description\n type: text", "section_id": "index-level-stopwords-configuration" }, { "id": "index-level-stopwords-configuration-ex5", "language": "yaml", "code": "index:\n stopwords:\n - the\n - a\n - an", "section_id": "index-level-stopwords-configuration" }, { "id": "index-level-stopwords-configuration-ex6", "language": "python", "code": "# Cleanup\ncompany_index.delete(drop=True)\nprint(\"✓ Cleaned up company_index\")", "section_id": "index-level-stopwords-configuration" }, { "id": "basic-hybrid-query-ex0", "language": "python", "code": "if HYBRID_SEARCH_AVAILABLE:\n from redisvl.query import HybridQuery\n\n # Create a hybrid query\n hybrid_query = HybridQuery(\n text=\"running shoes\",\n text_field_name=\"brief_description\",\n vector=[0.1, 0.2, 0.1], # Query vector\n vector_field_name=\"text_embedding\",\n return_fields=[\"product_id\", \"brief_description\", \"category\", \"price\"],\n num_results=5,\n yield_text_score_as=\"text_score\",\n yield_vsim_score_as=\"vector_similarity\",\n combination_method=\"LINEAR\",\n yield_combined_score_as=\"hybrid_score\",\n )\n\n results = index.query(hybrid_query)\n result_print(results)\n\nelse:\n print(\"Hybrid search is not available in this version of Redis/redis-py.\")", "section_id": "basic-hybrid-query" }, { "id": "basic-hybrid-query-ex1", "language": "python", "code": "from redisvl.query import AggregateHybridQuery\n\nagg_hybrid_query = AggregateHybridQuery(\n text=\"running shoes\",\n text_field_name=\"brief_description\",\n vector=[0.1, 0.2, 0.1], # Query vector\n vector_field_name=\"text_embedding\",\n return_fields=[\"product_id\", \"brief_description\", \"category\", \"price\"],\n num_results=5\n)\n\nresults = index.query(agg_hybrid_query)\nresult_print(results)", "section_id": "basic-hybrid-query" }, { "id": "adjusting-the-alpha-parameter-ex0", "language": "plaintext", "code": "hybrid_score = (alpha) * text_score + (1 - alpha) * vector_score", "section_id": "adjusting-the-alpha-parameter" }, { "id": "adjusting-the-alpha-parameter-ex1", "language": "python", "code": "if HYBRID_SEARCH_AVAILABLE:\n vector_heavy_query = HybridQuery(\n text=\"comfortable\",\n text_field_name=\"brief_description\",\n vector=[0.15, 0.25, 0.15],\n vector_field_name=\"text_embedding\",\n combination_method=\"LINEAR\",\n\t\tlinear_alpha=0.1, # 10% text, 90% vector\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3,\n yield_text_score_as=\"text_score\",\n yield_vsim_score_as=\"vector_similarity\",\n yield_combined_score_as=\"hybrid_score\",\n )\n\n print(\"Results with alpha=0.1 (vector-heavy):\")\n results = index.query(vector_heavy_query)\n result_print(results)\n\nelse:\n print(\"Hybrid search is not available in this version of Redis/redis-py.\")", "section_id": "adjusting-the-alpha-parameter" }, { "id": "adjusting-the-alpha-parameter-ex2", "language": "python", "code": "# More emphasis on vector search (alpha=0.9)\nvector_heavy_query = AggregateHybridQuery(\n text=\"comfortable\",\n text_field_name=\"brief_description\",\n vector=[0.15, 0.25, 0.15],\n vector_field_name=\"text_embedding\",\n alpha=0.9, # 90% vector, 10% text\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nprint(\"Results with alpha=0.9 (vector-heavy):\")\nresults = index.query(vector_heavy_query)\nresult_print(results)", "section_id": "adjusting-the-alpha-parameter" }, { "id": "reciprocal-rank-fusion-rrf-ex0", "language": "python", "code": "if HYBRID_SEARCH_AVAILABLE:\n rrf_query = HybridQuery(\n text=\"comfortable\",\n text_field_name=\"brief_description\",\n vector=[0.15, 0.25, 0.15],\n vector_field_name=\"text_embedding\",\n combination_method=\"RRF\",\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3,\n yield_text_score_as=\"text_score\",\n yield_vsim_score_as=\"vector_similarity\",\n yield_combined_score_as=\"hybrid_score\",\n )\n\n results = index.query(rrf_query)\n result_print(results)\n\nelse:\n print(\"Hybrid search is not available in this version of Redis/redis-py.\")", "section_id": "reciprocal-rank-fusion-rrf" }, { "id": "hybrid-query-with-filters-ex0", "language": "python", "code": "if HYBRID_SEARCH_AVAILABLE:\n # Hybrid search with a price filter\n filtered_hybrid_query = HybridQuery(\n text=\"professional equipment\",\n text_field_name=\"brief_description\",\n vector=[0.9, 0.1, 0.05],\n vector_field_name=\"text_embedding\",\n filter_expression=Num(\"price\") > 100,\n return_fields=[\"product_id\", \"brief_description\", \"category\", \"price\"],\n num_results=5,\n combination_method=\"LINEAR\",\n yield_text_score_as=\"text_score\",\n yield_vsim_score_as=\"vector_similarity\",\n yield_combined_score_as=\"hybrid_score\",\n )\n\n results = index.query(filtered_hybrid_query)\n result_print(results)\n\nelse:\n print(\"Hybrid search is not available in this version of Redis/redis-py.\")", "section_id": "hybrid-query-with-filters" }, { "id": "hybrid-query-with-filters-ex1", "language": "python", "code": "# Hybrid search with a price filter\nfiltered_hybrid_query = AggregateHybridQuery(\n text=\"professional equipment\",\n text_field_name=\"brief_description\",\n vector=[0.9, 0.1, 0.05],\n vector_field_name=\"text_embedding\",\n filter_expression=Num(\"price\") > 100,\n return_fields=[\"product_id\", \"brief_description\", \"category\", \"price\"],\n num_results=5\n)\n\nresults = index.query(filtered_hybrid_query)\nresult_print(results)", "section_id": "hybrid-query-with-filters" }, { "id": "using-different-text-scorers-ex0", "language": "python", "code": "if HYBRID_SEARCH_AVAILABLE:\n # Aggregate Hybrid query with TFIDF scorer\n hybrid_tfidf = HybridQuery(\n text=\"shoes support\",\n text_field_name=\"brief_description\",\n vector=[0.12, 0.18, 0.12],\n vector_field_name=\"text_embedding\",\n text_scorer=\"TFIDF\",\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3,\n combination_method=\"LINEAR\",\n yield_text_score_as=\"text_score\",\n yield_vsim_score_as=\"vector_similarity\",\n yield_combined_score_as=\"hybrid_score\",\n )\n\n results = index.query(hybrid_tfidf)\n result_print(results)\n\nelse:\n print(\"Hybrid search is not available in this version of Redis/redis-py.\")", "section_id": "using-different-text-scorers" }, { "id": "using-different-text-scorers-ex1", "language": "python", "code": "# Aggregate Hybrid query with TFIDF scorer\nhybrid_tfidf = AggregateHybridQuery(\n text=\"shoes support\",\n text_field_name=\"brief_description\",\n vector=[0.12, 0.18, 0.12],\n vector_field_name=\"text_embedding\",\n text_scorer=\"TFIDF\",\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nresults = index.query(hybrid_tfidf)\nresult_print(results)", "section_id": "using-different-text-scorers" }, { "id": "3-multivectorquery-multi-vector-search-ex0", "language": "plaintext", "code": "combined_score = w_1 * score_1 + w_2 * score_2 + w_3 * score_3 + ...", "section_id": "3-multivectorquery-multi-vector-search" }, { "id": "basic-multi-vector-query-ex0", "language": "python", "code": "from redisvl.query import MultiVectorQuery, Vector\n\n# Define multiple vectors for the query\ntext_vector = Vector(\n vector=[0.1, 0.2, 0.1],\n field_name=\"text_embedding\",\n dtype=\"float32\",\n weight=0.7 # 70% weight for text embedding\n)\n\nimage_vector = Vector(\n vector=[0.8, 0.1],\n field_name=\"image_embedding\",\n dtype=\"float32\",\n weight=0.3 # 30% weight for image embedding\n)\n\n# Create a multi-vector query\nmulti_vector_query = MultiVectorQuery(\n vectors=[text_vector, image_vector],\n return_fields=[\"product_id\", \"brief_description\", \"category\"],\n num_results=5\n)\n\nresults = index.query(multi_vector_query)\nresult_print(results)", "section_id": "basic-multi-vector-query" }, { "id": "adjusting-vector-weights-ex0", "language": "python", "code": "# More emphasis on image similarity\ntext_vec = Vector(\n vector=[0.9, 0.1, 0.05],\n field_name=\"text_embedding\",\n dtype=\"float32\",\n weight=0.2 # 20% weight\n)\n\nimage_vec = Vector(\n vector=[0.1, 0.9],\n field_name=\"image_embedding\",\n dtype=\"float32\",\n weight=0.8 # 80% weight\n)\n\nimage_heavy_query = MultiVectorQuery(\n vectors=[text_vec, image_vec],\n return_fields=[\"product_id\", \"brief_description\", \"category\"],\n num_results=3\n)\n\nprint(\"Results with emphasis on image similarity:\")\nresults = index.query(image_heavy_query)\nresult_print(results)", "section_id": "adjusting-vector-weights" }, { "id": "multi-vector-query-with-filters-ex0", "language": "python", "code": "# Multi-vector search with category filter\ntext_vec = Vector(\n vector=[0.1, 0.2, 0.1],\n field_name=\"text_embedding\",\n dtype=\"float32\",\n weight=0.6\n)\n\nimage_vec = Vector(\n vector=[0.8, 0.1],\n field_name=\"image_embedding\",\n dtype=\"float32\",\n weight=0.4\n)\n\nfiltered_multi_query = MultiVectorQuery(\n vectors=[text_vec, image_vec],\n filter_expression=Tag(\"category\") == \"footwear\",\n return_fields=[\"product_id\", \"brief_description\", \"category\", \"price\"],\n num_results=5\n)\n\nresults = index.query(filtered_multi_query)\nresult_print(results)", "section_id": "multi-vector-query-with-filters" }, { "id": "comparing-query-types-ex0", "language": "python", "code": "# TextQuery - keyword-based search\ntext_q = TextQuery(\n text=\"shoes\",\n text_field_name=\"brief_description\",\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nprint(\"TextQuery Results (keyword-based):\")\nresult_print(index.query(text_q))\nprint()", "section_id": "comparing-query-types" }, { "id": "comparing-query-types-ex1", "language": "python", "code": "if HYBRID_SEARCH_AVAILABLE:\n # HybridQuery - combines text and vector search\n hybrid_q = HybridQuery(\n text=\"shoes\",\n text_field_name=\"brief_description\",\n vector=[0.1, 0.2, 0.1],\n vector_field_name=\"text_embedding\",\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3,\n combination_method=\"LINEAR\",\n yield_text_score_as=\"text_score\",\n yield_vsim_score_as=\"vector_similarity\",\n yield_combined_score_as=\"hybrid_score\",\n )\n\n results = index.query(hybrid_q)\n\nelse:\n hybrid_q = AggregateHybridQuery(\n text=\"shoes\",\n text_field_name=\"brief_description\",\n vector=[0.1, 0.2, 0.1],\n vector_field_name=\"text_embedding\",\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3,\n )\n\n results = index.query(hybrid_q)\n\n\nprint(f\"{hybrid_q.__class__.__name__} Results (text + vector):\")\nresult_print(results)\nprint()", "section_id": "comparing-query-types" }, { "id": "comparing-query-types-ex2", "language": "python", "code": "# MultiVectorQuery - searches multiple vector fields\nmv_text = Vector(\n vector=[0.1, 0.2, 0.1],\n field_name=\"text_embedding\",\n dtype=\"float32\",\n weight=0.5\n)\n\nmv_image = Vector(\n vector=[0.8, 0.1],\n field_name=\"image_embedding\",\n dtype=\"float32\",\n weight=0.5\n)\n\nmulti_q = MultiVectorQuery(\n vectors=[mv_text, mv_image],\n return_fields=[\"product_id\", \"brief_description\"],\n num_results=3\n)\n\nprint(\"MultiVectorQuery Results (multiple vectors):\")\nresult_print(index.query(multi_q))", "section_id": "comparing-query-types" }, { "id": "cleanup-ex0", "language": "python", "code": "# Cleanup\nindex.delete()", "section_id": "cleanup" } ] }