添加数据¶

向已有知识库追加数据源。请求成功不表示来源已经完成解析或索引。

POST https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/sources

调用前准备¶

先检查数据源是否已添加，移除重复项；按数据库或卷批量选择时先预览待添加的数据源。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

直接添加来源时，按来源类型提供字段：

来源类型	必填字段
`catalog_table`	`table_id`
`catalog_file`	`file_id`、`volume_id`
`local_file`	上传本地文件返回的文件 ID、原始 `file_name`

按范围选择仅支持 Catalog 的 Database 和 Volume，不能用 source_selections 添加 Catalog 之外的数据源。

请求体¶

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/sources" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": [
      {
        "source_type": "catalog_file",
        "file_id": "$FILE_ID",
        "volume_id": $VOLUME_ID
      }
    ]
  }'

参数说明

路径参数

字段	类型	必填	说明
`model_id`	integer	是	要追加数据源的知识库 ID。

请求体

字段路径中的 [] 表示数组中的每一项。例如，sources[].source_type 表示 sources 数组中每一项的 source_type 字段。

字段	类型	必填	说明
`sources`	array of object	是	要添加的来源。
`source_selections`	array of object	否	按数据库或卷选择来源的规则。

来源记录

下面表格展开请求示例中 sources 数组的每一项；每一行是该数组项的一个字段。

字段	类型	必填	说明
`source_type`	string	是	来源类型，例如 `catalog_table`、`catalog_file`、`local_file`。
`table_id`	integer	条件必填	`catalog_table` 来源的表 ID。
`file_id`	string	条件必填	文件来源的文件 ID。
`file_name`	string	条件必填	`local_file` 来源的原始文件名。
`volume_id`	integer	条件必填	`catalog_file` 来源的权威卷 ID。

来源选择

下面表格展开请求示例中 source_selections 数组的每一项；每一行是该数组项的一个字段。

字段	类型	必填	说明
`kind`	string	条件必填	`database_tables` 或 `volume_files`。
`database_id`	integer	条件必填	`database_tables` 的 Catalog Database ID。
`volume_id`	integer	条件必填	`volume_files` 的 Catalog Volume ID。
`all_selected`	boolean	是	`true` 选择当前范围内全部对象；`false` 时必须提供对应的显式选择 ID。
`selected_table_ids`	array of integer	条件必填	`all_selected` 为 `false` 时，显式选中的 Catalog 表 ID。
`selected_file_ids`	array of string	条件必填	`all_selected` 为 `false` 时，显式选中的 Catalog 文件 ID。
`excluded_table_ids`	array of integer	否	全选时要排除的 Catalog 表 ID。
`excluded_file_ids`	array of string	否	全选时要排除的 Catalog 文件 ID。
`filters`	object	否	在选择范围内按名称或扩展名过滤；未提供的筛选字段不参与过滤。

筛选条件

下面表格展开请求示例中 source_selections[].filters 对象；每一行是该对象的一个字段。

字段	类型	必填	说明
`table_name`	string	否	表名筛选条件。
`file_name`	string	否	文件名筛选条件。
`file_ext`	array of string	否	文件扩展名筛选条件。

成功响应¶

成功时返回 200。保存每项来源的 row_id，并通过处理任务状态确认实际处理结果。

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "data_domain": {
      "model_id": 401,
      "catalog_id": 10,
      "database_id": 20,
      "raw_volume_id": 30,
      "processed_volume_id": 31,
      "ensure_status": "ready"
    },
    "sources": [
      {
        "row_id": "src_01",
        "source_type": "file",
        "model_id": 401,
        "resource_id": "file_01",
        "ingest_status": "pending",
        "effective_enabled": true
      }
    ],
    "jobs": [
      {
        "job_id": "job_01",
        "source_id": "src_01",
        "model_id": 401,
        "job_type": "ingest",
        "job_status": "pending",
        "idempotency_key": "idem_01",
        "retry_count": 0
      }
    ]
  }
}

字段说明

