> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Holistics is an AI-powered platform for self-service BI and embedded analytics that helps everyone make better decisions with governed, easily accessible metrics.

# Connecting ClickHouse to Holistics

export const CommunityMaintainedBadge = () => {
  return <div className="CommunityMaintainedBadge">
            <div className="CommunityMaintainedIcon">
            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 256 256">
                <path d="M244.8,150.4a8,8,0,0,1-11.2-1.6A51.6,51.6,0,0,0,192,128a8,8,0,0,1-7.37-4.89,8,8,0,0,1,0-6.22A8,8,0,0,1,192,112a24,24,0,1,0-23.24-30,8,8,0,1,1-15.5-4A40,40,0,1,1,219,117.51a67.94,67.94,0,0,1,27.43,21.68A8,8,0,0,1,244.8,150.4ZM190.92,212a8,8,0,1,1-13.84,8,57,57,0,0,0-98.16,0,8,8,0,1,1-13.84-8,72.06,72.06,0,0,1,33.74-29.92,48,48,0,1,1,58.36,0A72.06,72.06,0,0,1,190.92,212ZM128,176a32,32,0,1,0-32-32A32,32,0,0,0,128,176ZM72,120a8,8,0,0,0-8-8A24,24,0,1,1,87.24,82a8,8,0,1,0,15.5-4A40,40,0,1,0,37,117.51,67.94,67.94,0,0,0,9.6,139.19a8,8,0,1,0,12.8,9.61A51.6,51.6,0,0,1,64,128,8,8,0,0,0,72,120Z"></path>
            </svg>
        </div>
            Community Maintained
        </div>;
};

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

