表、列、行与索引
功能概述
表(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 利用丰富的查询算子(如 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 客户工单表
假设项目的 enterprise_biz_db 数据库中有一张 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)→ 点击左侧栏 数据库 → 点击进入数据库企业智能客服业务库(enterprise_biz_db)→ 点击表customer_tickets。路由地址:
/console/project-{region}-{project}/databases/database-{databaseId}/table-{tableId}表内二级页签结构:
Rows(默认电子表格页):浏览、筛选、创建和编辑行,配置行权限,以及导入或导出 CSV。
列:查看与创建强类型列、配置必填/默认值/数组/加密属性及编辑最高 256 字符的列注释。
索引:创建与管理
Key(普通索引)、Unique(唯一索引)、Fulltext(全文索引)及Spatial(空间索引)。活动:查看表与行记录的操作审计流水。
用量:查看该表近期的行读写趋势指标。
内容审核:查看表的内容审核入口。CSV 导入和导出位于 Rows 工具栏。
设置:配置表启用状态(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 页签,点击右上角 创建表 按钮。在弹窗中填写表定义信息:
Name(必填):表的业务显示名称,例如
客户工单表或customer_tickets。Display name / comment(可选):表的业务说明或别名,最长 256 字符(例如:
存储企业客户提交的技术支持工单、SLA 等级与处理状态)。该注释仅用于增强可读性与 AI 语义理解,不改变Table ID与Name。Table ID(可选):可自行填写;留空时由系统生成 ID;仅允许
a-z、A-Z、0-9、.、-、_,首字符必须为字母或数字,最长 36 字符(例如customer_tickets)。
点击 确认(Confirm) 完成建表,成功后进入新表。
2. 列类型全集与创建列(Create column)
切换到表的 列 页签点击 创建列,即可创建新列。
每个列均包含三个基础标识属性:
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 模式不支持空间列与空间算子。 |
连续建列技巧:在 创建列 弹窗底部勾选连续创建模式,可在保存当前列后保持弹窗不关闭,快速连续录入整张表的所有字段。
3. 索引类型与创建索引(Create index)
为高频过滤(WHERE)与排序(ORDER BY)字段建立合理的索引,是保障生产环境低延迟查询的关键。切换到 索引 页签并点击 创建索引(或从列头快捷菜单发起):
| 索引类型(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 页签中管理数据:
创建和编辑行:至少有一个列状态为
available且具备写权限时,点击 创建行(Create row);已有行可点击行 ID 或 编辑(Edit),在抽屉中修改并保存。复制和删除:使用行操作区的 复制(Duplicate) 创建新行,或使用 删除(Delete) 删除该行;操作受当前权限限制。
CSV 批量导入与导出:工具栏支持将本地 CSV 文件按列映射批量导入建行;点击工具栏的 导出 CSV(Export CSV) 可自定义勾选导出列、选择分隔符(逗号
,、分号;、制表符Tab或竖线|)、设置是否包含表头及是否仅导出当前筛选结果。
(2)SDK 查询算子(Query Operators)与游标分页实战
以下示例展示如何使用 agentbase-node-sdk@2.12.0 对 enterprise_biz_db 中的 customer_tickets 表执行多条件组合过滤、全文搜索、排序与高性能游标分页(cursorAfter):
运行前将 <APPBASE_ENDPOINT_WITH_V1> 和 <APPBASE_PROJECT_ID> 替换为已确认的目标 API 地址和项目 ID。未替换时 SDK 会拒绝无效地址,不会发送请求。
import { Client, Databases, Query } from 'agentbase-node-sdk'; // 版本固定 @2.12.0
const client = new Client()
.setEndpoint('<APPBASE_ENDPOINT_WITH_V1>')
.setProject('<APPBASE_PROJECT_ID>')
.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.equal('priority', ['P0', 'P1']),
Query.search('title', '向量索引'),
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) | 深分页可考虑使用游标;翻页时保持筛选和排序条件一致。 |
(3)批量操作与事务
批量接口可用于一次创建、更新或删除多条记录,但不能仅凭“批量”推断多个请求会作为一个事务提交。需要多个操作原子提交时,使用对应数据库 API 的事务:创建事务,将支持的写操作传入 transactionId 或暂存为操作,再明确提交或回滚。暂存成功不代表已经提交;遇到过期、冲突或结果未知时,先查询事务状态和数据,再决定后续操作。
常见问题与排障
Q1:刚刚在 Console 点击创建了新列或新索引,为什么立刻写入数据或查询时提示字段不存在或索引未就绪?
原因分析: 为了防止大表 DDL 阻塞线上并发请求,Agentbase 的列创建与索引构建均采用异步处理机制:提交后状态先进入 processing(处理中),待底层物理列添加或索引构建完成后状态才切换为 available(可用)。
解决方案:
在 Console 的 列 或 索引 页签观察状态徽标,待其从处理中变为正常可用状态后再发起业务写入或调用
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 → 切换到 索引 页签 → 点击 创建索引 → 将 Type 选择为 Fulltext,在 字段 中选中 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语法。
