topk_sdk.schema

Classes

FieldIndex

Internal Instances of the FieldIndex class represents a field index created by vector_index, keyword_index, semantic_index, or multi_vector_index functions.

FieldSpec

Internal Instances of the FieldSpec class represents a field specification created by text, int, float, bool, f32_vector, u8_vector, i8_vector, binary_vector, f32_sparse_vector, u8_sparse_vector, bytes, list, struct, or matrix functions. Methods

required()

required(self) -> FieldSpec

Mark a field as required. All fields are optional by default. Example:

from topk_sdk.schema import text

client.collections().create("books", schema={
    "title": text().required()
})

Returns FieldSpec

optional()

optional(self) -> FieldSpec

Returns FieldSpec

index()

index(self, index: FieldIndex) -> FieldSpec

Create an index on a field. Example:

from topk_sdk.schema import text, keyword_index

client.collections().create("books", schema={
    "title": text().index(keyword_index())
})

Parameters

Parameter	Type
`index`	`FieldIndex`

Returns FieldSpec

Functions

text()

text() -> FieldSpec

Create a FieldSpec type for text values. Example:

from topk_sdk.schema import text

client.collections().create("books", schema={
    "title": text()
})

Returns FieldSpec

int()

int() -> FieldSpec

Create an integer field specification. Returns FieldSpec

float()

float() -> FieldSpec

Create a FieldSpec type for float values. Example:

from topk_sdk.schema import float

client.collections().create("books", schema={
    "price": float()
})

Returns FieldSpec

bool()

bool() -> FieldSpec

Create a FieldSpec type for bool values. Example:

from topk_sdk.schema import bool

client.collections().create("books", schema={
    "is_published": bool()
})

Returns FieldSpec

f8_vector()

f8_vector(dimension: int) -> FieldSpec

Create a FieldSpec type for f8_vector values. Example:

from topk_sdk.schema import f8_vector

client.collections().create("books", schema={
    "title_embedding": f8_vector(dimension=1536)
})

Parameters

Parameter	Type
`dimension`	int

Returns FieldSpec

f16_vector()

f16_vector(dimension: int) -> FieldSpec

Create a FieldSpec type for f16_vector values. Example:

from topk_sdk.schema import f16_vector

client.collections().create("books", schema={
    "title_embedding": f16_vector(dimension=1536)
})

Parameters

Parameter	Type
`dimension`	int

Returns FieldSpec

f32_vector()

f32_vector(dimension: int) -> FieldSpec

Create a FieldSpec type for f32_vector values. Example:

from topk_sdk.schema import f32_vector

client.collections().create("books", schema={
    "title_embedding": f32_vector(dimension=1536)
})

Parameters

Parameter	Type
`dimension`	int

Returns FieldSpec

u8_vector()

u8_vector(dimension: int) -> FieldSpec

Create a FieldSpec type for u8_vector values. Example:

from topk_sdk.schema import u8_vector

client.collections().create("books", schema={
    "title_embedding": u8_vector(dimension=1536)
})

Parameters

Parameter	Type
`dimension`	int

Returns FieldSpec

i8_vector()

i8_vector(dimension: int) -> FieldSpec

Create a FieldSpec type for i8_vector values. Example:

from topk_sdk.schema import i8_vector

client.collections().create("books", schema={
    "title_embedding": i8_vector(dimension=1536)
})

Parameters

Parameter	Type
`dimension`	int

Returns FieldSpec

binary_vector()

binary_vector(dimension: int) -> FieldSpec

Create a FieldSpec type for binary_vector values. Example:

from topk_sdk.schema import binary_vector

client.collections().create("books", schema={
    "title_embedding": binary_vector(dimension=128)
})

Parameters

Parameter	Type
`dimension`	int

Returns FieldSpec

f32_sparse_vector()

f32_sparse_vector() -> FieldSpec

Create a FieldSpec type for f32_sparse_vector values. Note: Sparse vectors use u32 dimension indices to support dictionaries of up to 2^32 - 1 terms. Example:

from topk_sdk.schema import f32_sparse_vector

client.collections().create("books", schema={
    "sparse_field": f32_sparse_vector()
})

Returns FieldSpec

u8_sparse_vector()

u8_sparse_vector() -> FieldSpec

Create a FieldSpec type for u8_sparse_vector values. Note: Sparse vectors use u32 dimension indices to support dictionaries of up to 2^32 - 1 terms. Example:

from topk_sdk.schema import u8_sparse_vector

client.collections().create("books", schema={
    "sparse_field": u8_sparse_vector()
})

Returns FieldSpec

bytes()

bytes() -> FieldSpec

Create a FieldSpec type for bytes values. Example:

from topk_sdk.schema import bytes

client.collections().create("books", schema={
    "image": bytes()
})

Returns FieldSpec

timestamp()

timestamp() -> FieldSpec

Create a FieldSpec type for timestamp values. Timestamps are stored as milliseconds since UNIX epoch. When upserting timestamps, use:

datetime.datetime — timezone-aware datetime (timezone-naive datetimes are not supported)
datetime.date — date (padded to midnight UTC)
int — epoch milliseconds

Example:

from topk_sdk.schema import timestamp

client.collections().create("books", schema={
    "published_ts": timestamp()
})

Returns FieldSpec

list()

