ClickHouse connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'clickhouse'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize ClickHouse:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'clickhouse_get_organizations',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "clickhouse"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize ClickHouse:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="clickhouse_get_organizations",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Run SELECT queries — execute read-only SQL queries against any ClickHouse service and retrieve results directly in your agent
• Explore schema — list databases, tables, and column types to understand your data model before writing queries
• Manage services — list, inspect, and get full details for ClickHouse Cloud services (clusters) in an organization
• Monitor backups — list service backups, get backup details, and retrieve the backup schedule and retention config
• Inspect ClickPipes — list and retrieve data ingestion pipeline status and configuration
• Track costs — get billing and usage cost data for an organization over a custom date range

Common workflows

Get your service ID

Every ClickHouse tool requires a serviceId. Fetch it first by listing the services in your organization.

Node.js

const orgs = await actions.executeTool({
  toolName: 'clickhouse_get_organizations',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {},
});
const orgId = orgs.data?.result?.[0]?.id;

const services = await actions.executeTool({
  toolName: 'clickhouse_get_services_list',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: { organizationId: orgId },
});
const serviceId = services.data?.result?.[0]?.id;
console.log('Service ID:', serviceId);

Python

orgs = actions.execute_tool(
    tool_name="clickhouse_get_organizations",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={},
)
org_id = orgs.data["result"][0]["id"]

services = actions.execute_tool(
    tool_name="clickhouse_get_services_list",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={"organizationId": org_id},
)
service_id = services.data["result"][0]["id"]
print("Service ID:", service_id)

Explore schema before querying

List databases and tables to understand the data model before writing queries.

Node.js

// List databases
const dbs = await actions.executeTool({
  toolName: 'clickhouse_list_databases',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: { serviceId: '<your-service-id>' },
});

// List tables in a database
const tables = await actions.executeTool({
  toolName: 'clickhouse_list_tables',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    serviceId: '<your-service-id>',
    database: 'default',
  },
});
console.log(tables.data?.result);

Python

# List databases
dbs = actions.execute_tool(
    tool_name="clickhouse_list_databases",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={"serviceId": "<your-service-id>"},
)

# List tables in a database
tables = actions.execute_tool(
    tool_name="clickhouse_list_tables",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "serviceId": "<your-service-id>",
        "database": "default",
    },
)
print(tables.data["result"])

Run a SELECT query

Execute read-only SQL against your ClickHouse service. Only SELECT statements are permitted.

Node.js

const result = await actions.executeTool({
  toolName: 'clickhouse_run_select_query',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    serviceId: '<your-service-id>',
    query: 'SELECT event, count() AS cnt FROM events GROUP BY event ORDER BY cnt DESC LIMIT 10',
    timeoutSeconds: 30,
  },
});
console.log(result.data?.result);

Python

result = actions.execute_tool(
    tool_name="clickhouse_run_select_query",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "serviceId": "<your-service-id>",
        "query": "SELECT event, count() AS cnt FROM events GROUP BY event ORDER BY cnt DESC LIMIT 10",
        "timeoutSeconds": 30,
    },
)
print(result.data["result"])

Only SELECT is allowed

clickhouse_run_select_query rejects INSERT, UPDATE, DELETE, and DDL statements. Use it for read-only data retrieval and analytics.

Check organization costs

Retrieve billing and usage data for a ClickHouse Cloud organization over a date range (max 31 days per request).

Node.js

const costs = await actions.executeTool({
  toolName: 'clickhouse_get_organization_cost',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    organizationId: '<your-org-id>',
    from_date: '2025-01-01',
    to_date: '2025-01-31',
  },
});
console.log(costs.data?.result);

Python

costs = actions.execute_tool(
    tool_name="clickhouse_get_organization_cost",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "organizationId": "<your-org-id>",
        "from_date": "2025-01-01",
        "to_date": "2025-01-31",
    },
)
print(costs.data["result"])

List and inspect ClickPipes

ClickPipes are managed data ingestion pipelines. List all pipelines for a service and get detailed status for a specific one.

Node.js

const pipes = await actions.executeTool({
  toolName: 'clickhouse_list_clickpipes',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    organizationId: '<your-org-id>',
    serviceId: '<your-service-id>',
  },
});

const pipeId = pipes.data?.result?.[0]?.id;
const pipe = await actions.executeTool({
  toolName: 'clickhouse_get_clickpipe',
  connectionName: 'clickhouse',
  identifier: 'user_123',
  toolInput: {
    organizationId: '<your-org-id>',
    serviceId: '<your-service-id>',
    clickPipeId: pipeId,
  },
});
console.log(pipe.data?.result);

Python

pipes = actions.execute_tool(
    tool_name="clickhouse_list_clickpipes",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "organizationId": "<your-org-id>",
        "serviceId": "<your-service-id>",
    },
)
pipe_id = pipes.data["result"][0]["id"]

