Docs
Contents

Databases Overview

Feature Overview

The Agentbase structured database (Databases / TablesDB) is built on the OceanBase native distributed database engine, providing strongly consistent, highly available structured data management for enterprise AI agents and business systems. In project 企业智能客服与知识中台 (Project ID: enterprise-ai-hub-210), enterprises can create business databases (such as 企业智能客服业务库, Database ID: enterprise_biz_db) via the Console's Databases module or client/server SDKs (agentbase-web-sdk@2.10.0, agentbase-node-sdk@2.10.0), and under them define structured business tables (such as the customer support ticket table customer_tickets), strongly typed columns, high-performance secondary/unique/full-text indexes, and row records.

Leveraging OceanBase's multi-tenancy and massive table capacity, Agentbase provides two production-grade project storage modes at the underlying layer — Shared V2 (tableMode=shared) and JsonTable (tableMode=jsonTable) — and supports ProjectTableModeConversion to perform bidirectional online conversion between the two storage modes, complete with write-freeze protection windows, data integrity validation, and platform reference remapping. On top of this, the Databases service further integrates Schema multi-version control and rollback (Schema Versions), controlled SQL access surface (SQL Proxy), table-level and row-level security permissions (Row Security), server-side aggregate computation (COUNT / SUM), and cloud backup and restore (Backups), forming a one-stop data foundation for enterprise core production workloads.


Core Concepts and Architecture

Agentbase Databases adopts an architecture in which the "five-layer logical resource model (Project → Database → Table → Column & Index → Row)" maps to the underlying OceanBase storage pools. The diagram below shows the complete architecture from upper-layer SDK / Console access and permission evaluation to OceanBase's dual storage modes (Shared V2 and JsonTable) and mode conversion:

Databases Overview: workflow diagram, not a runtime screenshot

Flow diagram, not a runtime screenshot; read the relationships between steps or states along the arrows.

View the flow diagram in full size

1. Five-layer logical resource hierarchy explanation

Hierarchy objectExample (enterprise-ai-hub-210)Key attributes and architecture notes
Databaseenterprise_biz_db (企业智能客服业务库)A namespace for logical tables and a unit for backup/Schema version control. Multiple Databases can be created under a single project; client accessibility can be controlled via the enabled switch.
Tablecustomer_tickets (customer support ticket table)A collection of similarly structured row records. Supports business comments of up to 256 characters (comment), table-level read/write permissions, and row-level security switches (rowSecurity).
Column (column / field)title, status, priority, creatorUserIdDefines each column's data type (such as varchar, text, integer, float, boolean, datetime, enum, relationship), required constraint (required), default value (default), array flag (array), and column comments of up to 256 characters (comment).
Indexidx_status_priority, ft_titleA data structure that accelerates query filtering, sorting, and uniqueness constraints. Supports regular indexes (key), unique indexes (unique), full-text indexes (fulltext), and spatial indexes (spatial).
RowTK-20261022-001 .. TK-20261022-004Concrete business data records. In addition to user-defined business columns, the system automatically maintains the $id, $sequence, $createdAt, $updatedAt, $permissions, $databaseId, $tableId system metadata columns.

2. In-depth comparison of OceanBase storage modes: Shared V2 vs JsonTable

For projects of different scales and business characteristics, Agentbase provides two core storage modes on OceanBase storage pools — Shared V2 (tableMode=shared) and JsonTable (tableMode=jsonTable) (the legacy collection separate-table and Shared V1 modes are retained only for compatibility and are not intended for new projects):

