Read Kafka source samples¶
Read a bounded number of messages from a Kafka topic to inspect input format and fields.
POST https://api.moi.matrixorigin.cn/v5/connectors/structured/v1/source/sample
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 for identity, environment, and result handoff.
Request body¶
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]}}')"
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 |
|---|---|---|---|
|
string |
Yes |
Enabled connector ID supporting import in the current workspace. |
|
object |
Yes |
Source object for the same connector. |
|
string |
Yes |
Must match the outer connector_id. |
|
string |
Yes |
Uppercase API enum permitted by this operation, not the Worker’s lowercase name. |
|
integer |
Yes |
1–100; no contract to populate a default when omitted. |
|
object |
Yes |
Select a single topic, multiple topics, or a name pattern. |
|
string |
Yes |
single, multiple, or pattern. |
|
string[] |
Conditional |
Exactly one nonempty topic for single; at least one, all nonempty, for multiple. |
|
string |
Conditional |
Nonempty name-matching pattern for pattern mode. |
Successful response¶
{
"code": "OK",
"msg": "OK",
"data": {
"rows": [
{
"value": {
"id": 1
}
}
],
"next_position": {
"offset": 1
},
"has_more": false
}
}
Field |
Type |
Description |
|---|---|---|
|
string |
OK on success; also check HTTP and business codes. |
|
string |
Response information. |
|
object |
Current source result. |
|
array |
Raw JSON samples returned by the source, preserving keys, values, and format information. |
|
JSON |
Optional read position shaped by the Kafka sample result; not a pagination parameter accepted by this operation. |
|
boolean |
Whether more results exist for this sample; not import task state. |
Error response¶
Distinguish parameter, capability, authorization, and runtime-state failures using Errors and environments. Do not infer business success from HTTP 200 alone.