{
  "id": "queries",
  "title": "Query Types",
  "url": "https://redis.io/docs/latest/develop/ai/redisvl/0.16.0/concepts/queries/",
  "summary": "",
  "content": "\n\nRedisVL provides several query types, each optimized for different search patterns. Understanding when to use each helps you build efficient search applications.\n\n## Vector Queries\n\nVector queries find documents by semantic similarity. You provide a vector (typically an embedding of text or images), and Redis returns documents whose vectors are closest to yours.\n\n### VectorQuery\n\nThe most common query type. Returns the top K most similar documents using KNN (K-Nearest Neighbors) search.\n\n```python\nfrom redisvl.query import VectorQuery\n\nquery = VectorQuery(\n    vector=embedding,           # Your query embedding\n    vector_field_name=\"embedding\",\n    num_results=10\n)\nresults = index.query(query)\n```\n\nUse when you want to find the N most similar items regardless of how similar they actually are. Good for \"find me things like this\" searches.\n\n### VectorRangeQuery\n\nReturns all documents within a specified distance threshold. Unlike VectorQuery, this doesn’t limit results to a fixed K—it returns everything within the radius.\n\n```python\nfrom redisvl.query import VectorRangeQuery\n\nquery = VectorRangeQuery(\n    vector=embedding,\n    vector_field_name=\"embedding\",\n    distance_threshold=0.3      # Return all within this distance\n)\nresults = index.query(query)\n```\n\nUse when similarity threshold matters more than result count. Good for \"find everything similar enough\" searches, like deduplication or clustering.\n\n## Filter Queries\n\nFilter queries find documents by exact field matching without vector similarity.\n\n### FilterQuery\n\nSearches using filter expressions on indexed fields. Supports tag matching, numeric ranges, text search, and geographic filters.\n\n```python\nfrom redisvl.query import FilterQuery\nfrom redisvl.query.filter import Tag, Num\n\nquery = FilterQuery(\n    filter_expression=(Tag(\"category\") == \"electronics\") \u0026 (Num(\"price\") \u003c 100),\n    return_fields=[\"title\", \"price\"],\n    num_results=20\n)\nresults = index.query(query)\n```\n\nUse when you need precise filtering without semantic similarity—finding all products in a category, all users in a region, or all records within a date range.\n\n### CountQuery\n\nReturns only the count of matching documents, not the documents themselves. More efficient than FilterQuery when you only need the count.\n\n```python\nfrom redisvl.query import CountQuery\nfrom redisvl.query.filter import Tag\n\nquery = CountQuery(filter_expression=Tag(\"status\") == \"active\")\ncount = index.query(query)\n```\n\nUse for analytics, pagination totals, or checking if matches exist before running a full query.\n\n## Text Queries\n\nText queries perform full-text search with relevance scoring.\n\n### TextQuery\n\nSearches text fields using Redis’s full-text search capabilities. Supports multiple scoring algorithms (BM25, TF-IDF), stopword handling, and field weighting.\n\n```python\nfrom redisvl.query import TextQuery\n\nquery = TextQuery(\n    text=\"machine learning\",\n    text_field_name=\"content\",\n    text_scorer=\"BM25STD\",\n    num_results=10\n)\nresults = index.query(query)\n```\n\nUse when you need keyword-based search with relevance ranking—traditional search engine behavior where exact word matches matter.\n\n## Hybrid Queries\n\nHybrid queries combine multiple search strategies for better results than either alone.\n\n### HybridQuery\n\nCombines text search and vector search in a single query using Redis’s native hybrid search. Supports multiple fusion methods:\n\n- **RRF (Reciprocal Rank Fusion)**: Combines rankings from both searches. Good when you trust both signals equally.\n- **Linear**: Weighted combination of scores. Good when you want to tune the balance between text and semantic relevance.\n\n```python\nfrom redisvl.query import HybridQuery\n\nquery = HybridQuery(\n    text=\"machine learning frameworks\",\n    text_field_name=\"content\",\n    vector=embedding,\n    vector_field_name=\"embedding\",\n    combination_method=\"RRF\",\n    num_results=10\n)\nresults = index.query(query)\n```\n\nUse when neither pure keyword search nor pure semantic search gives good enough results. Common in RAG applications where you want both exact matches and semantic understanding.\n\n#### NOTE\nHybridQuery requires Redis \u003e= 8.4.0 and redis-py \u003e= 7.1.0.\n\n### AggregateHybridQuery\n\nSimilar to HybridQuery but uses Redis aggregation pipelines. Provides more control over score combination and result processing.\n\nUse when you need custom score normalization or complex result transformations that HybridQuery doesn’t support.\n\n## Multi-Vector Queries\n\n### MultiVectorQuery\n\nSearches across multiple vector fields simultaneously with configurable weights per field.\n\n```python\nfrom redisvl.query import MultiVectorQuery, Vector\n\nquery = MultiVectorQuery(\n    vectors=[\n        Vector(vector=text_embedding, field_name=\"text_vector\", weight=0.7),\n        Vector(vector=image_embedding, field_name=\"image_vector\", weight=0.3),\n    ],\n    num_results=10\n)\nresults = index.query(query)\n```\n\nUse for multimodal search—finding documents that match across text embeddings, image embeddings, and other vector representations. Each vector field can have different importance weights.\n\n## SQL Queries\n\n### SQLQuery\n\nTranslates SQL SELECT statements into Redis queries. Provides a familiar interface for developers coming from relational databases.\n\n```python\nfrom redisvl.query import SQLQuery\n\nquery = SQLQuery(\"\"\"\n    SELECT title, price, category\n    FROM products\n    WHERE category = 'electronics' AND price \u003c 100\n\"\"\")\nresults = index.query(query)\n```\n\nUse when your team is more comfortable with SQL syntax, or when integrating with tools that generate SQL.\n\n#### NOTE\nSQLQuery requires the optional `sql-redis` package. Install with: `pip install redisvl[sql-redis]`\n\n## Choosing the Right Query\n\n| Use Case                                   | Query Type       |\n|--------------------------------------------|------------------|\n| Semantic similarity search                 | VectorQuery      |\n| Find all items within similarity threshold | VectorRangeQuery |\n| Exact field matching                       | FilterQuery      |\n| Count matching records                     | CountQuery       |\n| Keyword search with relevance              | TextQuery        |\n| Combined keyword + semantic                | HybridQuery      |\n| Multimodal search                          | MultiVectorQuery |\n| SQL-familiar interface                     | SQLQuery         |\n\n## Common Patterns\n\n### Vector Search with Filters\n\nAll vector queries support filter expressions. Combine semantic search with metadata filtering:\n\n```python\nfrom redisvl.query import VectorQuery\nfrom redisvl.query.filter import Tag, Num\n\nquery = VectorQuery(\n    vector=embedding,\n    vector_field_name=\"embedding\",\n    filter_expression=(Tag(\"category\") == \"electronics\") \u0026 (Num(\"price\") \u003c 100),\n    num_results=10\n)\n```\n\n### Hybrid Search for RAG\n\nFor retrieval-augmented generation, hybrid search often outperforms pure vector search:\n\n```python\nfrom redisvl.query import HybridQuery\n\nquery = HybridQuery(\n    text=\"machine learning frameworks\",\n    text_field_name=\"content\",\n    vector=embedding,\n    vector_field_name=\"embedding\",\n    combination_method=\"RRF\",\n    num_results=5\n)\n```\n\n**Learn more:** [Use Advanced Query Types](../user_guide/11_advanced_queries.md) demonstrates these query types in detail.\n",
  "tags": [],
  "last_updated": "2026-04-21T14:39:33+02:00"
}