Title99/100
Get ClickPipe
The title clearly communicates the tool’s action and subject. Keep it concise.
Description93/100
Returns the full definition of one ClickPipe on a ClickHouse service: name, description, state, replica scaling, source settings (Kafka, object storage, Kinesis, or Postgres), destination database and table definition, field mappings, and creation and update times. If the lookup fails, result is an error object with status "error" and a message.
The description explains the capability, when to use it, and what to expect.
Inputs99/100
Input documentation gives an agent enough context to populate the arguments.
organizationId
Organization that owns the service. Use the id of an organization returned by get_organizations.
Clear enough to supply this argument.
serviceId
ClickHouse service that owns the ClickPipe. Use the id of a clickhouse-type service returned by get_services_list.
Clear enough to supply this argument.
clickPipeId
ClickPipe to retrieve. Use the id of an entry returned by list_clickpipes for the same service.
Clear enough to supply this argument.
Annotations100/100
All four behavior hints are declared.
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}Output schema95/100
The output schema explains the structured result.
View output schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"result"
],
"properties": {
"result": {
"anyOf": [
{
"type": "object",
"required": [
"id",
"serviceId",
"name",
"state",
"source",
"destination",
"createdAt",
"updatedAt"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The unique identifier of the ClickPipe"
},
"name": {
"type": "string",
"description": "The human-readable name of the ClickPipe"
},
"state": {
"type": "string",
"description": "Current operational state: \"Running\" (actively processing), \"Stopped\" (paused), \"Failed\" (error state), \"Starting\" (initializing), \"Stopping\" (shutting down)"
},
"source": {
"type": "object",
"properties": {
"kafka": {
"type": "object",
"required": [
"bootstrapServers",
"topicName"
],
"properties": {
"tls": {
"type": "object",
"required": [
"enable"
],
"properties": {
"enable": {
"type": "boolean",
"description": "Whether to enable TLS/SSL encryption for Kafka connections"
}
},
"description": "TLS/SSL encryption configuration for secure communication",
"additionalProperties": false
},
"topicName": {
"type": "string",
"description": "Name of the Kafka topic to consume from"
},
"authentication": {
"type": "object",
"required": [
"mechanism",
"username",
"password"
],
"properties": {
"password": {
"type": "string",
"description": "SASL authentication password or AWS access key"
},
"username": {
"type": "string",
"description": "SASL authentication username"
},
"mechanism": {
"enum": [
"PLAIN",
"SCRAM-SHA-256",
"SCRAM-SHA-512",
"SASL_IAM",
"SASL_SCRAM"
],
"type": "string",
"description": "SASL authentication mechanism: PLAIN (username/password), SCRAM-SHA-256 (secure challenge-response), SCRAM-SHA-512 (stronger hash), SASL_IAM (AWS IAM), SASL_SCRAM (generic SCRAM)"
}
},
"description": "SASL authentication configuration for secure Kafka access",
"additionalProperties": false
},
"schemaRegistry": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "Schema registry URL (e.g., http://schema-registry:8081)"
},
"password": {
"type": "string",
"description": "Schema registry authentication password"
},
"username": {
"type": "string",
"description": "Schema registry authentication username"
}
},
"description": "Confluent Schema Registry configuration for Avro/JSON schema validation",
"additionalProperties": false
},
"bootstrapServers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Bootstrap servers for Kafka (list of broker addresses)"
}
},
"additionalProperties": false
},
"kinesis": {
"type": "object",
"required": [
"streamName",
"region",
"roleArn"
],
"properties": {
"region": {
"type": "string",
"description": "AWS region where Kinesis stream is located (e.g., us-east-1, us-west-2, eu-west-1, ap-southeast-1)"
},
"roleArn": {
"type": "string",
"description": "IAM role ARN with permissions to read from Kinesis (format: arn:aws:iam::account:role/role-name)"
},
"streamName": {
"type": "string",
"description": "AWS Kinesis stream name (must exist in the specified region)"
}
},
"additionalProperties": false
},
"postgres": {
"type": "object",
"required": [
"host",
"port",
"database",
"username",
"password",
"tables"
],
"properties": {
"ssl": {
"type": "object",
"required": [
"enable"
],
"properties": {
"enable": {
"type": "boolean",
"description": "Whether to enable SSL/TLS encryption for PostgreSQL connection"
}
},
"description": "SSL/TLS configuration for secure database connections",
"additionalProperties": false
},
"host": {
"type": "string",
"description": "PostgreSQL server hostname or IP address"
},
"port": {
"type": "integer",
"maximum": 65535,
"minimum": 1,
"description": "PostgreSQL port number (typically 5432, range 1-65535)"
},
"tables": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of table names to replicate (e.g., [\"users\", \"orders\", \"products\"])"
},
"database": {
"type": "string",
"description": "PostgreSQL database name to connect to"
},
"password": {
"type": "string",
"description": "PostgreSQL password for authentication"
},
"username": {
"type": "string",
"description": "PostgreSQL username for authentication"
}
},
"additionalProperties": false
},
"objectStorage": {
"type": "object",
"required": [
"bucket",
"region",
"format",
"path"
],
"properties": {
"path": {
"type": "string",
"description": "Path pattern to files in bucket (supports wildcards like /data/*.json or /year=2024/month=*/)"
},
"bucket": {
"type": "string",
"description": "Storage bucket name (AWS S3 bucket, GCS bucket, or Azure container)"
},
"format": {
"type": "string",
"description": "File format: JSON (newline-delimited), CSV (comma-separated), Parquet (columnar), Avro (binary), ORC (optimized row columnar), TSV (tab-separated)"
},
"region": {
"type": "string",
"description": "Cloud storage region (e.g., us-east-1, europe-west1, eastus)"
},
"compression": {
"type": "string",
"description": "Compression algorithm: gzip, lz4, snappy, brotli, xz, zstd, or none"
}
},
"additionalProperties": false
},
"validateSamples": {
"type": "boolean",
"description": "Whether to validate data samples before processing (recommended for production)"
}
},
"description": "Data source configuration (Kafka, Object Storage, Kinesis, or PostgreSQL)",
"additionalProperties": false
},
"scaling": {
"type": "object",
"properties": {
"replicas": {
"type": "integer",
"maximum": 10,
"minimum": 1,
"description": "Number of replicas for the ClickPipe (1-10)"
}
},
"description": "Auto-scaling configuration for handling data load",
"additionalProperties": false
},
"createdAt": {
"type": "string",
"description": "Creation timestamp in ISO-8601 format (e.g., 2024-01-15T10:30:00Z)"
},
"serviceId": {
"type": "string",
"format": "uuid",
"description": "The unique identifier of the ClickHouse Cloud service"
},
"updatedAt": {
"type": "string",
"description": "Last modification timestamp in ISO-8601 format (e.g., 2024-01-15T14:20:30Z)"
},
"description": {
"type": "string",
"description": "Optional description explaining the ClickPipe purpose and data flow"
},
"destination": {
"type": "object",
"required": [
"database",
"table"
],
"properties": {
"roles": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"permissions"
],
"properties": {
"name": {
"type": "string",
"description": "ClickHouse role name for access control"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of permissions: SELECT, INSERT, CREATE, DROP, ALTER, SHOW, GRANT OPTION, or specific database/table permissions"
}
},
"additionalProperties": false
},
"description": "ClickHouse roles for access control and permissions"
},
"table": {
"type": "string",
"description": "ClickHouse destination table name (will be created if managedTable is true)"
},
"columns": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Column name (must be valid ClickHouse identifier)"
},
"type": {
"type": "string",
"description": "ClickHouse data type: String, Int32, Int64, Float32, Float64, DateTime, DateTime64, Date, UUID, Array(T), Nullable(T), LowCardinality(String), Enum8/Enum16, JSON, etc."
},
"nullable": {
"type": "boolean",
"description": "Whether column accepts NULL values (creates Nullable(T) wrapper type)"
},
"defaultValue": {
"description": "Default column value: literal values, functions like now(), or expressions"
}
},
"additionalProperties": false
},
"description": "Column definitions for table schema"
},
"database": {
"type": "string",
"description": "ClickHouse destination database name (must exist or be created)"
},
"managedTable": {
"type": "boolean",
"description": "Whether ClickPipe manages the table lifecycle (creation, schema evolution, deletion)"
},
"tableDefinition": {
"type": "object",
"required": [
"engine"
],
"properties": {
"engine": {
"type": "string",
"description": "ClickHouse table engine: MergeTree (most common), ReplacingMergeTree, SummingMergeTree, AggregatingMergeTree, CollapsingMergeTree, VersionedCollapsingMergeTree, GraphiteMergeTree, ReplicatedMergeTree variants"
},
"orderBy": {
"type": "array",
"items": {
"type": "string"
},
"description": "ORDER BY clause columns for data sorting and primary key (e.g., [\"timestamp\", \"user_id\"])"
},
"settings": {
"type": "object",
"description": "Additional table settings: index_granularity, ttl_delete_after_seconds, merge_with_ttl_timeout, etc.",
"additionalProperties": {}
},
"primaryKey": {
"type": "array",
"items": {
"type": "string"
},
"description": "PRIMARY KEY columns for efficient queries (subset of ORDER BY, e.g., [\"user_id\"])"
},
"partitionBy": {
"type": "array",
"items": {
"type": "string"
},
"description": "PARTITION BY clause for data partitioning, often by date/time (e.g., [\"toYYYYMM(timestamp)\"])"
}
},
"description": "Table structure definition for managed tables",
"additionalProperties": false
}
},
"description": "ClickHouse destination configuration including database, table, and schema",
"additionalProperties": false
},
"fieldMappings": {
"type": "array",
"items": {
"type": "object",
"required": [
"source",
"destination"
],
"properties": {
"source": {
"type": "string",
"description": "Source field name or JSONPath expression (e.g., \"user.id\", \"$.payload.timestamp\")"
},
"destination": {
"type": "string",
"description": "Destination ClickHouse column name (must match table schema)"
},
"transformation": {
"type": "string",
"description": "Optional transformation expression: type conversions (toString, toInt32), date functions (toDateTime), string functions (lower, upper), mathematical operations"
}
},
"additionalProperties": false
},
"description": "Field mapping and transformation rules from source to destination"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"status",
"message"
],
"properties": {
"status": {
"type": "string",
"const": "error",
"description": "Status indicating an error occurred"
},
"message": {
"type": "string",
"description": "Error message describing what went wrong"
}
},
"additionalProperties": false
}
]
}
},
"additionalProperties": false
}