# 检查数据源与采样

在配置结构化数据导入前，使用 AI Studio SDK 检查 MySQL 或 Doris 连接器源表的 CDC 能力与禁用原因，或从 Kafka Topic 读取小批量样本消息以核对字段与消息结构。

(sdk-ai-studio-source-sample-flow)=
## 任务流程

导入前检查分为关系型源表能力核验与消息流样本读取两类只读操作；两者均基于已配置的连接器 ID 执行，不会向目标表写入数据。

```text
工作区连接器服务 + 已配置连接器 ID
               │
               ├── MySQL / Doris 连接器 ──▶ 检查源表 CDC 能力与禁用原因
               │
               └── Kafka 连接器 + Topic ──▶ 读取小批量样本消息与下一读取位置
                                                       │
                                                       ▼
                                         确认读取模式与消息结构后配置导入任务
```

(sdk-ai-studio-source-sample-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. **关系型连接器与源表信息**（检查 CDC 能力时）：按 [管理连接器](管理连接器.md#sdk-ai-studio-connector-list) 获取已配置的 MySQL 或 Doris 连接器 ID（`RELATIONAL_CONNECTOR_ID`），并确认来源类型（`SOURCE_TYPE`）、数据库名（`SOURCE_DATABASE`）、表名（`SOURCE_TABLE`）及可选 Schema 名（`SOURCE_SCHEMA`）。
3. **Kafka 连接器与 Topic**（读取样本时）：按 [管理连接器](管理连接器.md#sdk-ai-studio-connector-list) 获取已配置的 Kafka 连接器 ID（`CONNECTOR_ID`），并向 Kafka 管理员确认连接器账号具备读取权限的 `KAFKA_TOPIC`。

(sdk-ai-studio-source-sample-capability)=
## 检查关系型源表能力

数据源能力检查适用于 MySQL 和 Doris 连接器，`SOURCE_TYPE` 分别设为 `SOURCE_TYPE_MYSQL` 或 `SOURCE_TYPE_DORIS`。调用返回对应引擎的 CDC 可用标志及禁用原因列表，便于在创建结构化导入任务前确定采用全量读取还是增量 CDC。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace = client.workspace(os.environ["WORKSPACE_ID"])
service = workspace.connectors()

capability = service.structured_source_capability(
    os.environ["RELATIONAL_CONNECTOR_ID"],
    os.environ["SOURCE_TYPE"],
    os.environ["SOURCE_DATABASE"],
    os.environ["SOURCE_TABLE"],
    os.environ.get("SOURCE_SCHEMA", ""),
)
print("MySQL CDC:", capability.mysql_cdc_available, "Doris CDC:", capability.doris_cdc_available)
print("Disabled reasons:", list(capability.disabled_reasons))
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	service := workspace.Connectors()

	capability, err := service.StructuredSourceCapability(
		ctx,
		os.Getenv("RELATIONAL_CONNECTOR_ID"),
		os.Getenv("SOURCE_TYPE"),
		os.Getenv("SOURCE_DATABASE"),
		os.Getenv("SOURCE_TABLE"),
		os.Getenv("SOURCE_SCHEMA"),
	)
	if err != nil {
		panic(err)
	}
	fmt.Println("MySQL CDC:", capability.MysqlCDCAvailable, "Doris CDC:", capability.DorisCDCAvailable)
	fmt.Println("Disabled reasons:", capability.DisabledReasons)
}
```

::::

:::::

(sdk-ai-studio-source-sample-read)=
## 读取 Kafka Topic 样本

复用工作区连接器服务，传入 Kafka 连接器 ID 与目标 Kafka Topic 读取小批量样本消息。来源类型固定传入枚举值 `SOURCE_TYPE_KAFKA`，单次采样条数范围为 1 至 100。以下示例从单个 Kafka Topic 读取最多 5 条消息，并输出是否仍有后续消息及下一读取位置。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
sample = service.structured_source_sample(
    os.environ["CONNECTOR_ID"],
    "SOURCE_TYPE_KAFKA",
    5,
    "single",
    [os.environ["KAFKA_TOPIC"]],
)
for row in sample.rows:
    print(row)
print("More samples:", sample.has_more, "Next position:", sample.next_position)
```

::::

::::{tab-item} Go
:sync: go

```go
sample, err := service.StructuredSourceSample(
	ctx,
	os.Getenv("CONNECTOR_ID"),
	"SOURCE_TYPE_KAFKA",
	5,
	"single",
	[]string{os.Getenv("KAFKA_TOPIC")},
	"",
)
if err != nil {
	panic(err)
}
for _, row := range sample.Rows {
	fmt.Println(string(row))
}
fmt.Println("More samples:", sample.HasMore)
fmt.Println("Next position:", string(sample.NextPosition))
```

::::

:::::

能力检查与消息采样仅用于导入前核对输入条件；数据导入是否完成需通过对应导入任务与目标表记录确认。

(sdk-ai-studio-source-sample-next)=
## 下一步

- [创建导入导出任务](创建导入导出任务.md)
- [查看结构化导入任务](查看结构化导入任务.md)
