Vector and hybrid search¶

You want to find the K most similar items to a query embedding, optionally filtered by metadata.

Prerequisites¶

An index with a VECTOR field, e.g.:

FT.CREATE products ON HASH PREFIX 1 product:
  SCHEMA
  title TEXT
  category TAG
  embedding VECTOR FLAT 6 TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE

Embeddings stored as FLOAT32 byte arrays in the embedding field.

Pure KNN¶

import struct

query_vec = struct.pack(f"{len(embedding)}f", *embedding)

result = executor.execute(
    """
    SELECT title, vector_distance(embedding, :vec) AS score
    FROM products
    LIMIT 5
    """,
    params={"vec": query_vec},
)

vector_distance(field, :param) is the function that triggers a KNN search. The LIMIT becomes the K value.

Hybrid: filter then KNN¶

Combine a WHERE clause with vector_distance:

result = executor.execute(
    """
    SELECT title, vector_distance(embedding, :vec) AS score
    FROM products
    WHERE category = 'electronics' AND price < 1000
    LIMIT 5
    """,
    params={"vec": query_vec},
)

The filter narrows the candidate set; the KNN runs over what survives.

Returning the score¶

vector_distance(...) AS alias is required for the score to come back as a column. The result rows include the alias as a key.