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

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.

Successful response

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

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.

Error response

Distinguish parameter, capability, authorization, and runtime-state failures using Errors and environments. Do not infer business success from HTTP 200 alone.

Last updated on