topk_sdk.query

Classes

LogicalExpr

Internal Instances of the LogicalExpr class are used to represent logical expressions in TopK. Usually created using logical constructors such as field(), literal(), etc. Methods

is_null()

is_null(self) -> LogicalExpr

Check if the expression is null. Returns LogicalExpr

is_not_null()

is_not_null(self) -> LogicalExpr

Check if the expression is not null. Returns LogicalExpr

abs()

abs(self) -> LogicalExpr

Compute the absolute value of the expression. Returns LogicalExpr

ln()

ln(self) -> LogicalExpr

Compute the natural logarithm of the expression. Returns LogicalExpr

exp()

exp(self) -> LogicalExpr

Compute the exponential of the expression. Returns LogicalExpr

sqrt()

sqrt(self) -> LogicalExpr

Compute the square root of the expression. Returns LogicalExpr

square()

square(self) -> LogicalExpr

Compute the square of the expression. Returns LogicalExpr

eq()

eq(self, other: FlexibleExpr) -> LogicalExpr

Check if the expression is equal to another expression. Parameters

Parameter	Type
`other`	`FlexibleExpr`

Returns LogicalExpr

ne()

ne(self, other: FlexibleExpr) -> LogicalExpr

Check if the expression is not equal to another expression. Parameters

Parameter	Type
`other`	`FlexibleExpr`

Returns LogicalExpr

lt()

lt(self, other: Ordered) -> LogicalExpr

Check if the expression is less than another expression. Parameters

Parameter	Type
`other`	`Ordered`

Returns LogicalExpr

lte()

lte(self, other: Ordered) -> LogicalExpr

Check if the expression is less than or equal to another expression. Parameters

Parameter	Type
`other`	`Ordered`

Returns LogicalExpr

gt()

gt(self, other: Ordered) -> LogicalExpr

Check if the expression is greater than another expression. Parameters

Parameter	Type
`other`	`Ordered`

Returns LogicalExpr

gte()

gte(self, other: Ordered) -> LogicalExpr

Check if the expression is greater than or equal to another expression. Parameters

Parameter	Type
`other`	`Ordered`

Returns LogicalExpr

add()

add(self, other: Numeric) -> LogicalExpr

Add another value to the expression. Parameters

Parameter	Type
`other`	`Numeric`

Returns LogicalExpr

sub()

sub(self, other: Numeric) -> LogicalExpr

Subtract another value from the expression. Parameters

Parameter	Type
`other`	`Numeric`

Returns LogicalExpr

mul()

mul(self, other: Numeric) -> LogicalExpr

Multiply the expression by another value. Parameters

Parameter	Type
`other`	`Numeric`

Returns LogicalExpr

div()

div(self, other: Numeric) -> LogicalExpr

Divide the expression by another value. Parameters

Parameter	Type
`other`	`Numeric`

Returns LogicalExpr

min()

min(self, other: Ordered) -> LogicalExpr

Compute the minimum of the expression and another value. Parameters

Parameter	Type
`other`	`Ordered`

Returns LogicalExpr

max()

max(self, other: Ordered) -> LogicalExpr

Compute the maximum of the expression and another value. Parameters

Parameter	Type
`other`	`Ordered`

Returns LogicalExpr

and_()

and_(self, other: Boolish) -> LogicalExpr

Compute the logical AND of the expression and another expression. Parameters

Parameter	Type
`other`	`Boolish`

Returns LogicalExpr

or_()

or_(self, other: Boolish) -> LogicalExpr

Compute the logical OR of the expression and another expression. Parameters

Parameter	Type
`other`	`Boolish`

Returns LogicalExpr

starts_with()

starts_with(self, other: Stringy) -> LogicalExpr

Check if the expression starts with the provided string expression. Can be applied on a string field or a list of strings field.

# Example:
from topk_sdk.query import field, starts_with

client.collection("books").query(
  filter(field("title").starts_with("The") | field("tags").starts_with("fiction"))
)

Parameters

Parameter	Type
`other`	`Stringy`

Returns LogicalExpr