[Holistics](https://www.holistics.io/) is an AI-native self-service BI platform with a programmable semantic layer for consistent, trustworthy metrics.

By connecting ClickHouse to Holistics, your teams get a fast, reliable AI-powered self-service experience grounded in a code-based semantic layer. Business users can explore data confidently with drag-and-drop and AI, while you keep metric definitions reusable, composable, and version-controlled in Git.

<h2 id="prerequisites">
  Prerequisites
</h2>

Before connecting, ensure you have the following:

* **Permissions:** You must be an Admin in Holistics to add new Data Sources.
* **Network Access:** Your ClickHouse server must be accessible from [Holistics' IP addresses](https://docs.holistics.io/docs/connect/ip-whitelisting).
* **Database User:** Create a dedicated, read-only user for Holistics rather than using an admin account.

<h3 id="recommended-privileges">
  Recommended privileges
</h3>

The dedicated user requires `SELECT` privileges on the tables you wish to query, as well as the `system` tables (for schema detection).

```sql theme={null}
-- Example: Grant read access to a specific database
GRANT SELECT ON my_database.* TO holistics_user;

-- Grant access to system metadata
GRANT SELECT ON system.* TO holistics_user;
```

<Steps>
  <Step title="Gather connection details" id="step-1-gather-connection-details">
    To connect to ClickHouse with HTTP(S) you will need this information:

    | **Parameter**     | **Description**                                                                           |
    | ----------------- | ----------------------------------------------------------------------------------------- |
    | **Host**          | The hostname of your ClickHouse server (e.g., `mz322.eu-central-1.aws.clickhouse.cloud`). |
    | **Port**          | **8443** for ClickHouse Cloud (SSL/TLS). **8123** for self-managed instances without SSL. |
    | **Database Name** | The name of the database you want to connect to. The default is usually `default`.        |
    | **Username**      | The database user. The default is `default`.                                              |
    | **Password**      | The password for the database user.                                                       |

    You can find these details by clicking the **Connect** button in your ClickHouse Cloud console and selecting **HTTPS**.

    <Image size="md" img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/jCcMIFRXeNsMw8EN/images/integrations/data-visualization/holistics_01.webp?fit=max&auto=format&n=jCcMIFRXeNsMw8EN&q=85&s=df80837406c7ce921f86c0ac2ea81e4b" alt="Location of the Connect button in the ClickHouse Cloud console" border width="998" height="932" data-path="images/integrations/data-visualization/holistics_01.webp" />
  </Step>

  <Step title="Configure network access" id="step-2-configure-network-access">
    Since Holistics is a cloud-based application, its servers must be able to reach your database. You have two options:

    1. **Direct Connection (Recommended):** Allowlist Holistics' IP addresses in your firewall or ClickHouse Cloud IP Access List. You can find the list of IPs in the [IP Whitelisting guide](https://docs.holistics.io/docs/connect/ip-whitelisting).

           <Image size="md" img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/jCcMIFRXeNsMw8EN/images/integrations/data-visualization/holistics_02.webp?fit=max&auto=format&n=jCcMIFRXeNsMw8EN&q=85&s=0aae0156890fc8fe13adb66f5f1f7e01" alt="Example of IP allowlisting in ClickHouse Cloud" border width="1651" height="1131" data-path="images/integrations/data-visualization/holistics_02.webp" />

    2. **Reverse SSH Tunnel:** If your database is in a private network (VPC) and can't be exposed publicly, use a [Reverse SSH Tunnel](https://docs.holistics.io/docs/connect/connect-tunnel).
  </Step>

  <Step title="Add data source in Holistics" id="step-3-add-data-source-in-holistics">
    1. In Holistics, go to **Settings → Data Sources**.

           <Image size="md" img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/jCcMIFRXeNsMw8EN/images/integrations/data-visualization/holistics_03.webp?fit=max&auto=format&n=jCcMIFRXeNsMw8EN&q=85&s=8e858767b5dbe28a470ce1b551511197" alt="Navigating to Data Sources in Holistics settings" border width="1647" height="1129" data-path="images/integrations/data-visualization/holistics_03.webp" />

    2. Click **New Data Source** and select **ClickHouse**.

           <Image size="md" img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/jCcMIFRXeNsMw8EN/images/integrations/data-visualization/holistics_04.webp?fit=max&auto=format&n=jCcMIFRXeNsMw8EN&q=85&s=b1d3f80724325165c97d1575c98b62b9" alt="Selecting ClickHouse from the list of new data sources" border width="1651" height="1131" data-path="images/integrations/data-visualization/holistics_04.webp" />

    3. Fill in the form with the details gathered in Step 1.

       | **Field**         | **Setting**                                                       |
       | ----------------- | ----------------------------------------------------------------- |
       | **Host**          | Your ClickHouse Hostname                                          |
       | **Port**          | `8443` (or `8123`)                                                |
       | **Require SSL**   | Toggle **ON** if using port 8443 (Required for ClickHouse Cloud). |
       | **Database Name** | `default` (or your specific DB)                                   |

           <Image size="md" img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/jCcMIFRXeNsMw8EN/images/integrations/data-visualization/holistics_05.webp?fit=max&auto=format&n=jCcMIFRXeNsMw8EN&q=85&s=fe3fa336abe98f6b5a0c7840b91fbde4" alt="Filling in ClickHouse connection details in Holistics" border width="1651" height="1131" data-path="images/integrations/data-visualization/holistics_05.webp" />

    4. Click **Test Connection**.

           <Image size="md" img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/jCcMIFRXeNsMw8EN/images/integrations/data-visualization/holistics_06.webp?fit=max&auto=format&n=jCcMIFRXeNsMw8EN&q=85&s=8645ac03ad0c7120731f97f2080cc216" alt="Successful ClickHouse connection test in Holistics" border width="1651" height="1131" data-path="images/integrations/data-visualization/holistics_06.webp" />

       * **Success:** Click **Save**.
       * **Failure:** Check your username/password and ensure the [Holistics IPs are allowlisted](https://docs.holistics.io/docs/connect/ip-whitelisting).
  </Step>
</Steps>

<h2 id="known-limitations">
  Known limitations
</h2>

Holistics supports most standard SQL features in ClickHouse, with the following exceptions:

* **Running Total:** This analytic function currently has limited support on ClickHouse.
* **Nested Data Types:** Deeply nested JSON or Array structures may require flattening via SQL models before visualization.

For a full list of supported features, please refer to the [Database-specific Limitations page](https://docs.holistics.io/docs/connect/faqs/clickhouse-limitations).