Collections are the core data structure in TopK. They store documents and provide the interface for querying them efficiently.

​
Creating a collection

To create a collection in TopK, call the create() function on client.collections(). The create() function takes two parameters:
​
name
string
required
The name of the collection.
​
schema
Map<String, FieldSpec>
required
Schema definition that describes the document structure.
Below is an example of creating a collection named books: 
from topk_sdk.schema import int, text, f32_vector, vector_index, keyword_index

client.collections().create(
    "books",
    schema={
        "title": text().required().index(keyword_index()),
        "title_embedding": f32_vector(dimension=1536)
            .required()
            .index(vector_index(metric="euclidean")),
        "published_year": int().required(),
    },
)
Field names starting with _ are reserved for internal use.

​
Schema

Collection schema in TopK is a map of field names and field specifications. TopK supports the following field data types:

​
int()

int() function is used to define an integer: 
from topk_sdk.schema import int

"published_year": int()

​
float()

float() function is used to define a float: 
from topk_sdk.schema import float

"price": float()

​
bool()

bool() function is used to define a boolean: 
from topk_sdk.schema import bool

"is_published": bool()

​
text()

text() function is used to define a text: 
from topk_sdk.schema import text

"title": text()

​
bytes()

bytes() is used to define a bytes field in the schema. 
from topk_sdk.schema import bytes

"image": bytes()

​
f32_vector()

f32_vector() function is used to define a vector field with 32-bit floating point values. 
from topk_sdk.schema import f32_vector

"title_embedding": f32_vector(dimension=1536)
To configure the float vector dimension, pass a dimension parameter to the f32_vector() function:
​
dimension
int
required
The dimension of the vector.
The vector dimension will be validated when upserting documents. Passing a vector with a different dimension will result in an error.

​
u8_vector()

u8_vector() function is used to define a vector field with u8 values. 
from topk_sdk.schema import u8_vector

"title_embedding": u8_vector(dimension=1536)
To configure the vector dimension, pass a dimension parameter to the u8_vector() function:
​
dimension
int
required
The dimension of the vector.

​
binary_vector()

binary_vector() function is used to define a binary vector packed into u8 values. You can pass vector dimension as a parameter (required, greater than 0) which will be validated when upserting documents.
Binary vector dimension is defined in terms of the number of bytes. This means that for a 1024-bit binary vector, the dimension topk expects is 128 (1024 / 8).
from topk_sdk.schema import binary_vector

"title_embedding": binary_vector(dimension=128)
To configure the binary vector dimension, pass a dimension parameter to the binary_vector() function:
​
dimension
int
required
The dimension of the vector.

​
f32_sparse_vector()

f32_sparse_vector() function is used to define a sparse vector field with 32-bit floating point values. 
from topk_sdk.schema import f32_sparse_vector

"sparse_field": f32_sparse_vector()
Sparse vectors use u32 dimension indices to support dictionaries of up to 2^32 - 1 terms.

​
u8_sparse_vector()

u8_sparse_vector() function is used to define a sparse vector field with 8-bit unsigned integer values. 
from topk_sdk.schema import u8_sparse_vector

"sparse_field": u8_sparse_vector()
Sparse vectors use u32 dimension indices to support dictionaries of up to 2^32 - 1 terms.

​
list()

list() function is used to define a list field. List can define a list of strings, integers and floats. 
from topk_sdk.schema import list

"tags": list(value_type="text")
​
value_type
"text" | "integer" | "float"
required
The type of the list elements. Supported types: text, integer, float.

​
Properties

​
required()

required() is used to mark a field as required. All fields are optional by default. 
"title": text().required()

​
Functions

​
index()

index() function is used to create an index on a field. This function accepts a single parameter specifying the index type:

​
semantic_index()

This function is used to create both a keyword and a vector on a given field. This allows you to do both semantic search and keyword search over the same field. Note that semantic_index() can only be called over text() data type. 
from topk_sdk.schema import semantic_index

"title": text().index(semantic_index())
Optionally, you can pass a model parameter and embedding_type parameter to the semantic_index() function:
​
model
string
default:"cohere/embed-multilingual-v3"
Embedding model to use for semantic search. Currently, these two models are supported:
  • cohere/embed-english-v3
  • cohere/embed-multilingual-v3 (default)
​
embedding_type
string
default:"float32"
TopK supports the following embedding types for Cohere models:
  • float32
  • uint8
  • binary

​
vector_index()

This function is used to create vector index on a vector field. You can add a vector index on f32_vector, u8_vector, binary_vector, f32_sparse_vector, or u8_sparse_vector fields. 
from topk_sdk.schema import f32_vector, vector_index

"title_embedding": f32_vector(dimension=1536).index(vector_index(metric="cosine"))
You must specify a metric when calling vector_index(). This parameter determines how vector similarity is calculated:
​
metric
string
required
Supported vector distance metrics:
  • euclidean (not supported for sparse vectors)
  • cosine (not supported for sparse vectors)
  • dot_product (supported for dense and sparse vectors)
  • hamming (only supported for binary_vector() type)
Vector fields can be null (i.e., when the field definition is not marked as .required()), in which case no data is stored for that document — null vectors are not substituted with dummy or zero vectors.

​
keyword_index()

This function is used to create a keyword index on a text field: 
from topk_sdk.schema import text, keyword_index

"title": text().index(keyword_index())
Adding a keyword index allows you to perform keyword search on this field.