Comparison dimensionShared V2 mode (tableMode=shared)JsonTable mode (tableMode=jsonTable)Selection and architecture impact
Physical storage structureSystem tables are shared across tenants; user business tables map each field to a real typed physical column in OceanBase ****, with multi-tenant row-level isolation implemented via the _tenant column.All logical tables of all projects are consolidated into a fixed set of 7 _jt_* physical tables (_jt_documents, _jt_permissions, _jt_index_values, _jt_unique_index_values, _jt_fulltext_index_values, _jt_table_catalog, _jt_table_sequences), with user fields stored in a _data JSON column, isolated by project_seq + catalog_id.High-concurrency core business & full AI suite: prefer Shared V2 (e.g., enterprise-ai-hub-210); choose JsonTable for ultra-large-scale long-tail projects / high-frequency dynamic table creation when physical table count needs to be flattened.
Table creation and column-addition DDL costExecutes real OceanBase physical CREATE TABLE / ALTER TABLE DDL, asynchronously materialized by a background database Worker.Catalog-only pure metadata writes (only updates _jt_table_catalog), with zero physical DDL; table creation, column addition, and index creation complete instantly without locking large physical tables.JsonTable Completely eliminates the OceanBase Schema memory and DDL blocking overhead caused by the proliferation of massive logical tables.
Index implementation mechanismDirectly uses OceanBase native secondary indexes, UNIQUE indexes, native FULLTEXT full-text indexes, and SPATIAL spatial indexes; queries and ORDER BY are pushed down directly to the storage layer.Regular indexes are accelerated via _jt_index_values typed side tables INNER JOIN; unique indexes use _jt_unique_index_values side tables with SHA-256 composite unique constraint strong validation; side tables are maintained synchronously with every write operation (with some write amplification).Shared V2 Native indexes deliver the best performance; JsonTable guarantees equality/range/unique index semantics, but ORDER BY performs in-scope JSON_EXTRACT sorting.
Full-text search and complex operatorsNative MATCH ... AGAINST full-text search; native support for array multi-value indexes (MVI) and spatial geometry operators.Operators such as search / notSearch, array contains*, and regex first narrow the candidate set via SQL, then perform exact filtering in memory on the candidate set (default limit 1 MB); does not support Spatial spatial types and spatial operators.If your business heavily relies on full-text search over massive data, complex aggregation on large tables, or spatial location queries, you must choose Shared V2.
AI module compatibilityFull support for Databases, Storage, Knowledge Base, Memory (long-term memory), PowerContext and AI Gateway.Supports common project resources such as Databases, Storage, Knowledge Base, Lexicons, and Scenarios; but Memory, PowerContext, and AI Gateway currently require the project to run in Shared V2 mode.Projects that enable agent memory or the AI Gateway must use, or first convert to, Shared V2 mode.

3. Bidirectional online conversion of project storage modes (ProjectTableModeConversion)

When a project's business form evolves (for example, migrating from a lightweight prototype stage to a production stage with Memory and high-frequency retrieval enabled, or consolidating from Shared V2 archives to JsonTable), Agentbase supports bidirectional lossless conversion of the project-level storage mode via ProjectTableModeConversion (Shared V2 ↔ JsonTable):

  1. Probe available target pools: Call GET /v1/project/table-mode-conversions/targets (or use the Console table mode conversion page) to query the current project's source pool (sourcePool / sourceTableMode) as well as the convertible target mode (targetModes[]) and available storage pool labels (tags[]).

  2. Initiate the conversion task and the stop-write protection window (Stop-Write Window): After the conversion task is submitted, the project enters a controlled stop-write window (tableModeConversionStatus set), blocking new concurrent writes to structures or data during conversion, ensuring strict data consistency between source and target.

  3. Full backfill, remapping, and consistency verification (Backfill & Verify): ProjectTableModeConversion Workers automatically backfill all metadata collections under the project, dynamic business tables (Tables / Columns / Indexes / Rows), row-level permissions, knowledge base and lexicon associations, and internal sequence numbers ($sequence / resourceInternalId) as well as platform-side project references, completely into the target storage pool, and perform item-by-item verification of row counts and key fields.

  4. Traffic cutover, cache clearing, and delayed deletion of source data: After validation passes, atomically switch the project database routing pointer and refresh the Swoole Table dynamic pool cache and Redis cache, restoring normal business reads and writes; the old data in the source storage pool is retained in a pending-cleanup state, and after confirming the business is stable you can click Delete source project data immediately (irreversible; once deleted, the conversion cannot be rolled back).


Roles, Entry Points, and Relationships

Console Entry and Routes

Role and permission control model

Databases adopts a dual-layer authentication mechanism: "Console management permissions (organization roles / API Key Scopes)" and "end-user data access permissions (table-level / row-level ACL)":

Permission levelScope of controlAuthorized principals and configuration entryEffective rule description
Control plane permissions (Control Plane)Creating/deleting databases, creating tables/columns/indexes, submitting Schema versions, managing backup policiesOrganization roles owner, admin, developer, editor; or a Server API Key carrying databases.read / databases.write, tables.read / tables.writebilling The analyst organization role has read-only permissions in the Console and cannot create or modify database and table structures.
Table-level data permissions (Table Permissions)End users' create, read, update, delete permissions on all rows of the tableAdd roles such as Role.any(), Role.users(), Role.team('team_support_ops') in the table's Settings → PermissionsAs long as an end user matches the table-level read (or update/delete) permission, they can read (or modify/delete) all rows in the table.
Row-level security permissions (Row Security)Isolated access at single-row record granularity (e.g., customer Zhang Wei can only see his own support tickets)Turn on the switch in the table's Settings → Row security and configure the row's $permissions when creating/editing rowsAfter enabling Row security, a user who does not match table-level permissions but matches the Permission.read(Role.user('user_zhangwei_001')) on a single row can only read or operate on that specific row.

Feature Details and Operation Guide

1. Browsing and searching the database list

After entering the project's Databases page, all databases under the current project are displayed by default in a table view (e.g., enterprise_biz_db enterprise intelligent customer service business database):

Database list page (reusing registered screenshot)

