Zvex.Query (zvex v0.4.0)

Fluent builder for zvec vector queries.

Example

alias Zvex.Query
alias Zvex.Vector

vec = Vector.from_list([0.1, 0.2, 0.3, 0.4], :fp32)

Query.new()
|> Query.field("embedding")
|> Query.vector(vec)
|> Query.top_k(5)
|> Query.hnsw(ef: 100)
|> Query.execute(collection)
# {:ok, [%Zvex.Query.Result{pk: _, score: _, doc_id: _, fields: %{}}]}

Summary

Types

t()

A vector similarity search query built with the fluent API.

Functions

execute(query, collection)

Executes the query against the given collection.

execute!(query, collection)

Like execute/2 but raises on error.

field(query, name)

Sets the vector field to search against. Required before executing.

filter(query, expr)

Applies a filter expression to pre-filter candidates before vector search.

flat(query, opts \\ [])

Selects brute-force flat scan. Guarantees exact results at the cost of speed.

hnsw(query, opts \\ [])

Selects HNSW as the search algorithm.

include_doc_id(query, bool)

When true, includes the internal document ID in each result (default false).

include_vector(query, bool)

When true, includes the matched vector data in each result (default false).

ivf(query, opts \\ [])

Selects IVF as the search algorithm.

new()

Creates a new query with default values (top_k: 10, no filter, no output fields).

output_fields(query, fields)

Specifies which scalar fields to include in the results. Defaults to none.

top_k(query, k)

Sets the maximum number of nearest neighbors to return (default 10).

vector(query, list)

Sets the query vector for similarity search. Required before executing.

Types

t()

@type t() :: %Zvex.Query{
  field: String.t() | nil,
  filter: String.t() | nil,
  include_doc_id: boolean(),
  include_vector: boolean(),
  output_fields: [String.t()],
  params: nil | {:hnsw, keyword()} | {:ivf, keyword()} | {:flat, keyword()},
  top_k: pos_integer(),
  vector: binary() | nil
}

A vector similarity search query built with the fluent API.

Functions

execute(query, collection)

@spec execute(t(), Zvex.Collection.t()) ::
  {:ok, [Zvex.Query.Result.t()]} | {:error, Zvex.Error.t()}

Executes the query against the given collection.

Both field/2 and vector/2 must be set before calling this function. Returns a list of Zvex.Query.Result structs sorted by score (closest first).

execute!(query, collection)

@spec execute!(t(), Zvex.Collection.t()) :: [Zvex.Query.Result.t()]

Like execute/2 but raises on error.

field(query, name)

@spec field(t(), String.t()) :: t()

Sets the vector field to search against. Required before executing.

filter(query, expr)

@spec filter(t(), String.t()) :: t()

Applies a filter expression to pre-filter candidates before vector search.

The expression uses zvec's filter syntax (e.g. "category == 'books'").

flat(query, opts \\ [])

@spec flat(
  t(),
  keyword()
) :: t()

Selects brute-force flat scan. Guarantees exact results at the cost of speed.

hnsw(query, opts \\ [])

@spec hnsw(
  t(),
  keyword()
) :: t()

Selects HNSW as the search algorithm.

Options

:ef — search-time expansion factor (higher = better recall, slower search).

include_doc_id(query, bool)

@spec include_doc_id(t(), boolean()) :: t()

When true, includes the internal document ID in each result (default false).

include_vector(query, bool)

@spec include_vector(t(), boolean()) :: t()

When true, includes the matched vector data in each result (default false).

ivf(query, opts \\ [])

@spec ivf(
  t(),
  keyword()
) :: t()

Selects IVF as the search algorithm.

Options

:n_probe — number of partitions to scan (higher = better recall, slower search).

new()

@spec new() :: t()

Creates a new query with default values (top_k: 10, no filter, no output fields).

output_fields(query, fields)

@spec output_fields(t(), [String.t()]) :: t()

Specifies which scalar fields to include in the results. Defaults to none.

top_k(query, k)

@spec top_k(t(), pos_integer()) :: t()

Sets the maximum number of nearest neighbors to return (default 10).

vector(query, list)

@spec vector(t(), Zvex.Vector.t() | [number()]) :: t()

Sets the query vector for similarity search. Required before executing.

Accepts a Zvex.Vector struct or a plain list of numbers (auto-converted to :fp32). Sparse vectors are not supported as query vectors.