<span id="读取-kafka-来源样本"></span>

# Read Kafka source samples

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

Read a bounded number of messages from a Kafka topic to inspect input format and fields.

```text
POST https://api.moi.matrixorigin.cn/v5/connectors/structured/v1/source/sample
```

<span id="调用前准备"></span>

## Before you call this API

Prepare a personal access token for the target workspace with source-read or import-run privileges. Install jq and set example variables. See [Common information](objects.md) for identity, environment, and result handoff.

<span id="请求体"></span>

## Request body

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/connectors/structured/v1/source/sample" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg v0 "$CONNECTOR_ID" --arg v1 "$CONNECTOR_ID" --arg v2 "$KAFKA_TOPIC" '{"connector_id":$v0,"source":{"connector_id":$v1,"source_type":"SOURCE_TYPE_KAFKA"},"limit":5,"kafka_sample":{"topic_mode":"single","topics":[$v2]}}')"
```

:::::
:::::{tab-item} Parameters

source_type must be SOURCE_TYPE_KAFKA, not lowercase kafka. Kafka source has no database, schema, table, or collection. Samples are not written to a target table. has_more and next_position describe this sample. Current input accepts no cursor/position, so they are not regular pagination tokens for guaranteed traversal of all messages by repeated sampling.

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `connector_id` | string | Yes | Enabled connector ID supporting import in the current workspace. |
| `source` | object | Yes | Source object for the same connector. |
| `source.connector_id` | string | Yes | Must match the outer connector_id. |
| `source.source_type` | string | Yes | Uppercase API enum permitted by this operation, not the Worker's lowercase name. |
| `limit` | integer | Yes | 1–100; no contract to populate a default when omitted. |
| `kafka_sample` | object | Yes | Select a single topic, multiple topics, or a name pattern. |
| `kafka_sample.topic_mode` | string | Yes | single, multiple, or pattern. |
| `kafka_sample.topics` | string[] | Conditional | Exactly one nonempty topic for single; at least one, all nonempty, for multiple. |
| `kafka_sample.topic_pattern` | string | Conditional | Nonempty name-matching pattern for pattern mode. |

:::::
::::::
:::::::

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "rows": [
      {
        "value": {
          "id": 1
        }
      }
    ],
    "next_position": {
      "offset": 1
    },
    "has_more": false
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success; also check HTTP and business codes. |
| `msg` | string | Response information. |
| `data` | object | Current source result. |
| `data.rows` | array | Raw JSON samples returned by the source, preserving keys, values, and format information. |
| `data.next_position` | JSON | Optional read position shaped by the Kafka sample result; not a pagination parameter accepted by this operation. |
| `data.has_more` | boolean | Whether more results exist for this sample; not import task state. |

:::::
::::::
:::::::

<span id="错误响应"></span>

## Error response

Distinguish parameter, capability, authorization, and runtime-state failures using [Errors and environments](objects.md#errors-and-environments). Do not infer business success from HTTP 200 alone.