list(value_type: Literal['text', 'integer', 'float']) -> FieldSpec

Create a FieldSpec type for list values. Example:

from topk_sdk.schema import list

client.collections().create("books", schema={
    "tags": list(value_type="text")
})

Parameters

Parameter	Type
`value_type`	Literal[‘text’, ‘integer’, ‘float’]

Returns FieldSpec

struct()

struct(fields: Mapping[str, SchemaFieldSpec]) -> FieldSpec

Create a FieldSpec type for struct values. Example:

from topk_sdk.schema import int, struct, text

client.collections().create("books", schema={
    "meta": struct({"author": text(), "year": int()})
})

Parameters

Parameter	Type
`fields`	Mapping[str, `SchemaFieldSpec`]

Returns FieldSpec

matrix()

matrix(dimension: int, value_type: Literal['f32', 'f16', 'f8', 'u8', 'i8']) -> FieldSpec

Create a FieldSpec type for matrix values. Supported value_types:

f32
f16
f8
u8
i8

Example:

from topk_sdk.schema import matrix

client.collections().create("books", schema={
    "title_embedding": matrix(dimension=1536, value_type="f32")
})

Parameters

Parameter	Type
`dimension`	int
`value_type`	Literal[‘f32’, ‘f16’, ‘f8’, ‘u8’, ‘i8’]

Returns FieldSpec

vector_index()

vector_index(metric: Literal['cosine', 'euclidean', 'dot_product', 'hamming']) -> FieldIndex

Create a FieldIndex type for vector_index values. Supported metrics:

euclidean (only dense vectors)
cosine (only dense vectors)
dot_product (dense and sparse vectors)
hamming (only binary vectors)

Example:

from topk_sdk.schema import f32_vector, vector_index

client.collections().create("books", schema={
    "title_embedding": f32_vector(dimension=1536).index(vector_index(metric="cosine"))
})

Parameters

Parameter	Type
`metric`	Literal[‘cosine’, ‘euclidean’, ‘dot_product’, ‘hamming’]

Returns FieldIndex

keyword_index()

keyword_index(type: Literal['text', 'exact'] = "text") -> FieldIndex

Create a FieldIndex type for keyword_index values. Supported index types:

text (default) - text is tokenized before indexing
exact - text is indexed as a single term

Example:

from topk_sdk.schema import text, keyword_index

client.collections().create("books", schema={
    "title": text().index(keyword_index())
})

Parameters

Parameter	Type
`type`	Literal[‘text’, ‘exact’]

Returns FieldIndex

semantic_index()

semantic_index() -> FieldIndex

Create a FieldIndex type for semantic_index values. Example:

from topk_sdk.schema import text, semantic_index

client.collections().create("books", schema={
    "title": text().index(semantic_index())
})

Returns FieldIndex

multi_vector_index()

multi_vector_index(
   metric: Literal['maxsim'],
   quantization: Optional[Literal['1bit', '2bit', 'scalar']] = None,
   width: Optional[int] = None,
   top_k: Optional[int] = None
)

Create a FieldIndex type for multi_vector_index values. Supported metrics:

maxsim

Example:

from topk_sdk.schema import matrix, multi_vector_index

client.collections().create("books", schema={
    "title_embedding": matrix(dimension=1536, value_type="f32").index(multi_vector_index(metric="maxsim"))
})

Parameters

Parameter	Type
`metric`	Literal[‘maxsim’]
`quantization`	Optional[Literal[‘1bit’, ‘2bit’, ‘scalar’]]
`width`	Optional[int]
`top_k`	Optional[int]

Returns FieldIndex

Type Aliases

SchemaFieldSpec

SchemaFieldSpec = FieldSpec | Mapping[str, 'SchemaFieldSpec']

Type FieldSpec | Mapping[str, ‘SchemaFieldSpec’]

Overview

SDK Reference

topk_sdk.schema

Classes

FieldIndex

FieldSpec

required()

optional()

index()

Functions

text()

int()

float()

bool()

f8_vector()

f16_vector()

f32_vector()

u8_vector()

i8_vector()

binary_vector()

f32_sparse_vector()

u8_sparse_vector()

bytes()

timestamp()

list()

struct()

matrix()

vector_index()

keyword_index()

semantic_index()

multi_vector_index()

Type Aliases

SchemaFieldSpec

​Classes

​FieldIndex

​FieldSpec

​required()

​optional()

​index()

​Functions

​text()

​int()

​float()

​bool()

​f8_vector()

​f16_vector()

​f32_vector()

​u8_vector()

​i8_vector()

​binary_vector()

​f32_sparse_vector()

​u8_sparse_vector()

​bytes()

​timestamp()

​list()

​struct()

​matrix()

​vector_index()

​keyword_index()

​semantic_index()

​multi_vector_index()

​Type Aliases

​SchemaFieldSpec

Classes

FieldIndex

FieldSpec

required()

optional()

index()

Functions

text()

int()

float()

bool()

f8_vector()

f16_vector()

f32_vector()

u8_vector()

i8_vector()

binary_vector()

f32_sparse_vector()

u8_sparse_vector()

bytes()

timestamp()

list()

struct()

matrix()

vector_index()

keyword_index()

semantic_index()

multi_vector_index()

Type Aliases

SchemaFieldSpec