通用字段

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data`	object	响应数据。

创建结果

下面表格展开响应示例中 data 对象；每一行是该对象的一个字段。

字段	类型	说明
`data_domain`	object	知识库的数据域及其确保状态。
`sources`	array of object	已创建的来源记录。
`jobs`	array of object	新建的处理任务。

数据域

下面表格展开响应示例中 data.data_domain 对象；每一行是该对象的一个字段。

字段	类型	说明
`model_id`	integer	知识库 ID。
`catalog_id`	integer	Catalog ID。
`database_id`	integer	数据库 ID。
`raw_volume_id`	integer	原始文件卷 ID。
`processed_volume_id`	integer	处理结果卷 ID。
`ensure_status`	string	数据域的当前确保状态。
`last_ensure_error`	string 或 null	最近一次确保数据域时的错误。
`last_checked_at`	integer	最近检查时间。

来源记录

下面表格展开响应示例中 data.sources 数组的每一项；每一行是该数组项的一个字段。

字段	类型	说明
`row_id`	string	来源记录 ID。
`source_id`	string 或 null	来源 ID。
`source_type`	string	来源类型。
`model_id`	integer	所属知识库 ID。
`resource_id`	string	来源资源 ID。
`source_resource_id`	string 或 null	原始资源 ID。
`kb_resource_id`	string 或 null	知识库侧资源 ID。
`source_file_id`	string 或 null	原始文件 ID。
`kb_file_id`	string 或 null	知识库文件 ID。
`source_table_id`	integer 或 null	原始表 ID。
`kb_table_id`	integer 或 null	知识库表 ID。
`display_name`	string 或 null	显示名称。
`path`	array of string	来源路径。
`source_path`	string 或 null	原始来源路径。
`db_name`	string 或 null	数据库名称。
`table_name`	string 或 null	表名称。
`size_bytes`	integer 或 null	文件大小。
`row_count`	integer 或 null	表行数。
`ingest_status`	string	处理状态；`pending` 不表示已可检索。
`enabled`	boolean 或 null	配置的启用状态。
`expires_at`	integer 或 null	到期时间。
`expired`	boolean	是否已到期。
`effective_enabled`	boolean	当前实际生效状态。
`force_enabled_after_expiry`	boolean	到期后是否强制启用。
`tags`	array of string	来源标签。
`segment_version_id`	string 或 null	当前分段版本 ID。
`index_version`	integer 或 null	当前索引版本。
`created_by`	string 或 null	创建者 ID。
`updated_by`	string 或 null	最后更新者 ID。
`updated_at`	integer 或 null	最近更新时间。
`error`	string 或 null	处理错误。
`governance_status`	string	治理状态。
`legacy_origin`	string 或 null	历史来源标记。

处理任务

下面表格展开响应示例中 data.jobs 数组的每一项；每一行是该数组项的一个字段。

字段	类型	说明
`job_id`	string	任务 ID。
`source_id`	string	关联来源 ID。
`job_type`	string	任务类型。
`job_status`	string	当前任务状态。
`idempotency_key`	string	任务幂等键。
`retry_count`	integer	已记录的重试次数。
`model_id`	integer	所属知识库 ID。
`operation_id`	string 或 null	操作 ID。
`workflow_execution_id`	string 或 null	工作流执行 ID。
`source_file_id`	string 或 null	原始文件 ID。
`kb_file_id`	string 或 null	知识库文件 ID。
`source_table_id`	integer 或 null	原始表 ID。
`kb_table_id`	integer 或 null	知识库表 ID。
`next_retry_at`	integer 或 null	下次重试时间。
`error`	string 或 null	任务错误。
`created_at`	integer	创建时间。
`updated_at`	integer	最近更新时间。

错误响应¶

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "invalid source request",
  "data": null
}

字段说明

字段	类型	说明
`code`	string	错误代码。
`msg`	string	面向调用者的错误信息。
`data`	null	发生错误时为 `null`。

后续操作¶

使用 data.jobs[].job_id 查询数据处理任务，确认来源处理完成。

最后更新于 2026 年 9 月 11 日