ClickHouse é um sistema de gerenciamento de banco de dados open-source orientado a colunas para processamento analítico online (OLAP). Ele foi feito para velocidade em escala — executando agregações e consultas analíticas sobre bilhões de linhas em tempo real.
O bloco ClickHouse conecta-se a qualquer implantação do ClickHouse (ClickHouse Cloud ou self-hosted) pela interface HTTP. Use-o para executar consultas analíticas, inserir linhas em tabelas, gerenciar schemas, inspecionar o estado do sistema e executar SQL arbitrário — tudo de dentro de um fluxo de trabalho.
Detalhes da conexão
- Host — o hostname do seu ClickHouse (ex.:
your-instance.clickhouse.cloud ou o endereço do servidor).
- Port — a porta da interface HTTP. Use
8443 para HTTPS (ClickHouse Cloud) ou 8123 para HTTP simples (self-hosted).
- Database / Username — usam
default se não forem especificados.
- Password — opcional para instâncias locais sem autenticação.
- Use HTTPS — mantenha habilitado para qualquer instância remota ou Cloud.
Pontos importantes
UPDATE e DELETE são implementados como mutations do ClickHouse (ALTER TABLE ... UPDATE/DELETE). As mutations rodam de forma assíncrona em segundo plano, então a contagem de linhas afetadas não é retornada imediatamente.
- O ClickHouse é otimizado para inserts em lote. Prefira agrupar muitas linhas por insert em vez de muitos inserts de uma linha.
- O host da conexão é validado para bloquear endereços privados/internos, então o bloco não consegue acessar
localhost nem hosts apenas internos.
Integrate ClickHouse into the workflow. Query and insert data, manage databases and tables, inspect schemas, monitor mutations and running queries, manage partitions, and execute raw SQL over the ClickHouse HTTP interface.
Execute a SELECT query on a ClickHouse database
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
query | string | Yes | SQL SELECT query to execute |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of rows returned from the query |
rowCount | number | Number of rows returned |
Execute raw SQL (DDL, mutations, or queries) on a ClickHouse database
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
query | string | Yes | Raw SQL statement to execute |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of rows returned from the statement |
rowCount | number | Number of rows returned or affected |
Insert a row into a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to insert data into |
data | object | Yes | Data object to insert (key-value pairs mapping column names to values) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Inserted rows (empty for ClickHouse inserts) |
rowCount | number | Number of rows inserted |
Insert multiple rows into a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table to insert into |
rows | json | Yes | Array of row objects to insert, e.g. [{"id":1,"name":"a"},{"id":2,"name":"b"}] |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Inserted rows (empty for ClickHouse inserts) |
rowCount | number | Number of rows inserted |
Update rows in a ClickHouse table via an ALTER TABLE ... UPDATE mutation
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to update data in |
data | object | Yes | Data object with fields to update (key-value pairs) |
where | string | Yes | WHERE clause condition (without the WHERE keyword) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Updated rows (empty for ClickHouse mutations) |
rowCount | number | Number of rows written by the mutation |
Delete rows from a ClickHouse table via an ALTER TABLE ... DELETE mutation
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to delete data from |
where | string | Yes | WHERE clause condition (without the WHERE keyword) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Deleted rows (empty for ClickHouse mutations) |
rowCount | number | Number of rows affected by the mutation |
List all databases on a ClickHouse server
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | List of databases with engine and comment |
rowCount | number | Number of rows returned |
List tables in the connected ClickHouse database
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of rows returned from the query |
rowCount | number | Number of rows returned |
Describe the columns of a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to describe |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of rows returned from the query |
rowCount | number | Number of rows returned |
Get the CREATE TABLE statement (DDL) for a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to get the CREATE statement for |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
ddl | string | The CREATE TABLE statement |
Count rows in a ClickHouse table, optionally filtered
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to count rows in |
where | string | No | Optional WHERE clause condition without the WHERE keyword |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
count | number | Number of rows |
Introspect a ClickHouse database to retrieve table structures, columns, and engines
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to introspect |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
tables | array | Array of table schemas with columns and engines |
↳ name | string | Table name |
↳ database | string | Database the table belongs to |
↳ engine | string | Table engine (e.g., MergeTree, Log) |
↳ totalRows | number | Approximate total number of rows in the table |
↳ columns | array | Table columns |
↳ name | string | Column name |
↳ type | string | ClickHouse data type (e.g., UInt32, String, DateTime) |
↳ defaultKind | string | Kind of default expression (DEFAULT, MATERIALIZED, ALIAS) |
↳ defaultExpression | string | Default value expression for the column |
↳ isInPrimaryKey | boolean | Whether the column is part of the primary key |
↳ isInSortingKey | boolean | Whether the column is part of the sorting key |
Create a new database on a ClickHouse server
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
name | string | Yes | Name of the database to create |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
Drop a database from a ClickHouse server
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
name | string | Yes | Name of the database to drop |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
Create a new MergeTree-family table in ClickHouse
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Name of the table to create |
columns | json | Yes | Array of column definitions, each an object with name and type, e.g. [{"name":"id","type":"UInt64"},{"name":"ts","type":"DateTime"}] |
engine | string | No | Table engine (default MergeTree) |
orderBy | string | Yes | ORDER BY expression, e.g. "id" or "(id, ts)" |
partitionBy | string | No | Optional PARTITION BY expression, e.g. toYYYYMM(ts) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
Drop a table from a ClickHouse database
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to drop |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
Remove all rows from a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to truncate |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
Rename a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Current table name |
newTable | string | Yes | New table name |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
Trigger a merge of table parts via OPTIMIZE TABLE
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table to optimize |
final | boolean | No | Force a merge to a single part using FINAL |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
List active partitions for a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name to inspect partitions for |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of rows returned from the query |
rowCount | number | Number of rows returned |
Drop a partition from a ClickHouse table
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | Yes | Table name |
partition | string | Yes | Partition expression, e.g. '2024-01' or 202401 |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
List mutations (async ALTER UPDATE/DELETE) for the connected database
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | No | Optional table name to filter mutations |
onlyRunning | boolean | No | Only show mutations that are still running |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of mutation rows |
rowCount | number | Number of rows returned |
List currently running queries on a ClickHouse server
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of rows returned from the query |
rowCount | number | Number of rows returned |
Kill a running query by its query ID
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
queryId | string | Yes | The query_id of the running query to kill |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Kill status rows |
rowCount | number | Number of rows returned |
Get row counts and on-disk size for tables in the connected database
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
table | string | No | Optional table name to get stats for |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of table stats rows |
rowCount | number | Number of rows returned |
List configured clusters, shards, and replicas
| Parameter | Type | Required | Description |
|---|
host | string | Yes | ClickHouse server hostname (e.g., your-instance.clickhouse.cloud) |
port | number | Yes | ClickHouse HTTP interface port (8443 for HTTPS, 8123 for HTTP) |
database | string | Yes | Database name to connect to |
username | string | Yes | ClickHouse username |
password | string | No | ClickHouse password |
secure | boolean | No | Use a secure HTTPS connection (default: true) |
| Parameter | Type | Description |
|---|
message | string | Operation status message |
rows | array | Array of cluster node rows |
rowCount | number | Number of rows returned |