topk_sdk.data

Classes

List

Internal Instances of the List class are used to represent lists of values in TopK. Usually created using data constructors such as f32_list(), i32_list(), etc.

SparseVector

Internal Instances of the SparseVector class are used to represent sparse vectors in TopK. Usually created using data constructors such as f32_sparse_vector() or u8_sparse_vector().

Matrix

Internal Instances of the Matrix class are used to represent matrices in TopK. Usually created using data constructors such as matrix().

Struct

Internal Instances of the Struct class are used to represent nested object values in TopK. Usually created using the struct() helper.

Image

Instances of the Image class are used to represent images in TopK. Created using the image() helper and returned for image fields by get(). Image fields can’t be selected in queries, use get() with the _ids returned from a query instead. Images read from TopK can be written back as-is without re-encoding. Example:

docs = client.collection("books").get(["gatsby"])
cover = docs["gatsby"]["cover"]

cover.format  # "jpeg"
cover.to_pil().save("cover.jpg")

Properties

Property	Type
`format`	Literal[‘jpeg’, ‘png’]	Encoding format of the image.
`data`	bytes	Encoded image bytes.

Methods

to_pil()

to_pil(self) -> PIL.Image.Image

Decode the image into a PIL image. Requires Pillow (pip install pillow). Returns PIL.Image.Image

UnknownValue

Internal Placeholder for a value this version of the SDK cannot represent.

Functions

f8_vector()

f8_vector(data: list[float]) -> List

Create a List type containing a 8-bit float vector. Example:

from topk_sdk.data import f8_vector

f8_vector([0.12, 0.67, 0.82, 0.53])

Parameters

Parameter	Type
`data`	list[float]

Returns List

f16_vector()

f16_vector(data: list[float]) -> List

Create a List type containing a 16-bit float vector. Example:

from topk_sdk.data import f16_vector

f16_vector([0.12, 0.67, 0.82, 0.53])

Parameters

Parameter	Type
`data`	list[float]

Returns List

f32_vector()

f32_vector(data: list[float]) -> List

Create a List type containing a 32-bit float vector. This function is an alias for f32_list(). Example:

from topk_sdk.data import f32_vector

f32_vector([0.12, 0.67, 0.82, 0.53])

Parameters

Parameter	Type
`data`	list[float]

Returns List

u8_vector()

u8_vector(data: list[int]) -> List

Create a List type containing an 8-bit unsigned integer vector. This function is an alias for u8_list(). Example:

from topk_sdk.data import u8_vector

u8_vector([0, 255, 1, 2, 3])

Parameters

Parameter	Type
`data`	list[int]

Returns List

i8_vector()

i8_vector(data: list[int]) -> List

Create a List type containing an 8-bit signed integer vector. Example:

from topk_sdk.data import i8_vector

i8_vector([-128, 127, -1, 0, 1])

Parameters

Parameter	Type
`data`	list[int]

Returns List

binary_vector()

binary_vector(data: list[int]) -> List

Create a List type containing a binary vector. Example:

from topk_sdk.data import binary_vector

binary_vector([0, 1, 1, 0])

Parameters

Parameter	Type
`data`	list[int]

Returns List

f32_sparse_vector()

f32_sparse_vector(data: dict[int, float]) -> SparseVector

Create a SparseVector type containing a 32-bit float sparse vector. Example:

from topk_sdk.data import f32_sparse_vector

f32_sparse_vector({0: 0.12, 6: 0.67, 17: 0.82, 97: 0.53})

Parameters

Parameter	Type
`data`	dict[int, float]

Returns SparseVector

u8_sparse_vector()

u8_sparse_vector(data: dict[int, int]) -> SparseVector

Create a SparseVector type containing an 8-bit unsigned integer sparse vector. Example:

from topk_sdk.data import u8_sparse_vector

u8_sparse_vector({0: 12, 6: 67, 17: 82, 97: 53})

Parameters

Parameter	Type
`data`	dict[int, int]

Returns SparseVector

bytes()

bytes(data: list[int] | bytes) -> List

Create a List type containing bytes data. Example:

from topk_sdk.data import bytes

bytes([0, 1, 1, 0])

Parameters

Parameter	Type
`data`	list[int] \| bytes

Returns List

u32_list()

u32_list(data: list[int]) -> List

Create a List type containing a list of 32-bit unsigned integers. Example:

from topk_sdk.data import u32_list

u32_list([0, 1, 2, 3])

Parameters

Parameter	Type
`data`	list[int]

Returns List

i32_list()

i32_list(data: list[int]) -> List

