Query - TopK

Overview

The query module provides functions and classes to build queries for searching and filtering data in TopK collections. Import query functions from topk-js/query.

import { 
  select, 
  filter, 
  field, 
  literal,
  match,
  fn 
} from "topk-js/query";

Query Building

select(exprs)

Creates a new query with a select stage. The select stage defines which fields and computed values to return.

exprs

Record<string, LogicalExpression | FunctionExpression>

required

A map of field names to expressions

import { select, field } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    author: field("author")
  })
);

filter(expr)

Creates a new query with a filter stage. The filter stage restricts which documents are returned.

expr

LogicalExpression | TextExpression

required

The filter expression

import { filter, field } from "topk-js/query";

const results = await client.collection("books").query(
  filter(field("published_year").gt(2000))
);

Query Class

A query object that represents a sequence of query stages. Queries are built by chaining together different stages like select, filter, topk, etc.

filter(expr)

Adds a filter stage to the query.

expr

LogicalExpression | TextExpression

required

The filter expression

select(exprs)

Adds a select stage to the query.

exprs

Record<string, LogicalExpression | FunctionExpression>

required

A map of field names to expressions

topk(expr, k, asc?)

Adds a top-k stage to the query. Returns the top k documents based on the expression.

expr

LogicalExpression

required

The expression to rank by

number

required

The number of documents to return

asc

boolean

Whether to sort in ascending order. Defaults to false (descending)

import { select, field, fn } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    similarity: fn.semanticSimilarity("title", "dystopian future")
  })
  .topk(field("similarity"), 10)
);

limit(k)

Adds a limit stage to the query.

number

required

The maximum number of documents to return

sort(expr, asc?)

Adds a sort stage to the query.

expr

LogicalExpression

required

The expression to sort by

asc

boolean

Whether to sort in ascending order. Defaults to false (descending)

import { select, field } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    year: field("published_year")
  })
  .sort(field("published_year"), true)
);

count()

Adds a count stage to the query.

import { filter, field } from "topk-js/query";

const results = await client.collection("books").query(
  filter(field("published_year").gt(2000))
  .count()
);

rerank(options?)

Adds a rerank stage to the query.

options

RerankOptions

Optional reranking configuration

options.model

string

The reranking model to use

options.query

string

The query text for reranking

options.fields

Array<string>

Fields to include in reranking

options.topkMultiple

number

Multiple of top-k to consider for reranking

Expression Functions

field(name)

Creates a field reference expression.

name

string

required

The name of the field to reference

import { field } from "topk-js/query";

const titleField = field("title");
const yearField = field("published_year");

literal(value)

Creates a literal value expression.

value

required

The literal value

import { literal, field } from "topk-js/query";

const expr = field("price").lt(literal(25.99));

match(token, options?)

Creates a text match expression for keyword search.

token

string

required

The token to match

options

MatchOptions

Optional matching configuration

options.field

string

Field to match against

options.weight

number

Weight for the match

options.all

boolean

Whether to match all terms

import { match } from "topk-js/query";

const results = await client.collection("books").query(
  filter(match("science fiction", { field: "genre" }))
);

Utility Functions

abs(expr)

Creates an absolute value expression.

expr

LogicalExpression

required

The expression to compute absolute value of

all(exprs)

Evaluates to true if each expression is true (logical AND).

exprs

Array<LogicalExpression>

required

Array of expressions to evaluate

any(exprs)

Evaluates to true if at least one expression is true (logical OR).

exprs

Array<LogicalExpression>

required

Array of expressions to evaluate

min(left, right)

Creates a MIN expression that returns the smaller of two values.

left

LogicalExpression | number | string

required

First value

right

LogicalExpression | number | string

required

Second value

max(left, right)

Creates a MAX expression that returns the larger of two values.

left

LogicalExpression | number | string

required

First value

right

LogicalExpression | number | string

required

Second value

not(expr)

Creates a logical NOT expression.

expr

LogicalExpression

required

The expression to negate

LogicalExpression

Represents a logical expression that can be used in queries. LogicalExpressions support method chaining for building complex queries.

Comparison Methods

eq(other)

Checks if the expression equals another value.

other

LogicalExpression | string | number | boolean | null

required

The value to compare against

import { field } from "topk-js/query";

const expr = field("author").eq("George Orwell");

