Note
This feature is an experimental feature in the current version.
This topic describes the write interfaces in the Agent hybrid search scenario. The data model consists of four fields: id, document, embedding, and metadata. For more information, see Agent hybrid search scenario overview.
Note
The example in this topic builds on Quick start with the Agent hybrid search scenario: assume that you have created a Collection named tech_docs and a Namespace named my_knowledge, and you are operating on this Namespace (using the variable ns). The sample data is consistent with that in the quick start example.
Insert (add)
# Single
ns.add(
ids="doc1",
documents="OceanBase AI Database is a distributed database independently developed by Ant Group. It supports HTAP mixed workloads.",
metadatas={"category": "database", "version": "4.0"},
)
# Batch (recommended)
ns.add(
ids=["doc1", "doc2", "doc3"],
documents=[
"OceanBase AI Database is a distributed database independently developed by Ant Group, supporting HTAP mixed workloads.",
"Agent Hybrid Search is a multi-tenant vector search solution for AI Agents in OceanBase AI Database.",
"pyseekdb is the Python SDK for OceanBase AI Database, providing vector storage and hybrid search capabilities.",
],
metadatas=[
{"category": "database", "version": "4.0"},
{"category": "ai", "version": "4.6"},
{"category": "sdk", "version": "1.2"},
],
)
If a vector already exists, passing embeddings skips automatic vectorization:
ns.add(
ids=["doc1"],
documents=["OceanBase AI Database is a distributed database independently developed by Ant Group, supporting HTAP mixed workload"],
embeddings=[[0.12, 0.34, ...]], # 384-dimensional
)
Constraints and recommendations are as follows:
addrequiresidto be unique within the Namespace. Passing a duplicateidmay cause insertion failure; for scenarios requiring repeated execution, useupsert.- Write parameter names are plural:
documents/embeddings/metadatas. - For batch writing, the length of each parameter must match that of
ids. For example, ifidsis["doc1", "doc2", "doc3"], thendocuments,embeddings, andmetadatasmust all be 3 elements long. - In Namespace mode, a single batch can contain at most 100 records; for larger data volumes, write in batches in a loop.
The embedding rules are as follows:
- When explicitly passing a dense
embeddingsvector, the SDK uses this vector directly without calling the Embedding Function. - If
embeddingsis not passed butdocumentsis, the Collection's embedding function must be configured; otherwise, an error will be reported. - Passing only
metadatasas a placeholder is allowed. In this case,documentandembeddingare empty. addrequires at least one ofembeddings,documents, ormetadatas.
Update (update)
# Update Metadata and Document by ID
ns.update(
ids="doc1",
documents="OceanBase AI Database is a distributed database independently developed by Ant Group. It supports HTAP mixed workloads (updated)",
metadatas={"category": "database", "version": "4.7"},
)
update does not check the number of rows affected. Passing an non-existent id does not throw an error or perform an update. To confirm the update result, you must call get or count to verify. Fields that do not require updating can be omitted.
Notice
The SDK does not verify whether the input vectors are semantically consistent with the embedded model. You must ensure that the vector space is consistent within the same Collection.
Insert or update (upsert)
upsert performs an insert or update operation based on the id: updates if the document exists, and inserts if it does not. It is more fault-tolerant than add and is suitable for write scenarios that require repeated execution.
ns.upsert(
ids=["doc1", "doc4"],
documents=[
"OceanBase AI Database is a distributed database independently developed by Ant Group, supporting HTAP hybrid workloads.",
"Add a new SDK usage note."
],
metadatas=[
{"category": "database", "version": "4.0", "status": "updated"},
{"category": "sdk", "version": "1.3", "status": "new"},
],
)
The vector semantics for update and upsert are the same as for add:
- If
embeddingsare explicitly provided, those vectors are used first, and the embedding function is not called. - If only
documentsare provided, vectors are automatically generated using the embedding function configured for the Collection. - Updating only
metadatasdoes not trigger a vector recalculation.
Delete
delete requires at least one of ids, where, or where_document.
# Delete by ID
ns.delete(ids=["doc1", "doc2"])
# Delete by Condition
ns.delete(where={"status": "obsolete"})
# Delete by Document Content
ns.delete(where_document={"$contains": "Obsolete content"})