ClickHouse/clickhouse-docs-embeddings huggingface dataset:
Minimize and optimize JOINs

Note

Each algorithm has varying support for JOIN types. A full list of supported join types for each algorithm can be found [here](/docs/guides/joining-tables#choosing-a-join-algorithm).

You can let ClickHouse choose the best algorithm by setting `join_algorithm = 'auto'` (the default), or explicitly control it based on your workload. If you need to select a join algorithm to optimize for performance or memory overhead, we recommend [this guide](/docs/guides/joining-tables#choosing-a-join-algorithm).

For optimal performance:

- Keep JOINs to a minimum in high-performance workloads.
- Avoid more than 3–4 joins per query.
- Benchmark different algorithms on real data — performance varies based on JOIN key distribution and data size.

For more on JOIN optimization strategies, JOIN algorithms, and how to tune them, refer to the [ClickHouse documentation](/docs/guides/joining-tables) and this [blog series](https://clickhouse.com/blog/clickhouse-fully-supports-joins-part1).

- [When JOINs are required](#when-joins-are-required)- [Choosing the correct JOIN Algorithm](#choosing-the-right-join-algorithm)

Was this page helpful?
Accessing Iceberg data securely

## Validate access[​](#validate-access "Direct link to Validate access")

1. Run a simple query:

```
SELECT * FROM icebergS3('https://{your-bucket}.s3.{region}.amazonaws.com/{iceberg-path}/', 'NOSIGN')
LIMIT 5;
```

2. Check for IAM errors like `AccessDenied` or `InvalidAccessKeyId`.

## Troubleshooting[​](#troubelshooting "Direct link to Troubleshooting")

- Verify the role ARN from ClickHouse Cloud service settings.
- Ensure your bucket/objects are in the same region as the Iceberg queries to reduce latency and cost.
- Confirm Iceberg table path points to a valid Iceberg metadata location (`metadata/v1/...` files under the table root).
- For catalog mode, check Glue metadata and partition visibility with AWS Glue console.

- [Overview](#overview)- [Obtain the ClickHouse service role ID (ARN)](#obtaining-the-clickhouse-service-iam-role-arn)
    - [1. Login to your ClickHouse Cloud account.](#login)- [2. Select the ClickHouse service where you want to query Iceberg data.](#select-service)- [3. Go to the **Settings** tab.](#settings-tab)- [4. Scroll to **Network security information**.](#network-security-information)- [5. Copy the **Service role ID (IAM)** value.](#service-role-iam-value)- [Set up IAM assume role](#setting-up-iam-assume-role)
      - [1. Login to AWS and go to the IAM service.](#aws-iam-service)- [2. Select Roles then Create role.](#create-role)- [3. Add the Trust and IAM policies.](#add-trust-iam-policies)- [4. Finish role creation.](#finish-role-creation)- [5. Copy the new **IAM Role Arn** after creation.](#copy-role-arn)- [Configure Iceberg access in ClickHouse Cloud](#configure-iceberg-access)
        - [Option A: Iceberg table function with role ARN](#iceberg-table-function-with-role-arn)- [Option B: Persistent Iceberg table engine](#persistent-iceberg-table-engine)- [Option C: Glue catalog + IcebergS3](#glue-catalog-plus-icebergs3)- [Option D: DataLake Catalog for Glue](#datalake-catalog-for-glue)- [Validate access](#validate-access)- [Troubleshooting](#troubelshooting)

Was this page helpful?
AI/ML in ClickHouse Cloud

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/10_AI_ML/index.md)

Traditional analytics workflows often involve multiple hand offs between data engineers writing queries, analysts building dashboards, and business users interpreting results.
Each step introduces latency measured in hours or days.
ClickHouse Cloud offers the following agentic capabilities to collapse that timeline to seconds or minutes,
making it possible for a product manager to ask "What's driving the spike in churn last week?" and immediately receive not just the answer, but the underlying query, a visualization, and potential next questions to explore.

- [ClickHouse Assistant agent](/docs/cloud/features/ai-ml/ask-ai)
- [Remote MCP server](/docs/cloud/features/ai-ml/remote-mcp)

Was this page helpful?
ClickHouse Assistant agent in Cloud

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/10_AI_ML/AI_chat_overview.md)

The “ClickHouse Assistant” agent is a turn-key experience that allows users to trigger complex analysis tasks on top of the data hosted in their ClickHouse Cloud service.
Instead of writing SQL or navigating dashboards, users can describe what they're looking for in natural language.
The assistant responds with generated queries, visualizations, or summaries, and can incorporate context like active tabs, saved queries, schema details, and dashboards to improve accuracy.
It’s designed to work as an embedded assistant, helping users move quickly from questions to insights and from prompts to working dashboards or APIs.

The experience also embeds a "Docs AI" sub-agent that can be used to ask specific questions about the ClickHouse documentation straight from the console.
Instead of searching through hundreds of pages, users can ask direct questions like "How do I configure materialized views?" or "What's the difference between ReplacingMergeTree and AggregatingMergeTree?" and receive precise answers with relevant code examples and links to source documentation.

See the [guides](/docs/use-cases/AI_ML/AIChat) section for more details.

Was this page helpful?
Langfuse

[](https://static.langfuse.com/docs-videos/scores-annotation-queue.mp4)

Add custom evaluation results; supports numeric, boolean, and categorical values.

```
POST /api/public/scores
```

Add scores via Python or JS SDK.

```
langfuse.score(
  trace_id="123",
  name="my_custom_evaluator",
  value=0.5,
)
```

## Quickstarts[​](#quickstarts "Direct link to Quickstarts")

Get up and running with Langfuse in minutes. Choose the path that best fits your current needs:

- [Integrate LLM Application/Agent Tracing](https://langfuse.com/docs/observability/get-started)
- [Integrate Prompt Management](https://langfuse.com/docs/prompt-management/get-started)
- [Setup Evaluations](https://langfuse.com/docs/evaluation/overview)

## Learn more[​](#learn-more "Direct link to Learn more")

- [Langfuse Documentation](https://langfuse.com/docs)
- [Langfuse GitHub Repository](https://github.com/langfuse/langfuse)
- [Watch the Demo Video](https://langfuse.com/watch-demo)

- [What is Langfuse?](#what-is-langfuse)- [Why Langfuse?](#why-langfuse)- [Deployment options](#deployment-options)- [Architecture](#architecture)- [Features](#features)
          - [Observability](#observability)- [Prompt management](#prompt-management)- [Evaluation & datasets](#evaluation)- [Quickstarts](#quickstarts)- [Learn more](#learn-more)

Was this page helpful?
Applicable model developer terms

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/10_AI_ML/model-developer-terms.md)

This document lists models in ClickHouse Cloud that are subject to separate third-party model developer terms.
All models used are currently hosted in AWS Bedrock, and not by the applicable model developer.
These links are provided for your convenience. You are responsible for ensuring compliance with applicable model terms and any applicable use policies.

## Models and terms[​](#model-and-terms "Direct link to Models and terms")

The following is a table of models with their terms, and other pertinent information.

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Model Terms and policies|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | [Anthropic Claude Sonnet 4.5](https://www.anthropic.com/news/claude-sonnet-4-5) [Usage policy](https://www.anthropic.com/legal/aup)| [Anthropic Claude Haiku 4.5](https://www.anthropic.com/news/claude-haiku-4-5) [Usage policy](https://www.anthropic.com/legal/aup)| Anthropic Claude Sonnet 4.6 [Usage policy](https://www.anthropic.com/legal/aup)| Anthropic Claude Opus 4.6 [Usage policy](https://www.anthropic.com/legal/aup)| [Anthropic Claude Opus 4.5](https://www.anthropic.com/news/claude-opus-4-5) [Usage policy](https://www.anthropic.com/legal/aup)| [Anthropic Claude Opus 4.1](https://www.anthropic.com/news/claude-4) [Usage policy](https://www.anthropic.com/legal/aup) | | | | | | | | | | | | | |

- [Models and terms](#model-and-terms)

Was this page helpful?
Remote MCP server in Cloud

### Billing[​](#billing "Direct link to Billing")

|  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- |
| Tool Description Parameters|  |  |  | | --- | --- | --- | | `get_organization_cost` Retrieve billing and usage cost data for an organization. Returns a grand total and daily per-entity cost records. `organizationId`; optionally `from_date` and `to_date` (YYYY-MM-DD, max 31-day range) | | | | | |

## Getting started[​](#getting-started "Direct link to Getting started")

See the [setup guide](/docs/use-cases/AI/MCP/remote_mcp) for step-by-step instructions on enabling the remote MCP server and connecting it to an MCP client.

- [Remote MCP server vs open-source MCP server](#remote-vs-oss)- [Enabling the remote MCP server](#enabling)- [Endpoint](#endpoint)- [Authentication](#authentication)- [Safety](#safety)- [Available tools](#available-tools)
            - [Query and schema exploration](#query-and-schema)- [Organizations](#organizations)- [Services](#services)- [Backups](#backups)- [ClickPipes](#clickpipes)- [Billing](#billing)- [Getting started](#getting-started)

Was this page helpful?
Horizontal scaling

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/04_automatic_scaling/03_horizontal_scaling.md)

## Manual horizontal scaling[​](#manual-horizontal-scaling "Direct link to Manual horizontal scaling")

Scale plan feature

Manual horizontal scaling is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

You can use ClickHouse Cloud [public APIs](https://clickhouse.com/docs/cloud/manage/api/swagger#/paths/~1v1~1organizations~1:organizationId~1services~1:serviceId~1scaling/patch) to scale your service by updating the scaling settings for the service or adjust the number of replicas from the cloud console.

**Scale** and **Enterprise** tiers also support single-replica services. Services once scaled out, can be scaled back in to a minimum of a single replica. Note that single replica services have reduced availability and aren't recommended for production usage.

Note

Services can scale horizontally to a maximum of 20 replicas. If you need additional replicas, please contact our support team.

### Horizontal scaling via API[​](#horizontal-scaling-via-api "Direct link to Horizontal scaling via API")

To horizontally scale a cluster, issue a `PATCH` request via the API to adjust the number of replicas. The screenshots below show an API call to scale out a `3` replica cluster to `6` replicas, and the corresponding response.

*`PATCH` request to update `numReplicas`*

*Response from `PATCH` request*

If you issue a new scaling request or multiple requests in succession, while one is already in progress, the scaling service will ignore the intermediate states and converge on the final replica count.

### Horizontal scaling via UI[​](#horizontal-scaling-via-ui "Direct link to Horizontal scaling via UI")

To scale a service horizontally from the UI, you can adjust the number of replicas for the service on the **Settings** page.

*Service scaling settings from the ClickHouse Cloud console*

Once the service has scaled, the metrics dashboard in the cloud console should show the correct allocation to the service. The screenshot below shows the cluster having scaled to total memory of `96 GiB`, which is `6` replicas, each with `16 GiB` memory allocation.

- [Manual horizontal scaling](#manual-horizontal-scaling)
  - [Horizontal scaling via API](#horizontal-scaling-via-api)- [Horizontal scaling via UI](#horizontal-scaling-via-ui)

Was this page helpful?
Automatic idling

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/04_automatic_scaling/05_automatic_idling.md)

## Automatic idling[​](#automatic-idling "Direct link to Automatic idling")

In the **Settings** page, you can also choose whether or not to allow automatic idling of your service when it is inactive for a certain duration (i.e. when the service isn't executing any user-submitted queries). Automatic idling reduces the cost of your service, as you're not billed for compute resources when the service is paused.

### Adaptive Idling[​](#adaptive-idling "Direct link to Adaptive Idling")

ClickHouse Cloud implements adaptive idling to prevent disruptions while optimizing cost savings. The system evaluates several conditions before transitioning a service to idle. Adaptive idling overrides the idling duration setting when any of the below listed conditions are met:

- When the number of parts exceeds the maximum idle parts threshold (default: 10,000), the service isn't idled so that background maintenance can continue
- When there are ongoing merge operations, the service isn't idled until those merges complete to avoid interrupting critical data consolidation
- Additionally, the service also adapts idle timeouts based on server initialization time:
  - If server initialization time is less than 15 minutes, no adaptive timeout is applied and the customer-configured default idle timeout is used
  - If server initialization time is between 15 and 30 minutes, the idle timeout is set to 15 minutes
  - If server initialization time is between 30 and 60 minutes, the idle timeout is set to 30 minutes.
  - If server initialization time is more than 60 minutes, the idle timeout is set to 1 hour

Note

The service may enter an idle state where it suspends refreshes of [refreshable materialized views](/docs/materialized-view/refreshable-materialized-view), consumption from [S3Queue](/docs/engines/table-engines/integrations/s3queue), and scheduling of new merges. Existing merge operations will complete before the service transitions to the idle state. To ensure continuous operation of refreshable materialized views and S3Queue consumption, disable the idle state functionality.

When not to use automatic idling

Use automatic idling only if your use case can handle a delay before responding to queries, because when a service is paused, connections to the service will time out. Automatic idling is ideal for services that are used infrequently and where a delay can be tolerated. It isn't recommended for services that power customer-facing features that are used frequently.

- [Automatic idling](#automatic-idling)
  - [Adaptive Idling](#adaptive-idling)

Was this page helpful?
Vertical autoscaling

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/04_automatic_scaling/02_vertical_autoscaling.md)

Scale plan feature

Automatic vertical scaling is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

Scale and Enterprise tier services support autoscaling based on CPU and memory usage. Service usage is constantly monitored over a lookback window to make scaling decisions. If the usage rises above or falls below certain thresholds, the service is scaled appropriately to match the demand.

## Configuring vertical auto scaling[​](#configuring-vertical-auto-scaling "Direct link to Configuring vertical auto scaling")

The scaling of ClickHouse Cloud Scale or Enterprise services can be adjusted by organization members with the **Admin** role. To configure vertical autoscaling, go to the **Settings** tab for your service and adjust the minimum and maximum memory, along with CPU settings as shown below.

Note

Single replica services can't be scaled for all tiers.

Set the **Maximum memory** for your replicas at a higher value than the **Minimum memory**. The service will then scale as needed within those bounds. These settings are also available during the initial service creation flow. Each replica in your service will be allocated the same memory and CPU resources.

You can also choose to set these values the same, essentially "pinning" the service to a specific configuration. Doing so will immediately force scaling to the desired size you picked.

It's important to note that this will disable any auto scaling on the cluster, and your service won't be protected against increases in CPU or memory usage beyond these settings.

Note

For Enterprise tier services, standard 1:4 profiles will support vertical autoscaling. Custom profiles don’t support vertical autoscaling or manual vertical scaling. However, these services can be scaled vertically by contacting support.

- [Configuring vertical auto scaling](#configuring-vertical-auto-scaling)

Was this page helpful?
Cloud API

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/06_admin_features/api/index.md)

This section contains reference documentation for Cloud API and contains the following pages:

|  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Page Description|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | [Overview](/docs/cloud/manage/api/api-overview) Provides an overview of rate limits, Terraform Provider, Swagger (OpenAPI) Endpoint and UI and available support.|  |  |  |  | | --- | --- | --- | --- | | [Managing API Keys](/docs/cloud/manage/openapi) Learn more about Cloud's API utilizing OpenAPI that allows you to programmatically manage your account and aspects of your services.|  |  | | --- | --- | | [API Reference](https://clickhouse.com/docs/cloud/manage/api/swagger) OpenAPI (swagger) reference page. | | | | | | | |

Was this page helpful?
HyperDX

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/03_sql_console_features/hyperdx.md)

Private preview

HyperDX is the user interface for [**ClickStack**](/docs/use-cases/observability/clickstack) - a production-grade observability platform built on ClickHouse and OpenTelemetry (OTel), unifying logs, traces, metrics, and session data in a single high-performance solution. Designed for monitoring and debugging complex systems, ClickStack enables developers and SREs to trace issues end-to-end without switching between tools or manually stitching together data using timestamps or correlation IDs.

HyperDX is a purpose-built frontend for exploring and visualizing observability data, supporting both Lucene-style and SQL queries, interactive dashboards, alerting, trace exploration, and more—all optimized for ClickHouse as the backend.

HyperDX in ClickHouse Cloud allows you to enjoy a more turnkey ClickStack experience - no infrastructure to manage, no separate authentication to configure.
HyperDX can be launched with a single click and connected to your data - fully integrated into the ClickHouse Cloud authentication system for seamless, secure access to your observability insights.

## Deployment[​](#main-concepts "Direct link to Deployment")

HyperDX in ClickHouse Cloud is currently in private preview and must be enabled at the organization level. Once enabled, you will find HyperDX available in the main left navigation menu when selecting any service.

To get started with HyperDX in ClickHouse Cloud, we recommend our dedicated [getting started guide](/docs/use-cases/observability/clickstack/deployment/clickstack-clickhouse-cloud).

For further details on ClickStack, see the [full documentation](/docs/use-cases/observability/clickstack).

- [Deployment](#main-concepts)

Was this page helpful?
Managing API keys

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/features/06_admin_features/api/openapi.md)

ClickHouse Cloud provides an API utilizing OpenAPI that allows you to programmatically manage your account and aspects of your services.

Note

This document covers the ClickHouse Cloud API. For database API endpoints, please see [Cloud Endpoints API](/docs/cloud/get-started/query-endpoints)

1. You can use the **API Keys** tab on the left menu to create and manage your API keys.

2. The **API Keys** page will initially display a prompt to create your first API key as shown below. After your first key is created, you can create new keys using the `New API Key` button that appears in the top right corner.

3. To create an API key, specify the key name, permissions for the key, and expiration time, then click `Generate API Key`.

  

Note

Permissions align with ClickHouse Cloud [predefined roles](/docs/cloud/security/console-roles). The developer role has read-only permissions for assigned services and the admin role has full read and write permissions.

Query API Endpoints

To use API keys with [Query API Endpoints](/docs/cloud/get-started/query-endpoints), set Organization Role to `Member` (minimum) and grant Service Role access to `Query Endpoints`.

4. The next screen will display your Key ID and Key secret. Copy these values and put them somewhere safe, such as a vault. The values won't be displayed after you leave this screen.

5. The ClickHouse Cloud API uses [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) to verify the validity of your API keys. Here is an example of how to use your API keys to send requests to the ClickHouse Cloud API using `curl`:

```
$ KEY_ID=mykeyid
$ KEY_SECRET=mykeysecret

$ curl --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations
```

6. Returning to the **API Keys** page, you will see the key name, last four characters of the Key ID, permissions, status, expiration date, and creator. You're able to edit the key name, permissions, and expiration from this screen. Keys may also be disabled or deleted form this screen.

  

Note

Deleting an API key is a permanent action. Any services using the key will immediately lose access to ClickHouse Cloud.

## Endpoints[​](#endpoints "Direct link to Endpoints")

Refer details on endpoints, refer to the [API reference](https://clickhouse.com/docs/cloud/manage/api/swagger).
Use your API Key and API Secret with the base URL `https://api.clickhouse.cloud/v1`.

- [Endpoints](#endpoints)

Was this page helpful?