Overview
The schema module provides functions to define field types and indexes for TopK collections. Import schema functions from topk-js/schema.
import {
text,
int,
float,
bool,
bytes,
list,
f32Vector,
f16Vector,
f8Vector,
binaryVector,
matrix,
semanticIndex,
vectorIndex,
multiVectorIndex,
keywordIndex
} from "topk-js/schema";
FieldSpec
Represents a field specification that can be used to define a field in a collection schema. All schema functions return a FieldSpec object.
Methods
required()
Marks the field as required. All fields are optional by default.
import { text } from "topk-js/schema";
await client.collections().create("books", {
title: text().required()
});
index(index)
Creates an index on a field.
The index configuration to apply to the field
import { text, keywordIndex } from "topk-js/schema";
await client.collections().create("books", {
title: text().index(keywordIndex())
});
Scalar Field Types
text()
Creates a FieldSpec for text values.
import { text } from "topk-js/schema";
await client.collections().create("books", {
title: text(),
author: text().required()
});
int()
Creates a FieldSpec for integer values.
import { int } from "topk-js/schema";
await client.collections().create("books", {
published_year: int(),
page_count: int()
});
float()
Creates a FieldSpec for floating-point values.
import { float } from "topk-js/schema";
await client.collections().create("books", {
price: float(),
rating: float()
});
bool()
Creates a FieldSpec for boolean values.
import { bool } from "topk-js/schema";
await client.collections().create("books", {
is_published: bool(),
in_stock: bool()
});
bytes()
Creates a FieldSpec for binary data.
import { bytes } from "topk-js/schema";
await client.collections().create("books", {
cover_image: bytes(),
thumbnail: bytes()
});
List Field Type
list(options)
Creates a FieldSpec for list values.
Configuration options for the list field
The type of values the list can contain. Can be: import { list } from "topk-js/schema";
await client.collections().create("books", {
tags: list({ valueType: "text" }),
chapter_lengths: list({ valueType: "integer" }),
ratings: list({ valueType: "float" })
});
Vector Field Types
f32Vector(options)
Creates a FieldSpec for 32-bit float vector values.
Configuration options for the vector field
The dimension of the vector
import { f32Vector } from "topk-js/schema";
await client.collections().create("books", {
title_embedding: f32Vector({ dimension: 1536 })
});
f16Vector(options)
Creates a FieldSpec for 16-bit float vector values.
Configuration options for the vector field
The dimension of the vector
import { f16Vector } from "topk-js/schema";
await client.collections().create("books", {
title_embedding: f16Vector({ dimension: 1536 })
});
f8Vector(options)
Creates a FieldSpec for 8-bit float vector values.
Configuration options for the vector field
The dimension of the vector
import { f8Vector } from "topk-js/schema";
await client.collections().create("books", {
title_embedding: f8Vector({ dimension: 1536 })
});
binaryVector(options)
Creates a FieldSpec for binary vector values.
Configuration options for the vector field
The dimension of the vector
import { binaryVector } from "topk-js/schema";
await client.collections().create("books", {
title_embedding: binaryVector({ dimension: 128 })
});
u8Vector(options)
Creates a FieldSpec for 8-bit unsigned integer vector values.
Configuration options for the vector field
The dimension of the vector
import { u8Vector } from "topk-js/schema";
await client.collections().create("books", {
title_embedding: u8Vector({ dimension: 1536 })
});
i8Vector(options)
Creates a FieldSpec for 8-bit signed integer vector values.
Configuration options for the vector field
The dimension of the vector
import { i8Vector } from "topk-js/schema";
await client.collections().create("books", {
title_embedding: i8Vector({ dimension: 1536 })
});
Sparse Vector Field Types
f32SparseVector()
Creates a FieldSpec for 32-bit float sparse vector values.
Sparse vectors use u32 dimension indices to support dictionaries of up to 2^32 - 1 terms.
import { f32SparseVector } from "topk-js/schema";
await client.collections().create("books", {
sparse_field: f32SparseVector()
});
u8SparseVector()
Creates a FieldSpec for 8-bit unsigned integer sparse vector values.
Sparse vectors use u32 dimension indices to support dictionaries of up to 2^32 - 1 terms.
import { u8SparseVector } from "topk-js/schema";
await client.collections().create("books", {
sparse_field: u8SparseVector()
});
Matrix Field Type
matrix(options)
Creates a FieldSpec for matrix values.
Configuration options for the matrix field
The dimension (number of columns) of the matrix
The value type of the matrix elements. Can be:
'f32' - 32-bit float'f16' - 16-bit float'f8' - 8-bit float'u8' - 8-bit unsigned integer'i8' - 8-bit signed integer
import { matrix } from "topk-js/schema";
await client.collections().create("books", {
token_embeddings: matrix({ dimension: 768, valueType: "f32" })
});
Index Types
semanticIndex(options?)
Creates a FieldIndex for semantic search. This index automatically generates embeddings from text fields and enables semantic similarity search.
Optional configuration for the semantic index
Embedding model to use for semantic search. Currently supported:
cohere/embed-english-v3cohere/embed-multilingual-v3cohere/embed-v4 (default)
TopK supports the following embedding types for Cohere models:
'float32''uint8''binary'
import { text, semanticIndex } from "topk-js/schema";
await client.collections().create("books", {
title: text().index(semanticIndex())
});
vectorIndex(options)
Creates a FieldIndex for vector similarity search.
options
VectorIndexOptions
required
Configuration options for the vector index
options.metric
VectorDistanceMetric
required
The distance metric to use for vector similarity. Can be:
'cosine' (not supported for sparse vectors)'euclidean' (not supported for sparse vectors)'dot_product' (supported for dense and sparse vectors)'hamming' (only supported for binary_vector type)
import { f32Vector, vectorIndex } from "topk-js/schema";
await client.collections().create("books", {
title_embedding: f32Vector({ dimension: 1536 }).index(
vectorIndex({ metric: "cosine" })
)
});
multiVectorIndex(options)
Creates a FieldIndex for multi-vector similarity search.
options
MultiVectorIndexOptions
required
Configuration options for the multi-vector index
options.metric
MultiVectorDistanceMetric
required
The distance metric to use for multi-vector similarity. Currently supported: Number of bits to use for multi-vector sketch
The quantization to use for multi-vector values. Can be: import { matrix, multiVectorIndex } from "topk-js/schema";
await client.collections().create("books", {
token_embeddings: matrix({ dimension: 768, valueType: "f32" }).index(
multiVectorIndex({ metric: "maxsim" })
)
});
keywordIndex()
Creates a FieldIndex for keyword search. This index enables full-text search on text fields.
import { text, keywordIndex } from "topk-js/schema";
await client.collections().create("books", {
title: text().index(keywordIndex()),
description: text().index(keywordIndex())
});
Complete Schema Example
import {
text,
int,
float,
bool,
list,
f32Vector,
matrix,
semanticIndex,
vectorIndex,
multiVectorIndex,
keywordIndex
} from "topk-js/schema";
await client.collections().create("books", {
// Required text field with semantic search
title: text().required().index(semanticIndex()),
// Text field with keyword search
description: text().index(keywordIndex()),
// Scalar fields
author: text(),
published_year: int(),
price: float(),
in_stock: bool(),
// List field
tags: list({ valueType: "text" }),
// Dense vector with cosine similarity
title_embedding: f32Vector({ dimension: 1536 }).index(
vectorIndex({ metric: "cosine" })
),
// Matrix for multi-vector search
token_embeddings: matrix({ dimension: 768, valueType: "f32" }).index(
multiVectorIndex({ metric: "maxsim" })
)
});
