{
  "id": "queries",
  "title": "Query Types",
  "url": "https://redis.io/docs/latest/develop/ai/redisvl/concepts/queries/",
  "summary": "",
  "tags": [],
  "last_updated": "2026-04-22T11:55:45+02:00",
  "page_type": "content",
  "content_hash": "cbec44a750334fc8fd2e3bd17c9d628dda5666bf87b034eaa95bb45e1b92989e",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "RedisVL provides several query types, each optimized for different search patterns. Understanding when to use each helps you build efficient search applications."
    },
    {
      "id": "vector-queries",
      "title": "Vector Queries",
      "role": "content",
      "text": "Vector 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."
    },
    {
      "id": "vectorquery",
      "title": "VectorQuery",
      "role": "content",
      "text": "The most common query type. Returns the top K most similar documents using KNN (K-Nearest Neighbors) search.\n\n[code example]\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."
    },
    {
      "id": "vectorrangequery",
      "title": "VectorRangeQuery",
      "role": "content",
      "text": "Returns 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[code example]\n\nUse when similarity threshold matters more than result count. Good for \"find everything similar enough\" searches, like deduplication or clustering."
    },
    {
      "id": "filter-queries",
      "title": "Filter Queries",
      "role": "content",
      "text": "Filter queries find documents by exact field matching without vector similarity."
    },
    {
      "id": "filterquery",
      "title": "FilterQuery",
      "role": "content",
      "text": "Searches using filter expressions on indexed fields. Supports tag matching, numeric ranges, text search, and geographic filters.\n\n[code example]\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."
    },
    {
      "id": "countquery",
      "title": "CountQuery",
      "role": "content",
      "text": "Returns only the count of matching documents, not the documents themselves. More efficient than FilterQuery when you only need the count.\n\n[code example]\n\nUse for analytics, pagination totals, or checking if matches exist before running a full query."
    },
    {
      "id": "text-queries",
      "title": "Text Queries",
      "role": "content",
      "text": "Text queries perform full-text search with relevance scoring."
    },
    {
      "id": "textquery",
      "title": "TextQuery",
      "role": "content",
      "text": "Searches text fields using Redis’s full-text search capabilities. Supports multiple scoring algorithms (BM25, TF-IDF), stopword handling, and field weighting.\n\n[code example]\n\nUse when you need keyword-based search with relevance ranking—traditional search engine behavior where exact word matches matter."
    },
    {
      "id": "hybrid-queries",
      "title": "Hybrid Queries",
      "role": "content",
      "text": "Hybrid queries combine multiple search strategies for better results than either alone."
    },
    {
      "id": "hybridquery",
      "title": "HybridQuery",
      "role": "content",
      "text": "Combines 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[code example]\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 >= 8.4.0 and redis-py >= 7.1.0."
    },
    {
      "id": "aggregatehybridquery",
      "title": "AggregateHybridQuery",
      "role": "content",
      "text": "Similar 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."
    },
    {
      "id": "multi-vector-queries",
      "title": "Multi-Vector Queries",
      "role": "content",
      "text": ""
    },
    {
      "id": "multivectorquery",
      "title": "MultiVectorQuery",
      "role": "content",
      "text": "Searches across multiple vector fields simultaneously with configurable weights per field.\n\n[code example]\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."
    },
    {
      "id": "sql-queries",
      "title": "SQL Queries",
      "role": "content",
      "text": ""
    },
    {
      "id": "sqlquery",
      "title": "SQLQuery",
      "role": "content",
      "text": "Translates SQL SELECT statements into Redis queries. Provides a familiar interface for developers coming from relational databases.\n\n[code example]\n\n`SQLQuery` also accepts `sql_redis_options`, which are forwarded to the\nunderlying `sql-redis` executor. This is mainly useful for tuning schema\ncaching behavior.\n\n[code example]\n\n- `\"lazy\"` (default) loads schemas only when a query touches an index, which\n  keeps startup and one-off queries cheaper.\n- `\"load_all\"` preloads all schemas up front, which can help repeated query\n  workloads that span many indexes.\n\nFor TEXT fields with `sql-redis >= 0.4.0`:\n\n- `=` performs exact phrase or exact-term matching\n- `LIKE` performs prefix/suffix/contains matching using SQL `%` wildcards\n- `fuzzy(field, 'term')` performs typo-tolerant matching\n- `fulltext(field, 'query')` performs tokenized search\n\n[code example]\n\nUse `=` when you want an exact phrase, `LIKE` for prefix/suffix/contains\npatterns, `fuzzy()` for typo-tolerant lookup, and `fulltext()` for tokenized\nsearch operators such as `OR`, optional terms, or proximity.\n\n**Aggregations and grouping:**\n\n[code example]\n\n**Geographic queries** with `geo_distance()`:\n\n[code example]\n\n**Date queries** with ISO date literals and date functions:\n\n[code example]\n\n**Vector similarity search** with parameters:\n\n[code example]\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\nFor comprehensive examples including geographic filtering, date functions, and vector search, see the [SQL to Redis Queries guide](../user_guide/12_sql_to_redis_queries.md)."
    },
    {
      "id": "choosing-the-right-query",
      "title": "Choosing the Right Query",
      "role": "content",
      "text": "| 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         |"
    },
    {
      "id": "common-patterns",
      "title": "Common Patterns",
      "role": "content",
      "text": ""
    },
    {
      "id": "vector-search-with-filters",
      "title": "Vector Search with Filters",
      "role": "content",
      "text": "All vector queries support filter expressions. Combine semantic search with metadata filtering:\n\n[code example]"
    },
    {
      "id": "hybrid-search-for-rag",
      "title": "Hybrid Search for RAG",
      "role": "content",
      "text": "For retrieval-augmented generation, hybrid search often outperforms pure vector search:\n\n[code example]\n\n**Learn more:** [Use Advanced Query Types](../user_guide/11_advanced_queries.md) demonstrates these query types in detail."
    }
  ],
  "examples": [
    {
      "id": "vectorquery-ex0",
      "language": "python",
      "code": "from 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)",
      "section_id": "vectorquery"
    },
    {
      "id": "vectorrangequery-ex0",
      "language": "python",
      "code": "from 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)",
      "section_id": "vectorrangequery"
    },
    {
      "id": "filterquery-ex0",
      "language": "python",
      "code": "from redisvl.query import FilterQuery\nfrom redisvl.query.filter import Tag, Num\n\nquery = FilterQuery(\n    filter_expression=(Tag(\"category\") == \"electronics\") & (Num(\"price\") < 100),\n    return_fields=[\"title\", \"price\"],\n    num_results=20\n)\nresults = index.query(query)",
      "section_id": "filterquery"
    },
    {
      "id": "countquery-ex0",
      "language": "python",
      "code": "from redisvl.query import CountQuery\nfrom redisvl.query.filter import Tag\n\nquery = CountQuery(filter_expression=Tag(\"status\") == \"active\")\ncount = index.query(query)",
      "section_id": "countquery"
    },
    {
      "id": "textquery-ex0",
      "language": "python",
      "code": "from 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)",
      "section_id": "textquery"
    },
    {
      "id": "hybridquery-ex0",
      "language": "python",
      "code": "from 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)",
      "section_id": "hybridquery"
    },
    {
      "id": "multivectorquery-ex0",
      "language": "python",
      "code": "from 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)",
      "section_id": "multivectorquery"
    },
    {
      "id": "sqlquery-ex0",
      "language": "python",
      "code": "from redisvl.query import SQLQuery\n\nquery = SQLQuery(\"\"\"\n    SELECT title, price, category\n    FROM products\n    WHERE category = 'electronics' AND price < 100\n\"\"\")\nresults = index.query(query)",
      "section_id": "sqlquery"
    },
    {
      "id": "sqlquery-ex1",
      "language": "python",
      "code": "query = SQLQuery(\n    \"\"\"\n    SELECT title, price, category\n    FROM products\n    WHERE category = 'electronics' AND price < 100\n    \"\"\",\n    sql_redis_options={\"schema_cache_strategy\": \"lazy\"},\n)",
      "section_id": "sqlquery"
    },
    {
      "id": "sqlquery-ex2",
      "language": "python",
      "code": "query = SQLQuery(\"SELECT * FROM products WHERE title = 'gaming laptop'\")\nquery = SQLQuery(\"SELECT * FROM products WHERE title LIKE 'lap%'\")\nquery = SQLQuery(\"SELECT * FROM products WHERE fuzzy(title, 'laptap')\")\nquery = SQLQuery(\"SELECT * FROM products WHERE fulltext(title, 'laptop OR tablet')\")",
      "section_id": "sqlquery"
    },
    {
      "id": "sqlquery-ex3",
      "language": "python",
      "code": "query = SQLQuery(\"\"\"\n    SELECT category, COUNT(*) as count, AVG(price) as avg_price\n    FROM products\n    GROUP BY category\n    ORDER BY count DESC\n\"\"\")",
      "section_id": "sqlquery"
    },
    {
      "id": "sqlquery-ex4",
      "language": "python",
      "code": "# Find stores within 50km of San Francisco\nquery = SQLQuery(\"\"\"\n    SELECT name, category\n    FROM stores\n    WHERE geo_distance(location, POINT(-122.4194, 37.7749), 'km') < 50\n\"\"\")\n\n# Calculate distances\nquery = SQLQuery(\"\"\"\n    SELECT name, geo_distance(location, POINT(-122.4194, 37.7749)) AS distance\n    FROM stores\n\"\"\")",
      "section_id": "sqlquery"
    },
    {
      "id": "sqlquery-ex5",
      "language": "python",
      "code": "# Filter by date range\nquery = SQLQuery(\"\"\"\n    SELECT name FROM events\n    WHERE created_at BETWEEN '2024-01-01' AND '2024-03-31'\n\"\"\")\n\n# Extract date parts\nquery = SQLQuery(\"\"\"\n    SELECT YEAR(created_at) AS year, COUNT(*) AS count\n    FROM events\n    GROUP BY year\n\"\"\")",
      "section_id": "sqlquery"
    },
    {
      "id": "sqlquery-ex6",
      "language": "python",
      "code": "query = SQLQuery(\"\"\"\n    SELECT title, vector_distance(embedding, :vec) AS score\n    FROM products\n    LIMIT 5\n\"\"\", params={\"vec\": embedding_bytes})",
      "section_id": "sqlquery"
    },
    {
      "id": "vector-search-with-filters-ex0",
      "language": "python",
      "code": "from 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\") & (Num(\"price\") < 100),\n    num_results=10\n)",
      "section_id": "vector-search-with-filters"
    },
    {
      "id": "hybrid-search-for-rag-ex0",
      "language": "python",
      "code": "from 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)",
      "section_id": "hybrid-search-for-rag"
    }
  ]
}