> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/clickhouse.md).

# Clickhouse

Configuring the Veza integration for ClickHouse.

### Overview

ClickHouse is a high-performance columnar database management system (DBMS) optimized for Online Analytical Processing (OLAP). The Veza integration for ClickHouse Cloud enables discovery of users, roles, and services configured for your organization, providing visibility into what human and non-human identities have permissions on ClickHouse data and settings.

### Prerequisites

* A ClickHouse Cloud account
* Administrator access to create API keys in ClickHouse
* A Developer API key with permissions to read organization metadata
* Note: The integration currently supports connecting to a single organization only

### Configuring the Veza integration for ClickHouse

#### Retrieve a ClickHouse API Key

1. In the ClickHouse Cloud Console, select **API Keys** from the left menu.

   ![Choose API Keys on the navigation menu.](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-91143c9b33dfef12292a7cdfe3a94a9fa3f510ab%2Fclickhouse-menu.png?alt=media)
2. Click **New API Key** in the top-right corner. For new accounts, you'll see a prompt to create your first key. ![Add a ClickHouse API key.](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-feb66821c4829aa95ea5c9f9959a49f1ca0bc3ce%2Fclickhouse-new-api-key.png?alt=media)
3. Configure the API key:
   * Enter a descriptive **Key Name**
   * For **Organization Permissions**, select **Developer**
   * Set an appropriate **expiration time**
4. Click **Generate API Key**

   ![API Key Creation Form](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-0ff6bb03767d4abe778c2676964d353543240f62%2Fclickhouse-create-api-key.png?alt=media)
5. Copy and securely store both the **Key ID** and **Key Secret**. These values cannot be retrieved after leaving this page. ![API Key Details](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-1d5aa8f52dbb06727690a1f367ab89b6cc1cc2ef%2Fclickhouse-api-key-details.png?alt=media)

#### Add the ClickHouse Integration to Veza

1. Browse to your Veza instance
2. In the left navigation, choose **Integrations**
3. Click **Add Integration** and select **ClickHouse**
4. Enter the following values:
   * **Client ID**: The Key ID from your ClickHouse API key
   * **Client Secret**: The Key Secret from your ClickHouse API key
5. Click **Create Integration** to save your changes

### Notes and Supported Entities

#### Organization Level Properties

The integration captures organization-level metadata for a ClickHouse Cloud deployment. Note that the integration currently supports connecting to a single organization only.

| Veza Field Name     | Description                                        | Property Type               |
| ------------------- | -------------------------------------------------- | --------------------------- |
| `organization_id`   | Unique identifier for your ClickHouse organization | Application Custom Property |
| `organization_name` | Display name of your ClickHouse organization       | Application Custom Property |
| `created_at`        | Organization creation timestamp in ISO-8601 format | Application Custom Property |

#### Users

Users represent members of your ClickHouse organization who can access and manage services. Each user is assigned either an Admin or Developer role, which determines their access to services and organization settings.

| Veza Field Name | Description                                             | Property Type      |
| --------------- | ------------------------------------------------------- | ------------------ |
| `id`            | The user's unique identifier                            | LocalUser Property |
| `name`          | User's display name                                     | LocalUser Property |
| `email`         | User's email address                                    | LocalUser Property |
| `created_at`    | When the user joined the organization (ISO-8601 format) | LocalUser Property |

**Role Assignment:**

* Users with role "admin" are assigned the Admin role with full access to all services
* All other users are automatically assigned the Developer role with selective service access

#### Services

Services represent individual ClickHouse database instances within your organization. Each service represents a deployable database with specific configuration options across cloud providers and regions.

| Veza Field Name | Description                                                | Property Type           |
| --------------- | ---------------------------------------------------------- | ----------------------- |
| `id`            | Unique identifier for the service                          | Resource ID             |
| `name`          | Display name of the service                                | Resource Name           |
| `provider`      | Cloud provider where service is deployed (aws, gcp, azure) | CustomResource Property |
| `region`        | Cloud region where service is deployed                     | CustomResource Property |
| `state`         | Current operational state of the service                   | CustomResource Property |
| `tier`          | Service tier determining scaling capabilities              | CustomResource Property |
| `is_primary`    | Whether this is the primary service                        | CustomResource Property |
| `created_at`    | Service creation timestamp (ISO-8601 format)               | CustomResource Property |

**Service Tiers:**

* `development`: Fixed-size instances with limited scaling (not available on Azure)
* `production`: Fully scalable instances
* `dedicated_high_mem`: Memory-optimized instances
* `dedicated_high_cpu`: Compute-optimized instances

#### Roles

ClickHouse uses a role-based access control (RBAC) system with two predefined roles:

* **Admin**: Full administrative access to all services and organization settings
* **Developer**: Limited access focused on service usage and monitoring

#### Permissions

The integration maps ClickHouse system permissions to standardized Veza permission types. These mappings include:

**Service Management:**

* `View service`: `DataRead`, `MetadataRead`
* `Create service`: `DataCreate`, `MetadataCreate`
* `Delete service`: `DataDelete`, `MetadataDelete`
* `Stop service`: `DataWrite`, `MetadataWrite`
* `Restart service`: `DataWrite`, `MetadataWrite`
* `Reset service password`: `DataWrite`, `MetadataWrite`
* `View service metrics`: `DataRead`, `MetadataRead`

**Access Management:**

* `View API key records`: `DataRead`, `MetadataRead`
* `Create API key`: `DataCreate`, `MetadataCreate`
* `Delete API key`: `DataDelete`, `MetadataDelete`
* `View users`: `DataRead`, `MetadataRead`
* `Invite users`: `DataCreate`, `MetadataCreate`
* `Change user role`: `DataWrite`, `MetadataWrite`
* `Delete users`: `DataDelete`, `MetadataDelete`

**Organization Management:**

* `View billing`: `DataRead`, `MetadataRead`
* `Manage billing`: `DataRead`, `DataWrite`, `DataCreate`, `DataDelete`, `MetadataRead`, `MetadataWrite`, `MetadataCreate`, `MetadataDelete`
* `View organization activity`: `DataRead`, `MetadataRead`
* `Submit support requests`: `DataCreate`, `MetadataCreate`
* `View integrations`: `DataRead`, `MetadataRead`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/integrations/integrations/clickhouse.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.