contains()

contains(self, other: FlexibleExpr) -> LogicalExpr

Check if the expression contains another value. Parameters

Parameter	Type
`other`	`FlexibleExpr`

Returns LogicalExpr

in_()

in_(self, other: Iterable) -> LogicalExpr

Check if the expression is in the provided iterable expression. Parameters

Parameter	Type
`other`	`Iterable`

Returns LogicalExpr

match_all()

match_all(self, other: StringyWithList) -> LogicalExpr

Check if the expression matches all terms against the field with keyword index. Parameters

Parameter	Type
`other`	`StringyWithList`

Returns LogicalExpr

match_any()

match_any(self, other: StringyWithList) -> LogicalExpr

Check if the expression matches any term against the field with keyword index. Parameters

Parameter	Type
`other`	`StringyWithList`

Returns LogicalExpr

coalesce()

coalesce(self, other: Numeric) -> LogicalExpr

Coalesce nulls in the expression with another value. Parameters

Parameter	Type
`other`	`Numeric`

Returns LogicalExpr

choose()

choose(self, x: FlexibleExpr, y: FlexibleExpr) -> LogicalExpr

Choose between two values based on the expression. Parameters

Parameter	Type
`x`	`FlexibleExpr`
`y`	`FlexibleExpr`

Returns LogicalExpr

boost()

boost(self, condition: FlexibleExpr, boost: Numeric) -> LogicalExpr

Multiply the scoring expression by the provided boost value if the condition is true. Parameters

Parameter	Type
`condition`	`FlexibleExpr`
`boost`	`Numeric`

Returns LogicalExpr

regexp_match()

regexp_match(self, pattern: str, flags: Optional[str] = None) -> LogicalExpr

Check if the expression matches the provided regexp pattern. Parameters

Parameter	Type
`pattern`	str
`flags`	Optional[str]

Returns LogicalExpr

FunctionExpr

Internal Instances of the FunctionExpr class are used to represent function expressions in TopK. Usually created using function constructors such as fn.vector_distance(), fn.semantic_similarity() or fn.bm25_score().

AggregateExpr

Internal Instances of the AggregateExpr class are used to represent aggregate expressions in TopK. Usually created using aggregate constructors such as agg.count(), agg.sum(), agg.min(), agg.max() or agg.avg().

TextExpr

Internal Instances of the TextExpr class are used to represent text expressions in TopK.

Query

Methods

select()

select(self) -> Query

Adds a select stage to the query. Returns Query

filter()

filter(self, expr: LogicalExpr | TextExpr) -> Query

Adds a filter stage to the query. Parameters

Parameter	Type
`expr`	`LogicalExpr` \| `TextExpr`

Returns Query

sort()

sort(self, expr: LogicalExpr, asc: bool = True) -> Query

Adds a sort stage to the query. Parameters

Parameter	Type
`expr`	`LogicalExpr`
`asc`	bool

Returns Query

limit()

limit(self, k: int) -> Query

Adds a limit stage to the query. Parameters

Parameter	Type
`k`	int

Returns Query

offset()

offset(self, offset: int) -> Query

Adds an offset stage to the query. Parameters

Parameter	Type
`offset`	int

Returns Query

count()

count(self) -> Query

Adds a count stage to the query. Returns Query

group_by()

group_by(self, keys: dict[str, LogicalExpr], aggs: dict[str, AggregateExpr]) -> Query

Adds a group-by stage to the query. Groups documents by one or more key expressions and computes aggregations for each group. Parameters

Parameter	Type
`keys`	dict[str, `LogicalExpr`]
`aggs`	dict[str, `AggregateExpr`]

Returns Query

topk()

Deprecated — Use .sort(expr, asc).limit(k) instead.

topk(self, expr: LogicalExpr, k: int, asc: bool = False) -> Query

Adds a top-k stage to the query. Parameters

Parameter	Type
`expr`	`LogicalExpr`
`k`	int
`asc`	bool

Returns Query

fn