ne(other)

Checks if the expression does not equal another value.

lt(other)

Checks if the expression is less than another value.

other

LogicalExpression | number | string

required

The value to compare against

lte(other)

Checks if the expression is less than or equal to another value.

gt(other)

Checks if the expression is greater than another value.

gte(other)

Checks if the expression is greater than or equal to another value.

import { field } from "topk-js/query";

// Greater than
const recentBooks = field("published_year").gt(2020);

// Less than or equal
const affordableBooks = field("price").lte(19.99);

// Not equal
const nonFiction = field("genre").ne("fiction");

Logical Methods

and(other)

Computes the logical AND of the expression and another expression.

other

LogicalExpression | boolean

required

The expression to AND with

import { field } from "topk-js/query";

const expr = field("published_year").gt(2000)
  .and(field("price").lt(25));

or(other)

Computes the logical OR of the expression and another expression.

other

LogicalExpression | boolean

required

The expression to OR with

Null Checks

isNull()

Checks if the expression evaluates to null.

isNotNull()

Checks if the expression evaluates to a non-null value.

import { field } from "topk-js/query";

const hasAuthor = field("author").isNotNull();

Math Methods

abs()

Computes the absolute value of the expression.

ln()

Computes the natural logarithm of the expression.

exp()

Computes the exponential of the expression.

sqrt()

Computes the square root of the expression.

square()

Computes the square of the expression.

add(other)

Adds another value to the expression.

sub(other)

Subtracts another value from the expression.

mul(other)

Multiplies the expression by another value.

div(other)

Divides the expression by another value.

min(other)

Computes the minimum of the expression and another value.

max(other)

Computes the maximum of the expression and another value.

import { select, field } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    price: field("price"),
    // 20% discount
    discounted_price: field("price").mul(0.8),
    // Rounded price
    rounded_price: field("price").add(0.5).abs()
  })
);

String Methods

startsWith(other)

Checks if the expression starts with another value. Can be applied to a string field or a list of strings field.

other

LogicalExpression | string

required

The value to check for

import { filter, field } from "topk-js/query";

const results = await client.collection("books").query(
  filter(
    field("title").startsWith("The")
    .or(field("tags").startsWith("fiction"))
  )
);

contains(other)

Checks if the expression contains another value.

other

LogicalExpression | string | number

required

The value to check for

in(other)

Checks if the expression is in another value.

other

LogicalExpression | string | Array<string> | Array<number> | data.List

required

The value or list to check against

import { filter, field } from "topk-js/query";

const results = await client.collection("books").query(
  filter(field("genre").in(["fiction", "fantasy", "sci-fi"]))
);

Keyword Search Methods

matchAll(other)

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

other

LogicalExpression | string | string[]

required

The terms to match

matchAny(other)

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

other

LogicalExpression | string | string[]

required

The terms to match

import { filter, field } from "topk-js/query";

const results = await client.collection("books").query(
  filter(field("tags").matchAny(["fiction", "fantasy"]))
);

Other Methods

coalesce(other)

Coalesces nulls in the expression with another value.

other

LogicalExpression | number

required

The value to use if the expression is null

choose(x, y)

Chooses between two values based on the expression.

LogicalExpression | string | number | boolean | null

required

Value to return if expression is true

LogicalExpression | string | number | boolean | null

required

Value to return if expression is false

boost(condition, boost)

Multiplies the scoring expression by the provided boost value if the condition is true. Otherwise, the scoring expression is unchanged (multiplied by 1).

condition

LogicalExpression | boolean

required

The condition to check

boost

LogicalExpression | number

required

The boost multiplier

regexpMatch(pattern, flags?)

Check if the expression matches the provided regexp pattern.

pattern

string

required

The regular expression pattern

flags

string

Optional regex flags

Function Expressions (fn)

Function expressions compute special values like semantic similarity or vector distance. Import from topk-js/query as fn.

import { fn } from "topk-js/query";

fn.semanticSimilarity(field, query)

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

field

string

required

The name of the field to search

query

string

required

The query text

import { select, field, fn } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    similarity: fn.semanticSimilarity("title", "classic American novel")
  })
  .topk(field("similarity"), 10)
);

fn.vectorDistance(field, query, options?)

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

field

string

required

The name of the vector field

query

Array<number> | Record<number, number> | data.List | data.SparseVector

