Skip to main content

Connect to an external ClickHouse database

ClickHouse is a high-performance, column-oriented database system. It allows for fast ingestion of data and is optimized for analytical queries.

LangSmith uses ClickHouse as the primary data store for traces and feedback. By default, self-hosted LangSmith will use an internal ClickHouse database that is bundled with the LangSmith instance. This is run as a stateful set in the same Kubernetes cluster as the LangSmith application or as a Docker container on the same host as the LangSmith application.

However, you can configure LangSmith to use an external ClickHouse database for easier management and scaling. By configuring an external ClickHouse database, you can manage backups, scaling, and other operational tasks for your database. While Clickhouse is not yet a native service in Azure, AWS, or Google Cloud, you can run LangSmith with an external ClickHouse database in the following ways:

note

Using the first two options (LangSmith-managed ClickHouse or ClickHouse Cloud) will provision a Clickhouse service OUTSIDE of your VPC. However, both options support private endpoints, meaning that you can direct traffic to the ClickHouse service without exposing it to the public internet (eg via AWS PrivateLink, or GCP Private Service Connect).

Additionally, sensitive information can be configured to be not stored in Clickhouse. Please reach out to support@langchain.dev for more information.

Requirements​

  • A provisioned ClickHouse instance that your LangSmith application will have network access to (see above for options).
  • A user with admin access to the ClickHouse database. This user will be used to create the necessary tables, indexes, and views.
  • We support both standalone ClickHouse and externally managed clustered deployments. For clustered deployments, ensure all nodes are running the same version. Note that clustered setups are not supported with bundled ClickHouse installations.
  • We only support ClickHouse versions >= 23.9. Use of ClickHouse versions >= 24.2 requires LangSmith v0.6 or later. See the LangSmith release notes for more information.

LangSmith-managed ClickHouse​

  • If using LangSmith-managed ClickHouse, you will need to set up a VPC peering connection between the LangSmith VPC and the ClickHouse VPC. Please reach out to support@langchain.dev for more information.
  • You will also need to set up Blob Storage. You can read more about Blob Storage in the Blob Storage documentation.
note

ClickHouse installations managed by LangSmith use a SharedMerge engine, which automatically clusters them and separates compute from storage.

Parameters​

You will need to provide several parameters to your LangSmith installation to configure an external ClickHouse database. These parameters include:

  • Host: The hostname or IP address of the ClickHouse database
  • HTTP Port: The port that the ClickHouse database listens on for HTTP connections
  • Native Port: The port that the ClickHouse database listens on for native connections
  • Database: The name of the ClickHouse database that LangSmith should use
  • Username: The username to use to connect to the ClickHouse database
  • Password: The password to use to connect to the ClickHouse database
  • Cluster (Optional): The name of the ClickHouse cluster if using an external Clickhouse cluster. When set, LangSmith will run migrations on the cluster and replicate data across instances.

Configuration​

With these parameters in hand, you can configure your LangSmith instance to use the provisioned ClickHouse database. You can do this by modifying the config.yaml file for your LangSmith Helm Chart installation or the .env file for your Docker installation.


clickhouse:
  external:
    enabled: true
    host: "host"
    port: "http port"
    nativePort: "native port"
    user: "default"
    password: "password"
    database: "default"
    tls: false
    cluster: "my_cluster_name"  # Optional: Set this if using an external Clickhouse cluster

Once configured, you should be able to reinstall your LangSmith instance. If everything is configured correctly, your LangSmith instance should now be using your external ClickHouse database.

note

Important considerations for clustered deployments:

  • Clustered setups must be configured on a fresh schema - existing standalone ClickHouse instances cannot be converted to clustered mode.
  • Clustering is only supported with externally managed ClickHouse deployments. It is not compatible with bundled ClickHouse installations as these do not include required ZooKeeper configurations.
  • When using a clustered deployment, LangSmith will automatically:
    • Run database migrations across all nodes in the cluster
    • Configure tables for data replication across the cluster

Note that while data is replicated across nodes, LangSmith does not configure distributed tables or handle query routing - queries will be directed to the specified host. You will need to handle any load balancing or query distribution at the infrastructure level if desired.

Was this page helpful?


You can leave detailed feedback on GitHub.