Connect ClickHouse

Beta

Experimentation is in beta.

Instead of the managed Flagsmith warehouse, you can store experiment events in your own ClickHouse instance. It must be reachable from Flagsmith: on Flagsmith Cloud, over the internet; when self-hosting, from your Flagsmith API and warehouse delivery.

1. Configure your instance by running the following against it, using an administrative user (the statements require CREATE USER, GRANT, CREATE DATABASE and CREATE TABLE privileges). Replace <USER> and <YOUR_PASSWORD> with your own values. This is a one-off setup step; the same SQL is available to copy from the Flagsmith dashboard.

   -- ClickHouse schema for experimentation events.
   CREATE DATABASE IF NOT EXISTS flagsmith_exp;
   
   CREATE TABLE IF NOT EXISTS flagsmith_exp.events
   (
       environment_key      LowCardinality(String),
       event                LowCardinality(String),
       feature_name         LowCardinality(String),
       timestamp            DateTime64(3),
       collected_at         DateTime64(3),
       identifier           String,
       value                String                          CODEC(ZSTD(3)),
       traits               String                          CODEC(ZSTD(3)),
       metadata             String                          CODEC(ZSTD(3)),
       sdk_language         LowCardinality(String),
       sdk_version          LowCardinality(String),
   
       INDEX idx_identity identifier TYPE bloom_filter GRANULARITY 4,
   
       CONSTRAINT environment_key_not_empty CHECK environment_key != '',
       CONSTRAINT event_not_empty           CHECK event != '',
       CONSTRAINT timestamp_sane            CHECK timestamp > toDateTime64('2020-01-01 00:00:00', 3)
   )
   ENGINE = MergeTree
   PARTITION BY toYYYYMMDD(timestamp)
   ORDER BY (environment_key, event, feature_name, timestamp, identifier);

   -- Create a dedicated user for Flagsmith
   CREATE USER IF NOT EXISTS <USER>
       IDENTIFIED WITH sha256_password BY '<YOUR_PASSWORD>';
   
   -- Allow it to write and read experiment events
   GRANT SELECT, INSERT ON flagsmith_exp.events TO <USER>;
   
   -- Allow it to check the events table exists
   GRANT SHOW TABLES, SHOW COLUMNS ON flagsmith_exp.* TO <USER>;

2. Go to Environment Settings › Warehouse, select ClickHouse and enter your connection details: host, HTTPS port (8443 by default), database (flagsmith_exp by default), and the username and password of the user you created in step 1.

3. Click Test connection. Once the test succeeds, save the connection.

4. On Flagsmith Cloud, click Send your first event on the connection card to verify events are arriving in your warehouse; the button disappears once the first event is received.

Connections use the ClickHouse HTTP(S) interface, with TLS enabled by default.

Experiment results and exposures are computed from your ClickHouse instance.