Note
This feature is an experimental feature in the current version.
This topic guides you through the entire process from connection to search using a complete example. In this example, we create a "technical documentation" knowledge base, insert several documents, and perform vector search and exact query.
Prerequisites
- OceanBase AI Database has been deployed. For information about how to deploy OceanBase AI Database, see Choose an appropriate deployment plan.
- The pyseekdb SDK has been installed. For information about how to install the pyseekdb SDK, see Deployment overview.
- A pyseekdb SDK connection has been created. For information about how to connect, see Connect to OceanBase AI Database by using SDK.
Create a collection
# Import the pyseekdb module
from pyseekdb import Schema, VectorIndexConfig, IVFConfiguration, FulltextIndexConfig
# Create a collection with IVF vector indexes and full-text indexes
collection = client.create_collection(
# Collection Name
name="tech_docs",
# Set schema
schema=Schema(
vector_index=VectorIndexConfig(
ivf=IVFConfiguration(dimension=384, distance="cosine", centroids_fresh_mode="spfresh"),
),
fulltext_index=FulltextIndexConfig(analyzer="ik"),
),
# Whether to Use Namespace
use_namespace=True,
)
This example uses use_namespace=True. To customize index parameters, see Indexes and embedding functions.
Create a namespace
# When you create a namespace, the system automatically assigns a namespace ID.
ns = collection.create_namespace("my_knowledge")
print(f"namespace_id: {ns.namespace_id}")
Write data
# Write documents in batches (This example only passes text; the SDK automatically generates vectors.)
ns.add(
# Business ID, used to associate business data
ids=["doc1", "doc2", "doc3"],
# Document text
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.",
],
# Metadata, used to associate business data
metadatas=[
{"category": "database", "version": "4.0"},
{"category": "ai", "version": "4.6"},
{"category": "sdk", "version": "1.2"},
],
)
In the first example of this section, the embeddings parameter is not passed. In this case, the SDK automatically vectorizes the text in the documents parameter. If you do not want to use automatic vectorization, pass the embeddings parameter to specify the vectors. For example:
ns.add(
ids=["doc1"],
documents=["OceanBase AI Database is a distributed database independently developed by Ant Group, supporting HTAP mixed workloads"],
# Vector, used for search
embeddings=[[0.12, 0.34, ...]], # 384-dimensional vector
)
Query data
In the examples of this section, three pieces of data have been written. The following are examples of querying data, including vector search, exact query, and statistics.
Vector search
# Perform vector search using natural language, return the two most similar results, and print them.
results = ns.query(
query_texts=["Distributed Database"],
n_results=2,
include=["documents", "metadatas", "distances"],
)
for i, id_ in enumerate(results["ids"][0]):
print(f"id: {id_}")
print(f" document: {results['documents'][0][i]}")
print(f" distance: {results['distances'][0][i]:.4f}")
Output example:
id: doc1
document: OceanBase AI Database is a distributed database independently developed by Ant Group, supporting HTAP mixed workload.
distance: 0.2310
id: doc3
document: pyseekdb is the Python SDK for OceanBase AI Database, providing vector storage and hybrid search capabilities.
distance: 0.4512
query_texts automatically calls the embedding function to convert text into vectors. For more information, see Search data.
Exact search
# Perform an exact query by business ID, return the first record, and print the result.
result = ns.get(ids=["doc1"])
print(result["documents"][0])
Statistics
print(ns.count())
# Output: 3
Pre-warming
In production environments, a Namespace that has not been accessed for a long time will become "cold" (its index cache will be evicted), which leads to higher latency on the next query. After writing data, you can call the prewarm API to actively load the cache:
ns.prewarm()
In this example, the data volume is extremely small and has just been written, so the pre-warming effect is not significant. However, for large-scale data scenarios, it is recommended to perform pre-warming immediately after writing. For more information, see Collection and namespace management.
Clean up resources
# Delete namespace and collection
collection.delete_namespace("my_knowledge")
client.delete_collection("tech_docs")
delete_namespace is an asynchronous operation. It returns immediately upon invocation, while the data is gradually cleaned up by background tasks. delete_collection is a synchronous operation. The deletion is completed and returned immediately upon invocation, without waiting for background asynchronous tasks. You can view the deletion progress through the DBA_OB_AGENT_DB_BACKGROUND_TASKS view. For more information, see Monitoring and maintenance.