表、列、行与索引
功能概述
表(Tables)、列(Columns)、索引(Indexes)与行(Rows)构成了 Agentbase 结构化数据库(Databases / TablesDB)的核心数据操作界面。在项目 企业智能客服与知识中台(Project ID:enterprise-ai-hub-210)的业务数据库 企业智能客服业务库(Database ID:enterprise_biz_db)中,研发与运营人员不仅可以通过 Console 直观的电子表格视图(Spreadsheet View)实时管理客户工单表(customer_tickets)的字段定义、二级与全文索引、行记录增删改查、单行级安全权限(Row Security)及 CSV 导入导出,还可以通过客户端与服务端 SDK(agentbase-web-sdk@2.10.0、agentbase-node-sdk@2.10.0)利用丰富的查询算子(如 Query.equal、Query.search、Query.orderDesc、Query.cursorAfter)与批量事务接口高效处理复杂业务。
Agentbase 的表结构引擎支持超过 15 种精细化列类型(涵盖短文本 varchar、长文本 text/mediumtext/longtext、数值 integer/float、布尔 boolean、日期时间 datetime、格式校验型 email/ip/url、枚举 enum、跨表关联 relationship 及空间几何类型 point/line/polygon),并为表和列提供最高 256 字符的业务注释(Comments),让智能体(Agent)在自动生成 SQL 或理解业务表语义时具备准确的上下文依据。
核心概念与架构
在 Agentbase 中,对表结构(Columns / Indexes)的变更由后台异步 DDL 状态机安全驱动,而对行数据(Rows)的读写则经过权限裁剪、字段类型/必填约束校验与索引同步更新后落盘至 OceanBase。下图展示了 customer_tickets 表从结构定义、异步状态流转到行级 CRUD 与查询检索的完整架构:
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
实战示例:customer_tickets(客户工单表)真實行数据全景
在 SIT 演示环境项目 enterprise-ai-hub-210 的 enterprise_biz_db 数据库中,customer_tickets 表承载了企业客户提交的真实技术支持工单:
下表列出了 customer_tickets 表中预置的 4 条典型企业客户工单记录及其业务上下文:
行 $id(工单编号) | 工单标题(title) | 优先级(priority) | 状态(status) | 提单客户(creatorUserId) | 负责团队与处理专家 |
|---|---|---|---|---|---|
TK-20261022-001 | OceanBase 向量索引在高并发混合检索下的 HNSW 参数调优咨询 | P0 | processing | user_zhangwei_001(张伟) | team_support_ops / user_lina_002(李娜) |
TK-20261022-002 | AI 网关 prod-enterprise-ai-gateway 语义缓存命中率与回退模型切换验证 | P1 | resolved | user_zhangwei_001(张伟) | team_ai_platform / user_lina_002(李娜) |
TK-20261022-003 | 知识库 kb_enterprise_support 同义词词典与 GraphRAG 实体抽取联调 | P1 | open | user_zhangwei_001(张伟) | team_kb_governance |
TK-20261022-004 | Shared V2 模式下智能体长期记忆蒸馏(Context Dreaming)触发策略确认 | P2 | resolved | user_lina_002(李娜) | team_ai_platform |
角色、入口与关联关系
控制台入口与路由
导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 点击左侧栏 Databases → 点击进入数据库企业智能客服业务库(enterprise_biz_db)→ 点击表customer_tickets。路由地址:
/console/project-{region}-{project}/databases/database-{databaseId}/table-{tableId}表内二级页签结构:
Rows(默认电子表格页):可视化浏览、筛选、排序、内联编辑单元格、创建行、配置单行权限、生成示例数据与 CSV 导入。
Columns:查看与创建强类型列、配置必填/默认值/数组/加密属性及编辑最高 256 字符的列注释。
Indexes:创建与管理
Key(普通索引)、Unique(唯一索引)、Fulltext(全文索引)及Spatial(空间索引)。Activity:查看表与行记录的操作审计流水。
Usage:查看该表近期的行读写趋势指标。
Export:按自定义列与分隔符将表数据导出为 CSV 文件。
Settings:配置表启用状态(Status)、显示名称(Name)、表注释(Table comment)、表级权限与行级安全(Permissions & Row security)以及删除表(Danger zone)。
权限与关联关系
结构管理权限:创建/删除表、创建/修改/删除列与索引需要组织角色具备
databases.write/tables.write权限(owner、admin、developer、editor)。与 Schema 版本控制互斥保护:若当前数据库已启用并存在处于
active状态的 Schema 版本,在独立接口直接修改表/列/索引结构会受版本锁保护(返回409),建议统一通过提交新 Schema 版本或带完整列定义的updateTable推进结构变更;但修改列注释(updateColumnComment)属于零 DDL 元数据操作,即使在 active 版本下也可直接执行。与智能体工作台及 SQL Proxy 联动:表注释(
Table comment)与列注释(Column comment)不仅在 Console 表头展示,还会同步暴露给 SQL 访问面(SQL Proxy) 与智能体工具调用,辅助大模型精准理解业务字段含义。
功能详解与操作指南
1. 创建数据表(Create table)
进入数据库
enterprise_biz_db的 Tables 页签,点击右上角 Create table 按钮。在弹窗中填写表定义信息:
Name(必填):表的业务显示名称,例如
客户工单表或customer_tickets。Table comment(可选,推荐填写):表的业务说明或别名,最长 256 字符(例如:
存储企业客户提交的技术支持工单、SLA 等级与处理状态)。该注释仅用于增强可读性与 AI 语义理解,不改变Table ID与Name。Table ID(可选):点击展开自定义输入框,系统会根据表名自动生成小写加下划线的建议值;仅允许
a-z、A-Z、0-9、.、-、_,首字符必须为字母或数字,最长 36 字符(例如customer_tickets)。
点击 Create 完成建表。在云端实例上,新表创建后顶部还会贴心提供 AI 列建议(AI column suggestions) 入口,可根据表名一键生成推荐业务列(也可直接忽略并手动建列)。
2. 列类型全集与创建列(Create column)
切换到表的 Columns 页签点击 Create column(或直接在 Rows 电子表格视图中点击任意列头右侧菜单选择 Insert column left / right),即可创建新列。
每个列均包含三个基础标识属性:
Key(必填):列的 API 字段名,必须匹配正则
^[A-Za-z0-9][A-Za-z0-9._\-]*$(如ticketNo、title、priority)。应用代码与查询条件直接依赖该Key,创建后请保持命名稳定。Type(必填):列的数据类型(详见下表)。
Comment(可选):列业务注释,最长 256 字符(如
工单紧急程度:P0特急 / P1高 / P2普通),支持随时在零 DDL 下独立更新。
列数据类型(Column Types)与约束参数详表
| 类别 | 列类型(Type) | 底层存储与容量规格 | 专属可配属性与使用边界 |
|---|---|---|---|
| 字符串与文本类 | Varchar | 变长字符串,需指定最大字符数 Size(上限 16,383) | 适合工单号、标题、User ID 等有明确长度上限且需高频建索引的字段。支持 Required、Array、Default、Encrypt。 |
| 字符串与文本类 | Text(默认) / Mediumtext / Longtext | 分别对应最大约 64 KB / 16 MB / 4 GB 文本内容 | 适合工单详细描述、Markdown 正文、JSON 报文。支持开启 Encrypt(服务端加密存储)——注意:开启 Encrypt 的加密列无法用于查询过滤(Query)或建立索引。 |
| 字符串与文本类 | Email / IP / URL | 带内置格式校验器的专用字符串类型 | 写入时服务端自动校验合法电子邮箱、IPv4/IPv6 地址或标准 URL 格式;支持建立普通或唯一索引。 |
| 字符串与文本类 | String(已弃用) | 历史兼容字符串类型 | 控制台标记为已弃用(Deprecated),新建列请统一选用 Varchar 或 Text。 |
| 数值与布尔类 | Integer | 64 位有符号整数(或大整数) | 支持设置最小值(Min)、最大值(Max)、必填(Required)、默认值(Default)及数组(Array)。可用于 slaHours、计数与原子自增/自减。 |
| 数值与布尔类 | Float | 双精度浮点数(Double / Decimal) | 支持设置 Min、Max、Required、Default、Array。适合 satisfactionScore(满意度评分)、金额比率等指标。 |
| 数值与布尔类 | Boolean | 布尔值(true / false) | 支持 Required、Default、Array。适合 isEscalated(是否升级处理)等状态位。 |
| 时间与枚举类 | Datetime | ISO-8601 标准日期时间(精确到毫秒,UTC 存储) | 支持 Required、Default、Array 及范围比较查询(greaterThan、between)。 |
| 时间与枚举类 | Enum | 枚举值集合(Elements 列表) | 写入值必须严格落在预设的 Elements 枚举项中(如 ["open", "processing", "resolved", "closed"]),有效防止脏数据入库。 |
| 跨表关联类 | Relationship | 跨表关系列(支持 One-to-One、One-to-Many、Many-to-One、Many-to-Many) | 需实例开启关系支持。可配置单向或双向关联(Two-way)、关联目标表及级联删除策略(Restrict 阻止删除、Cascade 级联删除、Set null 置空)。注意:Relationship 列不能直接加入索引 Fields。 |
| 空间几何类 | Point / Line / Polygon | 经纬度坐标点、折线与多边形空间几何对象 | 仅在 Shared V2(或 collection)且实例开启空间支持时可用;JsonTable 模式不支持空间列与空间算子。 |
连续建列技巧:在 Create column 弹窗底部勾选连续创建模式,可在保存当前列后保持弹窗不关闭,快速连续录入整张表的所有字段。
3. 索引类型与创建索引(Create index)
为高频过滤(WHERE)与排序(ORDER BY)字段建立合理的索引,是保障生产环境低延迟查询的关键。切换到 Indexes 页签并点击 Create index(或从列头快捷菜单发起):
| 索引类型(Type) | 适用场景与行为语义 | 多列复合与排序方向(Order)规则 | 存储模式差异说明(Shared V2 vs JsonTable) |
|---|---|---|---|
| Key(普通二级索引) | 加速等值过滤(equal)、范围过滤(greaterThan、between)、前缀匹配(startsWith)与排序(orderAsc / orderDesc)。例如 idx_status_priority(status + priority)。 | 支持单列或多列复合(遵循最左前缀原则);每列可独立选择 Asc(升序)或 Desc(降序)。 | Shared V2 创建原生 OceanBase 二级索引;JsonTable 同步维护 _jt_index_values 类型化侧表加速过滤。 |
| Unique(唯一索引) | 强制保证单列或多列组合在表内全局唯一(重复写入时立即抛出冲突错误),例如工单编号 uk_ticket_no(ticketNo)。 | 支持单列或多列复合唯一约束;每列可选 Asc / Desc。 | Shared V2 使用原生 UNIQUE 索引;JsonTable 通过 _jt_unique_index_values 侧表 + 数据库级复合唯一索引强制保障零并发穿透。 |
| Fulltext(全文索引) | 为文本列(varchar / text)开启关键词搜索能力。调用 Query.search(attr, keyword) 前必须先为该列建立 Fulltext 索引,例如 ft_title(title)。 | 支持选择文本列构建全文索引。 | Shared V2 使用底层原生 FULLTEXT 索引;JsonTable 仍要求声明 Fulltext 索引并在小候选集下执行内存子串匹配。 |
| Spatial(空间索引) | 加速 Point、Line、Polygon 空间几何列的距离与相交计算。 | 仅支持选择单个空间类型列,不适用 Asc / Desc 排序方向。 | 仅 Shared V2(及 collection)支持;JsonTable 不支持。 |
4. 电子表格行操作、导入导出与 SDK 查询/批量事务
(1)Console 电子表格视图(Rows)高效操作
在表的 Rows 页签中,管理员与运营人员可以像操作在线电子表格一样管理数据:
创建与内联编辑:点击工具栏 Create row 按表单录入新行;直接双击列表中的任意业务单元格即可内联修改并即时保存(系统列
$id、$createdAt、$updatedAt只读不可改)。复杂字段展开与复制:点击行尾展开按钮可打开抽屉完整编辑长文本、JSON 或 Relationship 关联字段;通过行右侧
⋯菜单可执行 Duplicate(复制为新$id的行)、Manage permissions(配置单行 ACL,需开启 Row security)、View activity(查看单行修改审计)、Copy as JSON 或 Delete(永久删除该行)。一键生成测试数据(Generate sample data):在空表或工具栏点击 Generate sample data,系统会根据当前各列的类型与枚举约束自动追加一批逼真的测试数据(仅追加不覆盖现有行,极大方便联调验证)。
CSV 批量导入与导出:工具栏支持将本地 CSV 文件按列映射批量导入建行;切换到 Export 页签可自定义勾选导出列、选择分隔符(逗号
,、分号;、制表符Tab或竖线|)、设置是否包含表头及是否仅导出当前筛选结果。
(2)SDK 查询算子(Query Operators)与游标分页实战
以下示例展示如何使用 agentbase-node-sdk@2.10.0 对 enterprise_biz_db 中的 customer_tickets 表执行多条件组合过滤、全文搜索、排序与高性能游标分页(cursorAfter):
import { Client, Databases, Query } from 'agentbase-node-sdk'; // 版本固定 @2.10.0
const client = new Client()
.setEndpoint('https://appbuild.oceanbase.com/v1')
.setProject('enterprise-ai-hub-210')
.setKey('<APPBASE_API_KEY>');
const databases = new Databases(client);
// 1. 组合查询:筛选状态为 open 或 processing、优先级为 P0/P1、标题含“向量索引”的工单,按创建时间倒序取前 20 条
const page1 = await databases.listDocuments(
'enterprise_biz_db',
'customer_tickets',
[
Query.equal('status', ['open', 'processing']),
Query.equal('priority', ['P0', 'P1']),
Query.search('title', '向量索引'), // 需已为 title 列创建 Fulltext 索引
Query.orderDesc('$createdAt'),
Query.limit(20)
]
);
// 2. 高性能深度分页:使用上一页最后一条记录的 $id 作为 cursorAfter 游标,避免大 offset 扫描退化
if (page1.documents.length === 20) {
const lastId = page1.documents[page1.documents.length - 1].$id;
const page2 = await databases.listDocuments(
'enterprise_biz_db',
'customer_tickets',
[
Query.equal('status', ['open', 'processing']),
Query.orderDesc('$createdAt'),
Query.cursorAfter(lastId),
Query.limit(20)
]
);
}常用 Query 算子速查表
| 算子分类 | SDK 方法调用示例 | 行为说明与索引利用建议 |
|---|---|---|
| 等值与集合匹配 | Query.equal('status', ['open', 'processing']) / Query.notEqual('priority', 'P2') | 单个字段传入数组时表示 IN (...)(邏輯或);不同字段的多个 Query 之间为 AND(逻辑与)。建议为过滤列建 Key 索引。 |
| 数值与时间范围 | Query.greaterThan('slaHours', 4)、Query.lessThanEqual('satisfactionScore', 4.5)、Query.between('$createdAt', '2026-10-01T00:00:00Z', '2026-10-22T23:59:59Z') | 适用于 integer、float、datetime 列的高效区间裁剪。 |
| 字符串与全文匹配 | Query.startsWith('ticketNo', 'TK-202610')、Query.contains('title', '网关')、Query.search('title', 'OceanBase 向量') | startsWith 可利用索引左前缀;search 要求目标列已建立 Fulltext 索引。 |
| 空值判断与逻辑组合 | Query.isNull('resolvedAt')、Query.isNotNull('resolvedAt')、Query.or([...])、Query.and([...]) | 支持构建复杂的嵌套布尔过滤条件树。 |
| 排序、投影与分页 | Query.orderAsc('priority')、Query.orderDesc('$createdAt')、Query.select(['$id', 'title', 'status'])、Query.limit(25)、Query.cursorAfter(docId) | 生产环境强烈推荐使用 Query.cursorAfter(lastId) 替代大数值 Query.offset(N),实现 $O(1)$ 复杂度翻页。 |
(3)批量事务操作(Bulk CRUD Transactions)
当需要一次性批量导入或更新多条工单记录并保证原子性(All-or-Nothing:任一行违反唯一索引或必填约束则整批回滚)时,可使用批量接口:
批量创建(Bulk Create / Upsert):在同一数据库事务内同步写入多条行记录、权限表与索引项。
按条件批量更新或删除:基于查询条件在同一事务内原子更新或清理匹配行,大幅降低网络往返开销。
常见问题与排障
Q1:刚刚在 Console 点击创建了新列或新索引,为什么立刻写入数据或查询时提示字段不存在或索引未就绪?
原因分析: 为了防止大表 DDL 阻塞线上并发请求,Agentbase 的列创建与索引构建均采用异步处理机制:提交后状态先进入 processing(处理中),待底层物理列添加或索引构建完成后状态才切换为 available(可用)。
解决方案:
在 Console 的 Columns 或 Indexes 页签观察状态徽标,待其从处理中变为正常可用状态后再发起业务写入或调用
Query.search()。若偶发提示“列已创建但注释(Comment)未保存”,无需删除重建列,直接点击该列右侧菜单进入 编辑列(Edit column) 重新保存一次 Comment 即可。
Q2:调用 Query.search('title', '向量索引') 时报错 Requires a fulltext index 怎么办?
原因分析: Query.search() 与 Query.notSearch() 算子强制要求被检索的目标列(如 title)上已经存在状态为 available 的 Fulltext(全文) 类型索引;仅有普通的 Key 或 Unique 索引无法支撑 search 算子。
解决步骤: 进入目标表 customer_tickets → 切换到 Indexes 页签 → 点击 Create index → 将 Type 选择为 Fulltext,在 Fields 中选中 title 列并保存。待索引构建完成后即可正常调用 Query.search()。
Q3:为什么为敏感文本列开启了 Encrypt(加密)选项后,无法在查询筛选器中使用该列过滤?
原因分析: 开启 Encrypt 属性的文本列在写入数据库前已由服务端完成高强度加密,存储在底层的是密文而非明文。由于密文不支持关系型索引匹配或子串扫描,因此加密列在设计上不支持作为 Query 过滤条件或加入任何索引。如果需要按某个敏感标识(如脱敏卡号或外部证件号)做等值检索,建议在业务层另存一个单向 HMAC-SHA256 摘要列(varchar 类型并建 Key / Unique 索引)用于精确查找,而将原始敏感内容存入 Encrypt 列。
相关文档
数据库概览(Databases Overview):了解 OceanBase
Shared V2与JsonTable存储模式差异及项目级存储模式转换。Schema 版本与回滚(Schema Versions):对表、列、索引与注释执行数据库级快照管理与零数据丢失回滚。
SQL 访问面(SQL Proxy):使用标准 SQL 对
customer_tickets等业务表执行关联查询、聚合统计与受控 DML。备份与恢复(Backups):在对核心业务表执行大规模删除或重构前创建手动备份快照。
认证概览(Auth Overview):查阅表级 Permissions 与行级安全(Row Security)中使用的
Role语法。
