---
title: ClickHouse Cloud
description: >-
  Connect ClickHouse Cloud to Datadog Data Observability to catalog your tables,
  track row counts and freshness, and run data quality monitors.
breadcrumbs: >-
  Docs > Data Observability Overview > Quality Monitoring > Warehouse
  Integrations > ClickHouse Cloud
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# ClickHouse Cloud

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

{% callout %}
# Important note for users on the following Datadog sites: app.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com

{% callout %}
##### Preview

Data Observability for ClickHouse Cloud is in Preview. Contact your Datadog representative to enable it for your organization.
{% /callout %}

{% /callout %}

## Overview{% #overview %}

The ClickHouse Cloud for Data Observability integration connects your [ClickHouse Cloud](https://clickhouse.com/cloud) service to Datadog Data Observability. You provide the service endpoint and credentials for a read-only user. Datadog reads metadata from your service's system tables. It uses this metadata to build a catalog of your databases, tables, and columns, and to track row count, size, and freshness for each table. You can then create data quality monitors on your ClickHouse tables.

This page covers ClickHouse Cloud services only.

**Note**: This integration is different from the [ClickHouse Cloud](https://docs.datadoghq.com/integrations/clickhouse-cloud.md) integration built by ClickHouse, which sends ClickHouse Cloud service metrics to Datadog. The ClickHouse Cloud for Data Observability integration covers the catalog, data quality metrics, and data quality monitors. You can use both integrations at the same time.

## Prerequisites{% #prerequisites %}

Before you begin, make sure you have:

- A ClickHouse Cloud service with an HTTPS endpoint. Example: `https://<service>.<region>.<cloud_provider>.clickhouse.cloud:8443`
- Administrator access to your ClickHouse Cloud service to create a role and a user.
- Preview access enabled for your organization by a Datadog representative.

## Allow Datadog IP addresses{% #allow-datadog-ip-addresses %}

Add Datadog's IP addresses to your service's IP Access List in ClickHouse Cloud. Use the addresses in the `webhooks` section of the [IP Ranges](https://docs.datadoghq.com/api/latest/ip-ranges.md) page. Without these addresses, Datadog cannot connect to your service.

{% alert level="warning" %}
IP ranges are different for each Datadog site. On the IP Ranges page, use the site selector in the top right to confirm you are fetching IPs from the correct site-specific endpoint URL.
{% /alert %}

## Create a Datadog user in ClickHouse Cloud{% #create-a-datadog-user-in-clickhouse-cloud %}

As an administrator, run the following SQL. It creates a role with read access to the system tables that hold schema and freshness metadata, grants the role access to the data you want to monitor, and creates a user with that role:

```sql
CREATE ROLE OR REPLACE DD_MONITOR;

GRANT SELECT ON system.databases TO DD_MONITOR;
GRANT SELECT ON system.tables TO DD_MONITOR;
GRANT SELECT ON system.columns TO DD_MONITOR;
GRANT SELECT ON system.parts TO DD_MONITOR;
GRANT SELECT ON information_schema.key_column_usage TO DD_MONITOR;


-- Option A: grant access to every table in a database
GRANT SELECT ON <database_name>.* TO DD_MONITOR;

-- Option B: limit access to a single table
GRANT SELECT ON <database_name>.<table_name> TO DD_MONITOR;

CREATE USER OR REPLACE datadog
IDENTIFIED BY '<password>';

GRANT DD_MONITOR TO datadog;

SET DEFAULT ROLE DD_MONITOR TO datadog;
```

Choose the grant that matches the data you want to monitor:

- `GRANT SELECT ON <database_name>.*` gives access to every table in a database.
- `GRANT SELECT ON <database_name>.<table_name>` limits access to a single table.

Replace `<database_name>`, `<table_name>`, and `<password>` with your own values. Choose a strong password and store it securely. You enter it in Datadog in the next step.

Datadog reads only metadata from ClickHouse system tables. Datadog queries the data in your tables only to run data quality monitors that you create.

## Connect your service to Datadog{% #connect-your-service-to-datadog %}

1. In Datadog, open the [ClickHouse Cloud for Data Observability integration tile](https://app.datadoghq.com/integrations/clickhouse-cloud-data-observability).

1. Enter the following:

| Parameter                  | Description                                                                                                                       |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Account name               | A name to help you identify this ClickHouse Cloud service later.                                                                  |
| ClickHouse Cloud HTTPS URL | The HTTPS URL of your ClickHouse Cloud service, for example, `https://<service>.<region>.<cloud_provider>.clickhouse.cloud:8443`. |
| Username                   | The ClickHouse user Datadog authenticates as, for example, `datadog`.                                                             |
| Password                   | The password for that ClickHouse user.                                                                                            |
| Tags                       | (Optional) Custom tags applied to datasets collected from this service.                                                           |

1. Click Save.

1. Click Test connection. If the test fails, see the Troubleshooting section.

1. Confirm the account shows as connected on the tile.

## What Datadog collects{% #what-datadog-collects %}

### Catalog{% #catalog %}

Datadog catalogs your databases, tables, and columns, including column types. ClickHouse has no schema level, so tables appear directly under their database.

### Table metrics{% #table-metrics %}

Datadog reads the following metrics for each table from ClickHouse system tables every hour:

- **Row count**: The number of rows in the table.
- **Size**: The table size in bytes.
- **Freshness**: The time of the last change to the table's data parts. Background merges and mutations also update this value, so it can change even when no new rows are inserted.

Some tables report fewer metrics:

- **Views** report freshness only, when it is available.
- **Engines with no stored row count**, such as `Distributed`, the `Log` engine family, and materialized views defined with `TO`, have no row count from metadata. To track row count for these tables, create a monitor, which counts rows with a query.
- **External and streaming engines**, such as `Kafka`, `S3Queue`, `S3`, `URL`, `MySQL`, `PostgreSQL`, and `Remote`, appear in the catalog, but only custom SQL monitors can run on them.

If your service is idle, a metadata read wakes it up, which can take a moment and uses compute in your ClickHouse Cloud service.

## Create data quality monitors{% #create-data-quality-monitors %}

ClickHouse tables support [Data Observability monitors](https://docs.datadoghq.com/monitors/types/data_observability.md), including custom SQL monitors.

- **Custom SQL**: Write the query in the ClickHouse SQL dialect. The query must alias its numeric result as `dd_value`. Other columns that the query returns become groups.
- **Schedule**: Monitors run every hour.
- **Cost**: Monitor queries run on your ClickHouse Cloud service and use its compute. A query on an idle service wakes the service up.
- **Cost control**: You control cost by choosing which monitors to create. Deleting a monitor stops its queries.

## Troubleshooting{% #troubleshooting %}

If Test connection fails, use the error to find the fix:

| Error                                          | Cause and fix                                                                                                                                                   |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid host                                   | The URL isn't the HTTPS endpoint of your service. Use `https://<service>.<region>.<cloud_provider>.clickhouse.cloud:8443`.                                      |
| Invalid credentials                            | The username or password is wrong. Check the credentials and try again.                                                                                         |
| Invalid permissions or insufficient privileges | The user doesn't have the `DD_MONITOR` grants. Run the SQL in Create a Datadog user in ClickHouse Cloud again.                                                  |
| Empty result                                   | No tables are visible to the user. Grant `SELECT` on the databases or tables you want to monitor.                                                               |
| Connection failure                             | Datadog can't reach your service. Add the `webhooks` IP ranges to your service's IP Access List, as described in Allow Datadog IP addresses, and check the URL. |
| Connection timeout                             | The service was idle and is waking up. Try again in a minute.                                                                                                   |
| Server error                                   | ClickHouse returned an error. Try again, and contact [Datadog support](https://docs.datadoghq.com/help/) if the problem persists.                               |

After a successful connection, your ClickHouse tables appear in the [Data Observability Catalog](https://app.datadoghq.com/data-obs/catalog?platform=clickhouse) after the first hourly metadata read.

If the integration tile isn't available in your organization, confirm that a Datadog representative has enabled Preview access for your organization.

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Data Observability Overview](https://docs.datadoghq.com/data_observability.md)
- [Data Observability Monitors](https://docs.datadoghq.com/monitors/types/data_observability.md)
