查询连接器表结构¶

读取一个结构化来源对象的字段结构和映射参考信息。先查询对象，再将选中的对象标识传入此接口。

POST https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/schema

调用前准备¶

先查询连接器表，选择一个对象。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID；确认查看可浏览的连接器接口中该条目的 enabled 和 capabilities.describe_schema 均为 true。

下方示例使用：

$AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。
$WORKSPACE_ID：要查询的工作区 ID，通过 X-Workspace-ID Header 传递。
$CONNECTOR_ID：查看可浏览的连接器接口返回的连接器 ID。
$SOURCE_TYPE：查看可浏览的连接器接口返回的来源类型。
$DATABASE：查询对象接口中选中对象的 database。
$SCHEMA：查询对象接口中选中对象的 schema；仅 SQL Server、Oracle 和 PostgreSQL 使用。
$TABLE：查询对象接口中选中对象的 table；MongoDB 不使用该变量。
$COLLECTION：查询对象接口中选中对象的 collection；仅 MongoDB 使用。

请求体¶

字段	类型	是否必填	说明
`connector_id`	string	是	连接器 ID。
`source`	object	是	来源对象引用。
`source.connector_id`	string	是	连接器 ID，必须与顶层 `connector_id` 相同。
`source.source_type`	string	是	查看可浏览的连接器接口返回的结构化来源类型。
`source.database`	string	是	查询连接器数据库接口返回的数据库名称。
`source.schema`	string	否	查询数据库分类接口返回的 Schema 名称；来源不支持 Schema 层级时省略。
`source.table`	string	非 MongoDB 时是	查询连接器表接口返回的表名。
`source.collection`	string	MongoDB 时是	查询连接器表接口返回的集合名。
`mongo_sample_limit`	integer	否	MongoDB 专用的采样文档数量上限。仅当 `source.source_type` 为 `SOURCE_TYPE_MONGODB` 时传入。

请求示例¶

关系型数据库¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/schema" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"connector_id\": \"$CONNECTOR_ID\",
    \"source\": {
      \"connector_id\": \"$CONNECTOR_ID\",
      \"source_type\": \"$SOURCE_TYPE\",
      \"database\": \"$DATABASE\",
      \"schema\": \"$SCHEMA\",
      \"table\": \"$TABLE\"
    }
  }"

SQL Server、Oracle 和 PostgreSQL 传入 schema；Hive 和 MySQL 从请求体中省略该字段。

MongoDB¶

MongoDB 使用 collection，不传 table。需要限制结构推断采样量时，在请求体顶层传入 mongo_sample_limit；下例的 100 是示例值，不是默认值。

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/schema" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"connector_id\": \"$CONNECTOR_ID\",
    \"source\": {
      \"connector_id\": \"$CONNECTOR_ID\",
      \"source_type\": \"SOURCE_TYPE_MONGODB\",
      \"database\": \"$DATABASE\",
      \"collection\": \"$COLLECTION\"
    },
    \"mongo_sample_limit\": 100
  }"

成功响应¶

成功时返回 200。从 data.schema_snapshot 读取字段结构；其余字段用于后续映射和一致性校验。不同来源返回的 JSON 结构可能不同，调用方应保留未知字段。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "schema_snapshot": {
      "fields": [
        {
          "name": "id",
          "type": "bigint"
        }
      ]
    },
    "mapping_draft": [],
    "target_type_catalog": [],
    "field_compatibilities": [],
    "source_schema_hash": "schema-hash",
    "source_object_hash": "object-hash",
    "connector_config_hash": "connector-hash",
    "mapping_hash": "mapping-hash",
    "flatten_hash": "flatten-hash",
    "endpoint_results": []
  }
}

响应字段如下。

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

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data.schema_snapshot`	JSON	来源对象的字段结构快照。
`data.mapping_draft`	JSON	推导出的映射草案；没有映射项时返回空数组。
`data.target_type_catalog`	JSON	可用目标类型目录；没有目录项时返回空数组。
`data.field_compatibilities`	JSON	字段兼容性信息；没有兼容性项时返回空数组。
`data.source_schema_hash`	string	来源结构快照摘要。
`data.source_object_hash`	string	来源对象摘要。
`data.connector_config_hash`	string	连接器配置摘要，不含原始密钥。
`data.mapping_hash`	string	映射配置摘要；不适用时可能省略。
`data.flatten_hash`	string	扁平化配置摘要；不适用时可能省略。
`data.endpoint_results`	JSON[]	当前返回空数组。

错误响应¶

{
  "code": "ErrParamInvalid",
  "msg": "invalid parameter",
  "data": null
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
`400`	`ErrParamInvalid`	缺少 `connector_id` 或 `source`，或对象引用与连接器不匹配。	使用查询对象接口返回的对象字段重新组装 `source`。
`501`	`STRUCTURED_CONNECTOR_SERVICE_UNAVAILABLE`	当前服务未提供结构化数据源发现。	暂时无法使用本组接口。
`200`	`STRUCTURED_LOAD_FEATURE_DISABLED`	当前工作区未启用结构化数据源功能。	检查该工作区是否可使用此功能。
`200`	`STRUCTURED_LOAD_MONGODB_DISABLED`	当前工作区未启用 MongoDB 结构化发现。	不要继续调用该 MongoDB 连接器的发现接口。
`500`	`ErrServer`	服务未能读取来源字段结构。	保留脱敏错误信息后重试。

后续操作¶

保存返回的字段与对象标识，前往导入任务的创建任务，用于配置结构化导入。

最后更新于 2026 年 8 月 22 日