Note
This feature is an experimental capability in the current version.
The Agent hybrid search scenario address the needs for memory, knowledge base, and multi-user space search in AI Agent applications. Typically, each user, Agent, or session requires an independent data isolation domain, which can scale to massive volumes. Creating a separate physical table for each isolated domain would lead to linearly proportional metadata and resource overhead.
This scenario is based on the logical table capability of OceanBase AI Database. By using the pyseekdb SDK (use_namespace=True), data from multiple Namespaces shares the underlying storage while being logically isolated. What developers see are independent Namespaces, without needing to create a separate physical table for each isolation domain, and they can perform vector search, full-text search, and hybrid search on the same object model. Through the Namespace-based user interface provided by the pyseekdb SDK, data from multiple Namespaces can share the underlying storage while remaining logically isolated.
Core object model
Client
└── Collection
└── Namespace
└── Record
Object |
Note |
|---|---|
| Client | The entry point for connecting to OceanBase AI Database, used to manage the creation and retrieval of collections. |
| Collection | The top-level container that determines schema configurations such as vector dimensionality, index type, and tokenizer. A collection can accommodate a vast number of namespaces. The collection itself does not directly carry data operations. |
| Namespace | The basic unit of data isolation. Each namespace has its own namespace_id, and data is isolated by namespace at the storage layer. All DML and DQL operations are performed on namespaces. |
| Record | A logical concept representing a data record, consisting of a four-tuple as detailed in the following table. |
The Record four-tuple is as follows:
Field |
Type |
Note |
|---|---|---|
| id | string | Business primary key, which is unique within the namespace. |
| document | string | Text content, used for full-text search and automatic vectorization |
| embedding | list[float] | Dense vectors, used for vector similarity search |
| metadata | dictionary | Structured metadata (JSON) used for conditional filtering |
Core capabilities
Capabilities |
Note |
|---|---|
| Large-scale user space isolation | A single collection can contain an massive number of namespaces, each with its own independent data space. |
| Vector search | High-performance approximate nearest neighbor search based on IVF indexes, supporting L2, cosine, and inner_product distances. |
| Full-text search | Supports full-text indexes with multiple tokenizers, including IK, Space, Ngram, Ngram2, and Beng. |
| Hybrid search | Vector + full-text multi-retrieval path, RRF fusion sorting. |
| Online index maintenance | The SPFresh mechanism prevents the recall rate from degrading after writing to an IVF index. |
| Automatic embedding | After configuring the embedding function, writing text automatically generates dense vectors. |
Working modes of pyseekdb SDK
pyseekdb supports two working modes, which are switched by the use_namespace parameter in create_collection:
Comparison item |
use_namespace=False (default) |
use_namespace=True |
|---|---|---|
| Application scenarios | Single-user space, small-scale data | Multi-user space, large-scale data isolation |
| Data isolation | No namespace; data is operated on directly at the collection level. | Through namespace isolation, data in different namespaces is mutually invisible. |
| Pre-warm | Not supported | Remote shared storage deployment supports the namespace.prewarm() API |
| Hot/cold separation | Not supported | Remote shared storage deployment supports hot namespace auto-expiration |
| Data operation entry | collection.add() / collection.query() |
namespace.add() / namespace.query() |
Additional notes are as follows:
- In this scenario,
use_namespace=Trueis used. If there is only one dataset and multi-user space isolation is not required, the default mode (use_namespace=False) can be used. - The current SDK does not support weak consistency reads; in Namespace mode, reads and writes follow the database's default strong-consistency path.
Application scenarios
Implementation method |
Note |
Recommended namespace granularity |
|---|---|---|
| Agent Memory | Dialogue memory storage and semantic search: Store historical messages, context, and memories | One namespace per Agent instance |
| RAG knowledge base | Hybrid search of vector and full-text after document segmentation | One namespace per knowledge base |
| Codebase search | Semantic search for code snippets (such as Cursor Codebase) | One namespace per code repository |
| Multi-user space SaaS | Strict data isolation between user spaces, access throttling, and shared underlying physical storage | One namespace per user space |
For capability comparison and selection with flash application scenarios, see Logical table overview.