Docs
文档目录

表、列、行与索引

功能概述

表(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-001OceanBase 向量索引在高并发混合检索下的 HNSW 参数调优咨询P0processinguser_zhangwei_001(张伟)team_support_ops / user_lina_002(李娜)
TK-20261022-002AI 网关 prod-enterprise-ai-gateway 工具接入与配额验证P1resolveduser_zhangwei_001(张伟)team_ai_platform / user_lina_002(李娜)
TK-20261022-003知识库 kb_enterprise_support 同义词词典与 GraphRAG 实体抽取联调P1openuser_zhangwei_001(张伟)team_kb_governance
TK-20261022-004Shared V2 模式下智能体长期记忆蒸馏(Context Dreaming)触发策略确认P2resolveduser_lina_002(李娜)team_ai_platform

角色、入口与关联关系

控制台入口与路由

权限与关联关系

  1. 结构管理权限:创建/删除表、创建/修改/删除列与索引需要组织角色具备 databases.write / tables.write 权限(owner、admin、developer、editor)。

  2. 与 Schema 版本控制互斥保护:若当前数据库已启用并存在处于 active 状态的 Schema 版本,在独立接口直接修改表/列/索引结构会受版本锁保护(返回 409),建议统一通过提交新 Schema 版本或带完整列定义的 updateTable 推进结构变更;但修改列注释(updateColumnComment)属于零 DDL 元数据操作,即使在 active 版本下也可直接执行。

  3. 与智能体工作台及 SQL Proxy 联动:表注释(Table comment)与列注释(Column comment)不仅在 Console 表头展示,还会同步暴露给 SQL 访问面(SQL Proxy) 与智能体工具调用,辅助大模型精准理解业务字段含义。


功能详解与操作指南

1. 创建数据表(Create table)

  1. 进入数据库 enterprise_biz_db 的 Tables 页签,点击右上角 创建表 按钮。

  2. 在弹窗中填写表定义信息:

    • Name(必填):表的业务显示名称,例如 客户工单表 或 customer_tickets。

    • Display name / comment(可选):表的业务说明或别名,最长 256 字符(例如:存储企业客户提交的技术支持工单、SLA 等级与处理状态)。该注释仅用于增强可读性与 AI 语义理解,不改变 Table ID 与 Name。

    • Table ID(可选):可自行填写;留空时由系统生成 ID;仅允许 a-z、A-Z、0-9、.、-、_,首字符必须为字母或数字,最长 36 字符(例如 customer_tickets)。

  3. 点击 确认(Confirm) 完成建表,成功后进入新表。

2. 列类型全集与创建列(Create column)

切换到表的 列 页签点击 创建列,即可创建新列。

每个列均包含三个基础标识属性:

列数据类型(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。
数值与布尔类Integer64 位有符号整数(或大整数)支持设置最小值(Min)、最大值(Max)、必填(Required)、默认值(Default)及数组(Array)。可用于 slaHours、计数与原子自增/自减。
数值与布尔类Float双精度浮点数(Double / Decimal)支持设置 Min、Max、Required、Default、Array。适合 satisfactionScore(满意度评分)、金额比率等指标。
数值与布尔类Boolean布尔值(true / false)支持 Required、Default、Array。适合 isEscalated(是否升级处理)等状态位。
时间与枚举类DatetimeISO-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 页签中管理数据:

(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(可用)。

解决方案:

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 列。


相关文档