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().

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

count()

count(self) -> Query

Adds a count stage to the query. Returns Query

topk()

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] | 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"
    )
  )
  .topk(field("title_similarity"), 10)
)

Parameters

Parameter	Type
`field`	str
`vector`	list[int] \| list[float] \| dict[int, float] \| dict[int, int] \| `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")
  )
  .topk(field("title_similarity"), 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"))
  .topk(field("text_score"), 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 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
    )
  )
  .topk(field("title_distance"), 10)
)

Parameters

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

Returns FunctionExpr

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

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 keyword search for documents that contain specific keywords or phrases. This function should be used in the filter stage of a query. You can configure the match() function to:

Match on multiple terms
Match only on specific fields
Use weights to prioritize certain terms

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

SDK Reference

Overview

Documentation Index

​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

​TextExpr

​Query

​select()

​filter()

​sort()

​limit()

​count()

​topk()

​fn

​vector_distance()

​semantic_similarity()

​bm25_score()

​multi_vector_distance()

​Functions

​field()

​select()

​filter()

​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

TextExpr

Query

select()

filter()

sort()

limit()

count()

topk()

fn

vector_distance()

semantic_similarity()

bm25_score()

multi_vector_distance()

Functions

field()

select()

filter()

literal()

match()

match_tokens()

not_()

abs()

all()

any()

min()

max()

Type Aliases

FlexibleExpr

Numeric

Ordered

Boolish

Stringy

StringyWithList

Iterable