Create a List type containing a list of 32-bit signed integers. Example:

from topk_sdk.data import i32_list

i32_list([0, 1, 2, 3])

Parameters

Parameter	Type
`data`	list[int]

Returns List

i64_list()

i64_list(data: list[int]) -> List

Create a List type containing a list of 64-bit signed integers. Example:

from topk_sdk.data import i64_list

i64_list([0, 1, 2, 3])

Parameters

Parameter	Type
`data`	list[int]

Returns List

f32_list()

f32_list(data: list[float]) -> List

Create a List type containing a list of 32-bit floating point numbers. Example:

from topk_sdk.data import f32_list

f32_list([0.12, 0.67, 0.82, 0.53])

Parameters

Parameter	Type
`data`	list[float]

Returns List

f64_list()

f64_list(data: list[float]) -> List

Create a List type containing a list of 64-bit floating point numbers. Example:

from topk_sdk.data import f64_list

f64_list([0.12, 0.67, 0.82, 0.53])

Parameters

Parameter	Type
`data`	list[float]

Returns List

string_list()

string_list(data: list[str]) -> List

Create a List type containing a list of strings. Example:

from topk_sdk.data import string_list

string_list(["foo", "bar", "baz"])

Parameters

Parameter	Type
`data`	list[str]

Returns List

struct()

struct(fields: dict[str, Any]) -> Struct

Create a Struct type containing nested object values. Example:

from topk_sdk.data import struct

struct({"author": "alice", "year": 2024})

Parameters

Parameter	Type
`fields`	dict[str, Any]

Returns Struct

matrix()

matrix(values: list[list[float]] | list[list[int]] | numpy.ndarray, value_type: Optional[Literal['f32', 'f16', 'f8', 'u8', 'i8']] = None) -> Matrix

Create a Matrix type containing matrix values. The values parameter can be a list of lists or a numpy array. When passing a numpy array, the matrix type is inferred from the array’s dtype (float32, float16, uint8, int8). When passing a list of lists, the optional value_type parameter specifies the matrix type. If value_type is not provided, the matrix defaults to f32.

from topk_sdk.data import matrix
import numpy as np

# List of lists with explicit type
matrix([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], "f32")

# List of lists defaults to f32
matrix([[1.0, 2.0], [3.0, 4.0]])

# Numpy array infers type from dtype
matrix(np.array([[1.0, 2.0], [3.0, 4.0]], dtype=np.float16))

Parameters

Parameter	Type
`values`	list[list[float]] \| list[list[int]] \| numpy.ndarray
`value_type`	Optional[Literal[‘f32’, ‘f16’, ‘f8’, ‘u8’, ‘i8’]]

Returns Matrix

image()

image(data: bytes | PIL.Image.Image) -> Image

Create an Image type from encoded JPEG or PNG bytes, or from a PIL image. PIL images can also be used as document values directly. Images decoded from JPEG are kept as JPEG, everything else is encoded as PNG. Image fields are returned as Image, use to_pil() to decode them. Example:

from topk_sdk.data import image
from PIL import Image

# Encoded JPEG or PNG bytes
image(open("cat.jpg", "rb").read())

# PIL image
image(Image.open("cat.jpg"))

Parameters

Parameter	Type
`data`	bytes \| PIL.Image.Image

Returns Image

Overview

SDK Reference

topk_sdk.data

Classes

List

SparseVector

Matrix

Struct

Image

to_pil()

UnknownValue

Functions

f8_vector()

f16_vector()

f32_vector()

u8_vector()

i8_vector()

binary_vector()

f32_sparse_vector()

u8_sparse_vector()

bytes()

u32_list()

i32_list()

i64_list()

f32_list()

f64_list()

string_list()

struct()

matrix()

image()

​Classes

​List

​SparseVector

​Matrix

​Struct

​Image

​to_pil()

​UnknownValue

​Functions

​f8_vector()

​f16_vector()

​f32_vector()

​u8_vector()

​i8_vector()

​binary_vector()

​f32_sparse_vector()

​u8_sparse_vector()

​bytes()

​u32_list()

​i32_list()

​i64_list()

​f32_list()

​f64_list()

​string_list()

​struct()

​matrix()

​image()

Classes

List

SparseVector

Matrix

Struct

Image

to_pil()

UnknownValue

Functions

f8_vector()

f16_vector()

f32_vector()

u8_vector()

i8_vector()

binary_vector()

f32_sparse_vector()

u8_sparse_vector()

bytes()

u32_list()

i32_list()

i64_list()

f32_list()

f64_list()

string_list()

struct()

matrix()

image()