The query.fn submodule exposes functions for creating function expressions such as fn.vector_distance(), fn.semantic_similarity() or fn.bm25_score(). Methods

vector_distance()

vector_distance(
   field: str,
   vector: list[int] | list[float] | dict[int, float] | dict[int, int] | numpy.ndarray | topk_sdk.data.SparseVector | topk_sdk.data.List,
   skip_refine: bool = False
)

Calculate the vector distance between a field and a query vector.

# Example:

from topk_sdk.query import field, fn, select

client.collection("books").query(
  select(
    "title",
    title_similarity=fn.vector_distance(
      "title_embedding",
      [0.1, 0.2, 0.3, ...] # embedding for "animal"
    )
  )
  .sort(field("title_similarity"), asc=False).limit(10)
)

Parameters

Parameter	Type
`field`	str
`vector`	list[int] \| list[float] \| dict[int, float] \| dict[int, int] \| numpy.ndarray \| `topk_sdk.data.SparseVector` \| `topk_sdk.data.List`
`skip_refine`	bool

Returns FunctionExpr

semantic_similarity()

semantic_similarity(field: str, query: str) -> FunctionExpr

Calculate the semantic similarity between a field and a query string.

# Example:

from topk_sdk.query import field, fn, select

client.collection("books").query(
  select(
    "title",
    title_similarity=fn.semantic_similarity("title", "animal")
  )
  .sort(field("title_similarity"), asc=False).limit(10)
)

Parameters

Parameter	Type
`field`	str
`query`	str

Returns FunctionExpr

bm25_score()

bm25_score(b: Optional[float] = None, k1: Optional[float] = None) -> FunctionExpr

Calculate the BM25 score for a keyword search. Optional parameters: b (0-1), k1 (>=0) to override BM25 scoring behavior.

# Example:

from topk_sdk.query import field, fn, select

client.collection("books").query(
  select(
    "title",
    text_score=fn.bm25_score()
  )
  .filter(match("animal"))
  .sort(field("text_score"), asc=False).limit(10)
)

Parameters

Parameter	Type
`b`	Optional[float]
`k1`	Optional[float]

Returns FunctionExpr

multi_vector_distance()

multi_vector_distance(
   field: str,
   matrix: topk_sdk.data.Matrix | numpy.ndarray | list[list[float]] | list[list[int]],
   candidates: Optional[int] = None
)

Calculate the multi-vector distance between a field and a query matrix. The query matrix can be a list of lists (defaults to f32), a numpy array (type inferred from dtype), or a Matrix instance. To specify a different matrix type, use matrix() with value_type or a 2-D numpy array with the corresponding dtype. The optional candidates parameter limits the number of candidate vectors considered during search.

from topk_sdk.query import field, fn, select

client.collection("books").query(
  select(
    "title",
    title_distance=fn.multi_vector_distance(
      "title_embedding",
      [[0.1, 0.2, 0.3, ...], [0.4, 0.5, 0.6, ...]],
      candidates=100
    )
  )
  .sort(field("title_distance"), asc=False).limit(10)
)

Parameters

Parameter	Type
`field`	str
`matrix`	`topk_sdk.data.Matrix` \| numpy.ndarray \| list[list[float]] \| list[list[int]]
`candidates`	Optional[int]

Returns FunctionExpr

agg

The query.agg submodule exposes functions for creating aggregate expressions used in group_by()’s aggs argument, such as agg.count(), agg.sum(), agg.min(), agg.max() or agg.avg(). Methods

count()

count(field: str | None = None) -> AggregateExpr

Count the number of documents in the group. If field is provided, counts only the documents where that field is non-null. If omitted, counts every document in the group.

# Example:
from topk_sdk.query import group_by, field, agg

client.collection("books").query(
  group_by(
    {"is_old": field("published_year") < 1940},
    {"count": agg.count()},
  )
)

Parameters

Parameter	Type
`field`	str \| None

Returns AggregateExpr

sum()

sum(field: str) -> AggregateExpr

Sum the values of field across the group. Parameters

Parameter	Type
`field`	str

Returns AggregateExpr

min()