pipe = actions.execute_tool(
    tool_name="clickhouse_get_clickpipe",
    connection_name="clickhouse",
    identifier="user_123",
    tool_input={
        "organizationId": "<your-org-id>",
        "serviceId": "<your-service-id>",
        "clickPipeId": pipe_id,
    },
)
print(pipe.data["result"])

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

clickhouse_get_clickpipe # Get configuration and status for a specific ClickPipe by ID. 3 params ▾

Get configuration and status for a specific ClickPipe by ID.

Name Type Required Description

clickPipeId string required ID of the requested ClickPipe

organizationId string required ID of the organization that owns the service

serviceId string required ID of the service that owns the ClickPipe

clickhouse_get_organization_cost # Get billing and usage cost data for an organization over a date range (max 31 days). Returns a grand total and daily per-entity cost breakdown. 3 params ▾

Get billing and usage cost data for an organization over a date range (max 31 days). Returns a grand total and daily per-entity cost breakdown.

Name Type Required Description

organizationId string required The unique identifier of the organization

from_date string optional Start date for the report, e.g. 2024-12-19 (YYYY-MM-DD)

to_date string optional End date (inclusive) for the report, e.g. 2024-12-20 (YYYY-MM-DD). Cannot be more than 30 days after from_date.

clickhouse_get_organization_details # Get details for a specific ClickHouse Cloud organization: name, tier, status, and settings. Use get_organizations to find the organizationId. 1 param ▾

Get details for a specific ClickHouse Cloud organization: name, tier, status, and settings. Use get_organizations to find the organizationId.

Name Type Required Description

organizationId string required ID of the organization to retrieve

clickhouse_get_organizations # List all ClickHouse Cloud organizations accessible with the current API key. Returns organization IDs and names. Use the returned organizationId with all other tools. 0 params ▾

List all ClickHouse Cloud organizations accessible with the current API key. Returns organization IDs and names. Use the returned organizationId with all other tools.

clickhouse_get_service_backup_configuration # Get the backup schedule and retention configuration for a service. 2 params ▾

Get the backup schedule and retention configuration for a service.

Name Type Required Description

organizationId string required ID of the organization that owns the service

serviceId string required ID of the service

clickhouse_get_service_backup_details # Get details for a specific backup: status, size, duration, and creation time. 3 params ▾

Get details for a specific backup: status, size, duration, and creation time.

Name Type Required Description

backupId string required ID of the backup

organizationId string required ID of the organization that owns the service

serviceId string required ID of the service

clickhouse_get_service_details # Get full details for a specific service: status, region, tier, endpoints, and scaling configuration. 2 params ▾

Get full details for a specific service: status, region, tier, endpoints, and scaling configuration.

Name Type Required Description

organizationId string required ID of the organization

serviceId string required ID of the service to retrieve

clickhouse_get_services_list # List all services (clusters) in a ClickHouse Cloud organization. Returns service IDs, names, status, region, and tier. Use the returned serviceId with other tools. 1 param ▾

List all services (clusters) in a ClickHouse Cloud organization. Returns service IDs, names, status, region, and tier. Use the returned serviceId with other tools.

Name Type Required Description

organizationId string required ID of the organization whose services are to be listed

clickhouse_list_clickpipes # List all ClickPipes (managed data ingestion pipelines) configured for a service. 2 params ▾

List all ClickPipes (managed data ingestion pipelines) configured for a service.

Name Type Required Description

organizationId string required ID of the organization

serviceId string required ID of the service to list ClickPipes for

clickhouse_list_databases # List all databases in a ClickHouse service. Use the returned database names with list_tables and run_select_query. 1 param ▾

List all databases in a ClickHouse service. Use the returned database names with list_tables and run_select_query.

Name Type Required Description

serviceId string required The unique identifier of the ClickHouse service

clickhouse_list_service_backups # List all backups for a service, most recent first. Returns backup IDs, status, size, and timestamps. 2 params ▾

List all backups for a service, most recent first. Returns backup IDs, status, size, and timestamps.

Name Type Required Description

organizationId string required ID of the organization

serviceId string required ID of the service to list backups for

clickhouse_list_tables # List all tables in a database, including column names and types. Supports LIKE pattern filtering. 4 params ▾

List all tables in a database, including column names and types. Supports LIKE pattern filtering.

Name Type Required Description

database string required Name of the database to list tables from

serviceId string required The unique identifier of the ClickHouse service

like string optional Optional SQL LIKE pattern to filter tables by name (e.g., "events_%")

notLike string optional Optional SQL LIKE pattern to exclude tables by name

clickhouse_run_select_query # Execute a read-only SELECT query against a ClickHouse service. Only SELECT statements are permitted. 3 params ▾

Execute a read-only SELECT query against a ClickHouse service. Only SELECT statements are permitted.

Name Type Required Description

query string required A valid ClickHouse SELECT query. Only read-only SELECT statements are permitted. e.g. SELECT * FROM my_table LIMIT 10

serviceId string required The unique identifier of the ClickHouse service

timeoutSeconds integer optional Query timeout in seconds. Default: 300 (5 min), max: 3600 (1 hour). Use lower values for simple queries.