Note
This feature is an experimental feature in the current version.
This topic summarizes the commonly used pyseekdb interface signatures in this scenario for easy reference.
Client APIs
import pyseekdb
# Create a client (to connect to OceanBase)
# host/tenant/database/user/password: str;port: int
client = pyseekdb.Client(
host="localhost", port=2881,
tenant="test", database="test",
user="root", password="",
)
# Create a collection. In this scenario, you must set use_namespace=True.
# name: str, consisting only of letters, digits, and underscores, with a maximum length of 512 characters
# schema: Schema | None. In this scenario, IVF must be explicitly configured. For construction details, see Schema/Configuration API below.
# Return a collection instance
client.create_collection(name="tech_docs", use_namespace=True, schema=schema)
# Gets an existing collection. If the collection does not exist, an exception is thrown.
# name: str
client.get_collection("tech_docs")
# Returns the collection if it exists; creates the collection if it does not. The parameters are the same as those for create_collection.
# If the specified schema or namespace already exists, subsequent calls to this API will not modify the existing configuration.
client.get_or_create_collection(name="tech_docs", use_namespace=True, schema=schema)
# Delete a collection. The call will block until the deletion is complete before returning, with no return value.
client.delete_collection("tech_docs")
# List all collections; return list[Collection].
client.list_collections()
# Whether it exists. Returns a boolean value.
client.has_collection("tech_docs")
Collection APIs
# Creates a namespace. name: string, which can contain only letters, digits, and underscores, and must not exceed 256 characters in length. Returns the namespace instance.
# Must be called on a collection with use_namespace=True
collection.create_namespace("my_knowledge")
# Gets the namespace. If it does not exist, an exception is thrown.
collection.get_namespace("my_knowledge")
# Returns the value if it exists; creates it if it does not.
collection.get_or_create_namespace("my_knowledge")
# Delete namespace. The operation is asynchronous, returns immediately after the call, and data is deleted gradually in the background.
collection.delete_namespace("my_knowledge")
# List all namespaces; return list[Namespace].
collection.list_namespaces()
# Whether it exists. Returns a boolean value.
collection.has_namespace("my_knowledge")
# Attribute
collection.name # str, the name of the collection.
collection.id # str,Collection ID
collection.Dimension # int, the dimensionality of the vector.
collection.distance # str, the distance algorithm (e.g., cosine or l2).
collection.use_namespace # bool, whether to enable namespace mode.
collection.metadata # dict | None, metadata
collection.embedding_function # EmbeddingFunction | None, the current embedding function
In this scenario, data read and write operations are performed on namespaces. Collections themselves do not directly support DML/DQL.
Namespace APIs
# ---------- DML ----------
# INSERT; IDs must be unique within the namespace; duplicates will cause an error. Use upsert when repeatable execution is required.
# ids: str | list[str]
# embeddings: list[float] | list[list[float]] | None (One or more vectors. The dimensionality must match that of the collection.)
# metadatas: dict | list[dict] | None
# documents: str | list[str] | None
# At least one of embeddings, documents, or metadatas must be provided. If embeddings is not provided and only documents is provided, an embedding function must be configured.
# The lengths of the `documents`, `embeddings`, and `metadatas` fields must match the length of the `ids` field in a batch; up to 100 records per batch.
ns.add(ids=["doc1"], documents=["OceanBase AI Database"])
# Updates a specified field by id. Fields not provided are unchanged. If the id does not exist, no error is reported and no update is performed.
ns.update(ids=["doc1"], documents=["OceanBase AI Database (Updated)"])
# If the parameter exists, update it; if not, insert it. The parameter types are the same as those of add.
ns.upsert(ids=["doc1"], documents=["OceanBase AI Database"])
# Delete. You can delete by ID or filter conditions. At least one of ids, where, and where_document must be specified.
ns.delete(ids=["doc1", "doc2"])
ns.delete(where={"category": "database"})
# ---------- DQL ----------
# Vector Search -> dict (including ids, documents, metadatas, distances, etc.)
# query_embeddings: list[float] | list[list[float]] | None
# list[float] indicates a single query vector; list[list[float]] indicates multiple query vectors (batch query). Each vector is searched independently and returns a two-dimensional result. The results are not merged for hybrid search.
# query_texts: str | list[str] | None
# str: a single query text; list[str]: multiple query texts (for batch queries)
# Either query_embeddings or query_texts must be provided. An error is returned if neither parameter is specified.
# n_results: int, default 10
# where / where_document: dict | None
# include: list[str] | None (for example, ["documents", "metadatas", "distances"])
# Returns a two-dimensional dict, where the outer layer corresponds to each query.
ns.query(query_texts=["aaa"], n_results=10,
where=None, where_document=None, include=None)
ns.query(query_embeddings=[[0.12, 0.34, ...]], n_results=10,
where=None, where_document=None, include=None)
# Hybrid search (vector + full-text); query is for the full-text path, knn is for the vector path, rank is for the fusion; returns a two-dimensional dict
# query: dict | None
# where_document: dict | None (for example, {"$contains": "aaa"}).
# where: dict | None (filter by local metadata)
# n_results: int (Number of results retrieved locally. Default: 10.)
# knn: dict | None
# At least one of query_texts or query_embeddings is specified (semantically equivalent to ns.query).
# where / n_results (Filtering by local metadata and number of retrieved records)
# rank: dict | None, for example, {"rrf": {"rank_window_size": 60, "rank_constant": 60}}
# n_results: int, the number of records returned after fusion. Default value: 10.
# include: list[str] | None; always returned by distances
# query_hint: QueryHint | None. This parameter takes effect only for this API (parallel, query_timeout, and vector_index).
ns.hybrid_search(
query={
"where_document": {"$contains": "aaa"},
"where": {"category": {"$eq": "database"}},
"n_results": 6,
},
knn={
"query_texts": ["aaaaa"],
"n_results": 6,
},
rank={"rrf": {"rank_window_size": 60, "rank_constant": 60}},
n_results=3,
include=["documents", "metadatas"],
)
# Exact match (non-similarity search); returns a one-dimensional dict
# Supports pagination by using IDs or WHERE/WHERE_DOCUMENT; LIMIT/OFFSET
ns.get(ids=["doc1", "doc2"])
ns.get(where={"category": "database"}, limit=2, offset=0,
include=["documents", "metadatas"])
# ---------- Statistics and O&M ----------
# Number of records returned; return type: int
ns.count()
# Limit the number of records to preview. The returned value is a one-dimensional dict (same structure as that returned by the get method).
ns.peek(limit=10)
# Preheat the current namespace (available for remote shared storage deployment). No return value.
ns.prewarm()
# Attribute
ns.name # str, the name of the namespace.
ns.namespace_id # str,Namespace ID
ns.collection # Collection, the collection to which it belongs.
Schema/configuration APIs
from pyseekdb import (
Schema, VectorIndexConfig, IVFConfiguration,
FulltextIndexConfig,
)
# Schema: Overall configuration for Collection indexes
Schema(
# vector_index: VectorIndexConfig | None, the vector index.
vector_index=VectorIndexConfig(
# ivf: IVFConfiguration; the dimension must match the output of the embedding model, with values ranging from [1, 4096].
# distance: cosine / l2 / inner_product; In this scenario, the type only supports ivf_flat.
ivf=IVFConfiguration(dimension=384, distance="cosine", type="ivf_flat"),
# embedding_function: EmbeddingFunction | None, for automatic text vectorization
embedding_function=ef,
),
# fulltext_index: FulltextIndexConfig | None, specifies the full-text index.
# analyzer: str(ik / space / ngram / ngram2 / beng)
fulltext_index=FulltextIndexConfig(analyzer="ik"),
)
In this scenario, the IVF is used for vector indexing. The SparseVectorIndexConfig applies only to non-namespace collections and does not need to be configured in this scenario.
Embedding function APIs
from pyseekdb import EmbeddingFunction, register_embedding_function
# Register custom embedding functions for easy identification and reconstruction by name.
@register_embedding_function
class MyEF(EmbeddingFunction):
@staticmethod
def name() -> str: ...
# Embedding function identifier; returns str
def __call__(self, documents) -> list[list[float]]: ...
# Converts text into a vector; documents: str | list[str]; returns list[list[float]]
def get_config(self) -> dict: ...
# Configuration for writing collection metadata; returns dict
@staticmethod
def build_from_config(config) -> EmbeddingFunction: ...
# Restore an instance by metadata; config: dict; Return EmbeddingFunction
For binding methods, see Indexes and embedding functions.