min(field: str) -> AggregateExpr

Find the minimum value of field across the group. Parameters

Parameter	Type
`field`	str

Returns AggregateExpr

max()

max(field: str) -> AggregateExpr

Find the maximum value of field across the group. Parameters

Parameter	Type
`field`	str

Returns AggregateExpr

avg()

avg(field: str) -> AggregateExpr

Calculate the average value of field across the group. Parameters

Parameter	Type
`field`	str

Returns AggregateExpr

Functions

field()

field(name: str) -> LogicalExpr

Select a field from the document. Parameters

Parameter	Type
`name`	str

Returns LogicalExpr

select()

select() -> Query

Creates a new query with a select stage.

# Example:
from topk_sdk.query import select, field

client.collection("books").query(
  select("title", year=field("published_year"))
)

Returns Query

filter()

filter(expr: LogicalExpr | TextExpr) -> Query

Creates a new query with a filter stage.

# Example:

from topk_sdk.query import filter, field

client.collection("books").query(
  filter(field("published_year") > 1980)
)

Parameters

Parameter	Type
`expr`	`LogicalExpr` \| `TextExpr`

Returns Query

group_by()

group_by(keys: dict[str, LogicalExpr], aggs: dict[str, AggregateExpr]) -> Query

Creates a new query with a group-by stage. Groups documents by one or more key expressions and computes aggregations for each group.

# Example:
from topk_sdk.query import group_by, field, agg

client.collection("books").query(
  group_by(
    {"is_old": field("published_year") < 1940},
    {"count": agg.count()},
  )
)

Parameters

Parameter	Type
`keys`	dict[str, `LogicalExpr`]
`aggs`	dict[str, `AggregateExpr`]

Returns Query

literal()

literal(value: Any) -> LogicalExpr

Create a literal expression. Parameters

Parameter	Type
`value`	Any

Returns LogicalExpr

match()

match(token: str, field: str | None = None, weight: float = 1.0, all: bool = False) -> TextExpr

Perform a BM25 keyword search using TopK’s built-in tokenizer. The token argument is a raw query string — TopK tokenizes it automatically, removes stop words, and scores documents using BM25. Pass the full query string directly; tokenization and stop-word removal happen server-side.

field: restrict matching to a specific keyword-indexed field (default: all).
weight: scale the BM25 contribution of this expression (default: 1.0).
all: if True, require all tokens to match (AND); default is any-token (OR).

Parameters

Parameter	Type
`token`	str
`field`	str \| None
`weight`	float
`all`	bool

Returns TextExpr

match_tokens()

match_tokens(
   tokens: Sequence[str | tuple[str, float]],
   field: str | None = None,
   all: bool = False
)

Filters documents that match the provided tokens with optional per-token weights. Each token can be a string (with the default weight of 1.0) or a (token, weight) tuple. When field is provided, matches only against that field (must have a keyword index). When field is None (default), matches against all keyword-indexed fields. When all is False (default), matches documents containing any of the tokens (OR). When all is True, matches only documents containing all tokens (AND). Parameters

Parameter	Type
`tokens`	Sequence[str \| tuple[str, float]]
`field`	str \| None
`all`	bool

Returns TextExpr

not_()

not_(expr: LogicalExpr) -> LogicalExpr

Negate a logical expression.

# Example:

from topk_sdk.query import field, not_

.filter(
    not_(field("title").contains("Catcher"))
)

Parameters

Parameter	Type
`expr`	`LogicalExpr`

Returns LogicalExpr

abs()

abs(expr: LogicalExpr) -> LogicalExpr

Compute the absolute value of a logical expression.

# Example:

from topk_sdk.query import field, abs

client.collection("books").query(
  filter(abs(field("rating")) > 4.5)
)

Parameters

Parameter	Type
`expr`	`LogicalExpr`

Returns LogicalExpr

all()

all(exprs: Sequence[LogicalExpr]) -> LogicalExpr

Create a logical AND expression.

# Example:

from topk_sdk.query import field, all