required

The query vector (dense or sparse)

options

VectorDistanceOptions

Optional configuration

options.skipRefine

boolean

Whether to skip refinement step

import { select, field, fn } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    distance: fn.vectorDistance(
      "title_embedding",
      [0.1, 0.2, 0.3, /* ... */]
    )
  })
  .topk(field("distance"), 10)
);

fn.multiVectorDistance(field, query, candidates?)

Calculates the multi-vector distance between a field and a query matrix.

field

string

required

The name of the matrix field

query

Array<Array<number>> | data.Matrix

required

The query matrix. Can be an array of number arrays (defaults to f32), or a Matrix instance

candidates

number

Limits the number of candidate vectors considered during retrieval

import { select, field, fn } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    distance: fn.multiVectorDistance(
      "token_embeddings",
      [
        [0.1, 0.2, 0.3, /* ... */],
        [0.4, 0.5, 0.6, /* ... */]
      ],
      100
    )
  })
  .topk(field("distance"), 10)
);

fn.bm25Score()

Computes the BM25 score for a keyword search.

import { select, field, match, fn } from "topk-js/query";

const results = await client.collection("books").query(
  filter(match("science fiction", { field: "description" }))
  .select({
    title: field("title"),
    score: fn.bm25Score()
  })
  .topk(field("score"), 10)
);

Complete Query Examples

import { select, field, fn } from "topk-js/query";

const results = await client.collection("books").query(
  select({
    title: field("title"),
    author: field("author"),
    similarity: fn.semanticSimilarity("title", "dystopian future")
  })
  .topk(field("similarity"), 10)
);

API Reference

​Overview

​Query Building

​select(exprs)

​filter(expr)

​Query Class

​filter(expr)

​select(exprs)

​topk(expr, k, asc?)

​limit(k)

​sort(expr, asc?)

​count()

​rerank(options?)

​Expression Functions

​field(name)

​literal(value)

​match(token, options?)

​Utility Functions

​abs(expr)

​all(exprs)

​any(exprs)

​min(left, right)

​max(left, right)

​not(expr)

​LogicalExpression

​Comparison Methods

​eq(other)

​ne(other)

​lt(other)

​lte(other)

​gt(other)

​gte(other)

​Logical Methods

​and(other)

​or(other)

​Null Checks

​isNull()

​isNotNull()

​Math Methods

​abs()

​ln()

​exp()

​sqrt()

​square()

​add(other)

​sub(other)

​mul(other)

​div(other)

​min(other)

​max(other)

​String Methods

​startsWith(other)

​contains(other)

​in(other)

​Keyword Search Methods

​matchAll(other)

​matchAny(other)

​Other Methods

​coalesce(other)

​choose(x, y)

​boost(condition, boost)

​regexpMatch(pattern, flags?)

​Function Expressions (fn)

​fn.semanticSimilarity(field, query)

​fn.vectorDistance(field, query, options?)

​fn.multiVectorDistance(field, query, candidates?)

​fn.bm25Score()

​Complete Query Examples

Build docs developers (and LLMs) love

Overview

Query Building

select(exprs)

filter(expr)

Query Class

filter(expr)

select(exprs)

topk(expr, k, asc?)

limit(k)

sort(expr, asc?)

count()

rerank(options?)

Expression Functions

field(name)

literal(value)

match(token, options?)

Utility Functions

abs(expr)

all(exprs)

any(exprs)

min(left, right)

max(left, right)

not(expr)

LogicalExpression

Comparison Methods

eq(other)

ne(other)

lt(other)

lte(other)

gt(other)

gte(other)

Logical Methods

and(other)

or(other)

Null Checks

isNull()

isNotNull()

Math Methods

abs()

ln()

exp()

sqrt()

square()

add(other)

sub(other)

mul(other)

div(other)

min(other)

max(other)

String Methods

startsWith(other)

contains(other)

in(other)

Keyword Search Methods

matchAll(other)

matchAny(other)

Other Methods

coalesce(other)

choose(x, y)

boost(condition, boost)

regexpMatch(pattern, flags?)

Function Expressions (fn)

fn.semanticSimilarity(field, query)

fn.vectorDistance(field, query, options?)

fn.multiVectorDistance(field, query, candidates?)

fn.bm25Score()

Complete Query Examples