Interface reference: reuses previously registered historical screenshots; demo data may differ from the current project; no new screenshots were taken this time.

2. Steps to create a database (Create database)

  1. On the Databases list page, click the Create database button in the upper right corner (or press the shortcut key c). If the current project's database count has reached the quota limit of the associated plan, the button will be disabled and display a plan upgrade prompt.

  2. Fill in the following parameters in the pop-up creation window:

Field nameRequiredValidation rules and example values (enterprise-ai-hub-210)
NameRequiredThe database's display name, up to 128 characters. Example: 企业智能客服业务库
Database IDOptionalClick the Database ID label to expand the custom input box. Only a-z, A-Z, 0-9, periods (.), hyphens (-), and underscores (_) are allowed, up to 36 characters, and the first character cannot be a special symbol; if left blank, the system automatically generates a unique ID. Example: enterprise_biz_db
Backup policy (visible with cloud plans)OptionalThe create database dialog embeds a backup policy selector, allowing you to enable a preset daily/hourly backup policy or a custom backup policy while creating the database; if the current plan does not include backup benefits, an upgrade prompt is shown.
  1. Click the Create button to submit. A notification "企业智能客服业务库 has been created" pops up in the upper right corner, and the page automatically redirects to the /databases/database-enterprise_biz_db table list page.

3. Database enable/disable (enabled) and settings management

In the database detail page's Settings tab (or by calling databases.update(databaseId, name, enabled) via the Server SDK), administrators can maintain the database's basic properties:

4. Deleting a database (Delete database) and the asynchronous cascading cleanup mechanism

When a test database is no longer needed, you can delete it via the following safety confirmation process:

  1. Go to the target database's Settings tab, scroll to the bottom Danger zone, and click Delete database to open the deletion confirmation dialog.

  2. Review the list of affected tables: The dialog clearly lists the business table names under the database that will be destroyed along with it (showing at most the first 25 tables), and warns that all backup snapshots associated with the database will also be permanently destroyed simultaneously and cannot be recovered.

  3. Check the strong confirmation checkbox: You must manually check the "I understand and confirm" checkbox before the red Delete button in the lower right corner becomes enabled.

  4. Understand the asynchronous cascading deletion behavior: After clicking confirm deletion, the server accepts the request and returns success, then hands it off to a background asynchronous deletion task (Worker) that cleans up all row records, indexes, and column metadata table by table, and finally removes the database's main document and associated backups. For databases containing massive rows, the list page may briefly retain the database record during asynchronous cleanup until the background cascading cleanup is fully complete.


FAQ and Troubleshooting

Q1: When creating a new project or planning the business architecture, how should you decide whether the project should use the Shared V2 or JsonTable storage mode?

Decision guide:

  1. Scenarios where Shared V2 (tableMode=shared) is preferred:

    • The project needs to use agent long-term memory (Memory), PowerContext, or the AI Gateway (e.g., demo project enterprise-ai-hub-210).

    • Business tables have large single-table data volumes and heavily rely on OceanBase native secondary index sorting, native FULLTEXT full-text search relevance ranking, array multi-value indexes (MVI), or Point / Line / Polygon spatial location queries.

  2. Scenarios for choosing JsonTable (tableMode=jsonTable):

    • The tenant needs to dynamically and frequently create hundreds or thousands of logical tables, and wants table creation, column addition, and index changes to have zero physical DDL (Catalog-only) second-level response, while keeping the underlying OceanBase physical table count consistently converged within 7 _jt_* shared tables.

    • If later business growth requires native column indexes or enabling Memory, you can convert online losslessly from ProjectTableModeConversion to Shared V2 at any time.

Q2: Why does a client query on the customer_tickets table under enterprise_biz_db return success but with an empty documents / rows array (total: 0), while the Console clearly shows 4 support ticket records?

Root cause analysis: The Agentbase database follows the Default Deny zero-trust security principle by default. The Console admin view uses organization management permissions to read full table data directly, while client SDK requests are strictly filtered by the table's Permissions (table-level permissions) and Row security (row-level security): if neither the Read permission has been granted to the current user role in the table's Settings → Permissions, nor Row security has been enabled with that user granted the Read permission on individual rows, the query will not throw an error but will automatically filter out all rows the user has no access to and return an empty list.

Troubleshooting steps:

Q3: After executing a database deletion (or deleting a large table), why does the database still briefly appear for a few seconds when I refresh the page?

Root cause analysis: To prevent gateway timeouts or long-transaction table locks from synchronous HTTP requests when deleting a database or large table containing millions of rows, both database deletion and table deletion in Agentbase adopt an asynchronous cascading cleanup architecture. The HTTP endpoint returns immediately after registering the deletion intent and locking the resource; a background database Worker then safely deletes the underlying row data, side-table indexes, and backup files in bounded batches, and the top-level database metadata record is removed only after all cleanup is complete. Simply wait a few seconds and refresh again.