> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# topk_sdk.schema

## Classes

### FieldIndex

*Internal*

Instances of the `FieldIndex` class represents a field index created by [`vector_index`](#vector-index), [`keyword_index`](#keyword-index), [`semantic_index`](#semantic-index), or [`multi_vector_index`](#multi-vector-index) functions.

### FieldSpec

*Internal*

Instances of the `FieldSpec` class represents a field specification created by [`text`](#text), [`int`](#int), [`float`](#float), [`bool`](#bool), [`f32_vector`](#f32-vector), [`u8_vector`](#u8-vector), [`i8_vector`](#i8-vector), [`binary_vector`](#binary-vector), [`f32_sparse_vector`](#f32-sparse-vector), [`u8_sparse_vector`](#u8-sparse-vector), [`bytes`](#bytes), [`list`](#list), [`struct`](#struct), or [`matrix`](#matrix) functions.

**Methods**

#### required()

```python theme={null}
required(self) -> FieldSpec
```

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

Example:

```python theme={null}
from topk_sdk.schema import text

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

**Returns**

[`FieldSpec`](#fieldspec)

***

#### optional()

```python theme={null}
optional(self) -> FieldSpec
```

**Returns**

[`FieldSpec`](#fieldspec)

***

#### index()

```python theme={null}
index(self, index: FieldIndex) -> FieldSpec
```

Create an index on a field.

Example:

```python theme={null}
from topk_sdk.schema import text, keyword_index

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

**Parameters**

| Parameter | Type                        |
| --------- | --------------------------- |
| `index`   | [`FieldIndex`](#fieldindex) |

**Returns**

[`FieldSpec`](#fieldspec)

***

## Functions

### text()

```python theme={null}
text() -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `text` values.

Example:

```python theme={null}
from topk_sdk.schema import text

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

**Returns**

[`FieldSpec`](#fieldspec)

***

### int()

```python theme={null}
int() -> FieldSpec
```

Create an integer field specification.

**Returns**

[`FieldSpec`](#fieldspec)

***

### float()

```python theme={null}
float() -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `float` values.

Example:

```python theme={null}
from topk_sdk.schema import float

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

**Returns**

[`FieldSpec`](#fieldspec)

***

### bool()

```python theme={null}
bool() -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `bool` values.

Example:

```python theme={null}
from topk_sdk.schema import bool

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

**Returns**

[`FieldSpec`](#fieldspec)

***

### f8\_vector()

```python theme={null}
f8_vector(dimension: int) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `f8_vector` values.

Example:

```python theme={null}
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`](#fieldspec)

***

### f16\_vector()

```python theme={null}
f16_vector(dimension: int) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `f16_vector` values.

Example:

```python theme={null}
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`](#fieldspec)

***

### f32\_vector()

```python theme={null}
f32_vector(dimension: int) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `f32_vector` values.

Example:

```python theme={null}
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`](#fieldspec)

***

### u8\_vector()

```python theme={null}
u8_vector(dimension: int) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `u8_vector` values.

Example:

```python theme={null}
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`](#fieldspec)

***

### i8\_vector()

```python theme={null}
i8_vector(dimension: int) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `i8_vector` values.

Example:

```python theme={null}
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`](#fieldspec)

***

### binary\_vector()

```python theme={null}
binary_vector(dimension: int) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `binary_vector` values.

Example:

```python theme={null}
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`](#fieldspec)

***

### f32\_sparse\_vector()

```python theme={null}
f32_sparse_vector() -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#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:

```python theme={null}
from topk_sdk.schema import f32_sparse_vector

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

**Returns**

[`FieldSpec`](#fieldspec)

***

### u8\_sparse\_vector()

```python theme={null}
u8_sparse_vector() -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#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:

```python theme={null}
from topk_sdk.schema import u8_sparse_vector

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

**Returns**

[`FieldSpec`](#fieldspec)

***

### bytes()

```python theme={null}
bytes() -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `bytes` values.

Example:

```python theme={null}
from topk_sdk.schema import bytes

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

**Returns**

[`FieldSpec`](#fieldspec)

***

### list()

```python theme={null}
list(value_type: Literal['text', 'integer', 'float']) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `list` values.

Example:

```python theme={null}
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`](#fieldspec)

***

### struct()

```python theme={null}
struct(fields: dict[str, FieldSpec]) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `struct` values.

Example:

```python theme={null}
from topk_sdk.schema import int, struct, text

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

**Parameters**

| Parameter | Type                                  |
| --------- | ------------------------------------- |
| `fields`  | dict\[str, [`FieldSpec`](#fieldspec)] |

**Returns**

[`FieldSpec`](#fieldspec)

***

### matrix()

```python theme={null}
matrix(dimension: int, value_type: Literal['f32', 'f16', 'f8', 'u8', 'i8']) -> FieldSpec
```

Create a [FieldSpec](/sdk/topk-py/schema#FieldSpec) type for `matrix` values.

Supported `value_type`s:

* `f32`
* `f16`
* `f8`
* `u8`
* `i8`

Example:

```python theme={null}
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`](#fieldspec)

***

### vector\_index()

```python theme={null}
vector_index(metric: Literal['cosine', 'euclidean', 'dot_product', 'hamming']) -> FieldIndex
```

Create a [FieldIndex](/sdk/topk-py/schema#FieldSpec) type for `vector_index` values.

Supported `metric`s:

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

Example:

```python theme={null}
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`](#fieldindex)

***

### keyword\_index()

```python theme={null}
keyword_index() -> FieldIndex
```

Create a [FieldIndex](/sdk/topk-py/schema#FieldIndex) type for `keyword_index` values.

Example:

```python theme={null}
from topk_sdk.schema import text, keyword_index

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

**Returns**

[`FieldIndex`](#fieldindex)

***

### semantic\_index()

```python theme={null}
semantic_index() -> FieldIndex
```

Create a [FieldIndex](/sdk/topk-py/schema#FieldIndex) type for `semantic_index` values.

Example:

```python theme={null}
from topk_sdk.schema import text, semantic_index

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

**Returns**

[`FieldIndex`](#fieldindex)

***

### multi\_vector\_index()

```python theme={null}
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](/sdk/topk-py/schema#FieldIndex) type for `multi_vector_index` values.

Supported `metric`s:

* `maxsim`

Example:

```python theme={null}
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`](#fieldindex)

***