client.collection("books").query(
  filter(all([
    field("published_year") >= 1900,
    field("published_year") <= 2000,
    field("title").is_not_null()
  ]))
)

Parameters

Parameter	Type
`exprs`	Sequence[`LogicalExpr`]

Returns LogicalExpr

any()

any(exprs: Sequence[LogicalExpr]) -> LogicalExpr

Create a logical OR expression.

# Example:

from topk_sdk.query import field, any

client.collection("books").query(
  filter(any([
    field("genre") == "fiction",
    field("genre") == "mystery",
    field("genre") == "thriller"
  ]))
)

Parameters

Parameter	Type
`exprs`	Sequence[`LogicalExpr`]

Returns LogicalExpr

min()

min(left: Ordered, right: Ordered) -> LogicalExpr

Create a logical MIN expression.

# Example:

from topk_sdk.query import field, min

client.collection("books").query(
  filter(min(field("rating"), field("published_year")))
)

Parameters

Parameter	Type
`left`	`Ordered`
`right`	`Ordered`

Returns LogicalExpr

max()

max(left: Ordered, right: Ordered) -> LogicalExpr

Create a logical MAX expression.

from topk_sdk.query import field, max

client.collection("books").query(
  filter(max(field("rating"), field("published_year")))
)

Parameters

Parameter	Type
`left`	`Ordered`
`right`	`Ordered`

Returns LogicalExpr

Type Aliases

FlexibleExpr

FlexibleExpr = str | int | float | bool | None | LogicalExpr

Numeric

Numeric = int | float | LogicalExpr

Type int | float | LogicalExpr

Ordered

Ordered = int | float | str | LogicalExpr

Type int | float | str | LogicalExpr

Boolish

Boolish = bool | LogicalExpr

Type bool | LogicalExpr

Stringy

Stringy = str | LogicalExpr

Type str | LogicalExpr

StringyWithList

StringyWithList = str | list[str] | LogicalExpr

Type str | list[str] | LogicalExpr

Iterable

Iterable = str | list[int] | list[float] | list[str] | topk_sdk.data.List | LogicalExpr

​Classes

​LogicalExpr

​is_null()

​is_not_null()

​abs()

​ln()

​exp()

​sqrt()

​square()

​eq()

​ne()

​lt()

​lte()

​gt()

​gte()

​add()

​sub()

​mul()

​div()

​min()

​max()

​and_()

​or_()

​starts_with()

​contains()

​in_()

​match_all()

​match_any()

​coalesce()

​choose()

​boost()

​regexp_match()

​FunctionExpr

​AggregateExpr

​TextExpr

​Query

​select()

​filter()

​sort()

​limit()

​offset()

​count()

​group_by()

​topk()

​fn

​vector_distance()

​semantic_similarity()

​bm25_score()

​multi_vector_distance()

​agg

​count()

​sum()

​min()

​max()

​avg()

​Functions

​field()

​select()

​filter()

​group_by()

​literal()

​match()

​match_tokens()

​not_()

​abs()

​all()

​any()

​min()

​max()

​Type Aliases

​FlexibleExpr

​Numeric

​Ordered

​Boolish

​Stringy

​StringyWithList

​Iterable

Classes

LogicalExpr

is_null()

is_not_null()

abs()

ln()

exp()

sqrt()

square()

eq()

ne()

lt()

lte()

gt()

gte()

add()

sub()

mul()

div()

min()

max()

and_()

or_()

starts_with()

contains()

in_()

match_all()

match_any()

coalesce()

choose()

boost()

regexp_match()

FunctionExpr

AggregateExpr

TextExpr

Query

select()

filter()

sort()

limit()

offset()

count()

group_by()

topk()

fn

vector_distance()

semantic_similarity()

bm25_score()

multi_vector_distance()

agg

count()

sum()

min()

max()

avg()

Functions

field()

select()

filter()

group_by()

literal()

match()

match_tokens()

not_()

abs()

all()

any()

min()

max()

Type Aliases

FlexibleExpr

Numeric

Ordered

Boolish

Stringy

StringyWithList

Iterable