This topic provides an overview of logical tables, including the problems they solve, the basic concepts, and the differences between the two implementation scenarios.
A logical table is a data organization method provided by OceanBase AI Database. Multiple isolated data spaces can share the same set of underlying physical tables, distinguished by namespaces, eliminating the need to create separate tables for each space.
Background
In conventional usage, a business table typically corresponds to a physical table in the database. When a large number of independent data spaces are required (for example, by user, Agent, session, or application), creating a separate physical table for each space can lead to the following issues:
Issue |
Note |
|---|---|
| Increased metadata burden | As the number of physical tables increases with the growth of the isolated spaces, metadata management costs rise, impacting related operations and query overhead. |
| Frequent DDL changes | In scenarios with dynamic table schemas or a large number of small applications, frequent table creation and modification can increase the risk of changes and operational complexity. |
| Hard to reuse storage | Different isolated spaces could have shared the same physical storage and index configuration, but are split into different physical tables. |
The logical table approach keeps data on shared physical tables, with isolation between spaces achieved through namespaces, thereby reducing the number of physical tables and DDL pressure.
Object model
When using logical tables, the object hierarchy is as follows. The business data stored under Namespace differs by scenario, but the upper-level isolation relationship is the same:
Client
└── Collection
└── Namespace
└── Business Data
Object |
Note |
|---|---|
| Client | The SDK connection entry point, used to connect to the database and manage collections. |
| Collection | The top-level container that corresponds to a set of shared physical tables and related configurations (such as partitions and indexes). A collection can contain a large number of namespaces. |
| Namespace | The basic unit of data isolation. Data in different namespaces is invisible to each other, and read and write operations are performed within the respective namespace. In flash applications, a namespace corresponds to an app. |
| Business Data | The actual content stored in a namespace. In the Agent hybrid search scenario, it consists of fixed-structured search records; in the flash application scenario, it consists of virtual tables and their row data. |
The related SDK must enable namespace mode before logical tables can be used (for example, by setting use_namespace=True). Specific parameters and calling methods are described in the documentation for each scenario.
Implementation scenarios
Logical table is a lower-level capability. It can be used in the following two scenarios based on interfaces and data models. In this two scenrios, the same isolation method is used, but the data models and SDKs used are different.
Comparison item |
Agent hybrid search scenario |
Flash application scenario |
|---|---|---|
| Application scenarios | Agent memory, knowledge base, and multi-user space search | Dynamic table structures, SQL read/write for multi-application virtual tables |
| SDK | pyseekdb | json-table-sdk |
| How do developers read and write? | Call the write and query APIs of the SDK; no need to create tables | First use CREATE TABLE to define columns, and then use SQL statements such as INSERT / SELECT. |
| What is stored in a namespace? | Multiple search records. For example, several conversation memories of an Agent, each containing an ID, text, vector, and metadata. | User-defined tables and rows. For example, a small application can have orders, users, and other tables (stored as JSON in the database but used as regular tables on the client side). |
| Core capabilities | Vector search, full-text search, and hybrid search | Creation and alteration of virtual tables, SQL read and write operations, structured queries based on JSON, and query acceleration using search indexes |
Details such as field meanings, indexes, limitations, and operation examples are provided in the documentation for each scenario.