# 查询连接器表结构

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

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

## 调用前准备

先[查询连接器表](list-tables.md)，选择一个对象。准备有目标工作区访问权限的个人访问令牌和目标工作区 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` 时传入。 |

## 请求示例

### 关系型数据库

```bash
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` 是示例值，不是默认值。

```bash
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 结构可能不同，调用方应保留未知字段。

```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[] | 当前返回空数组。 |

## 错误响应

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 30 28 30

* - 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`
  - 服务未能读取来源字段结构。
  - 保留脱敏错误信息后重试。
```

## 后续操作

保存返回的字段与对象标识，前往导入任务的[创建任务](../import-tasks/create-import-task.md)，用于配置结构化导入。