ClickHouse: from project to first query

ClickHouse is Zenifra's managed Analytics option for storing events and querying aggregated data. This guide follows the user journey: choose a plan, create a project, save the password, connect, and query. For transactional application data, first compare Database.

Before you begin

• Access an organization in the Console with database.create on organization:*. To view the project later, you need project.read on project:<project-id>; to view connection details, database.connection.read on database:<project-id>.
• Pick an analytics-* SKU for your capacity and topology. Compare plans before creation: Sandbox and Starter have one instance; Production and Enterprise have three replicas.
• Prepare a secure place to save the password during creation. The Console cannot retrieve the full password afterward.

Create the project

1. In the Console, choose Create project → Analytics → ClickHouse in your organization.
2. Enter a name, choose an available analytics-* SKU, version, and storage capacity using the options shown. Check the current price and included storage allowance in the Console before confirming.
3. Submit and watch the project's status until it is ready. Provisioning can take time; the initial response does not mean authenticated SQL queries are already available.
4. On the completion screen, copy the password and usable connection details to a secret manager. Do not put the password in code, messages, or screenshots. Once that screen is closed, the stored connection view is masked.
5. Under Project → Connection, copy the host, username, database, and both ports assigned to your project. The Native TLS and HTTPS/JDBC ports differ; never assume fixed numbers or exchange the ports.

If the connection view does not include the HTTPS/JDBC port, do not guess it. Check the project status and use only values shown in the Console. See Connections and clients for the right protocol.

Connect and verify

In DBeaver, select the current ClickHouse driver, use the HTTPS/JDBC port, enable SSL, and explicitly include ssl=true in the JDBC URL. With clickhouse-client, use the Native TLS port and --secure. Set the username, password, and database from your own project. The connections guide gives complete fields and examples for both clients.

Once your client is authenticated, run:

SELECT 1;
SELECT currentDatabase();

SELECT 1 verifies an authenticated query; currentDatabase() checks the active database. An endpoint responding to /ping or an open TLS port does not prove your password or SQL queries work.

Create data for a first analysis

This example uses the app database provided for new connections. If the Console shows a different database for your project, adjust the identifier before running it. These rows are illustrative; use your own data in a real application.

CREATE TABLE app.events
(
    event_time DateTime,
    event_type LowCardinality(String),
    user_id UInt64
)
ORDER BY (event_type, event_time, user_id);

INSERT INTO app.events (event_time, event_type, user_id) VALUES
    ('2026-01-01 12:00:00', 'page_view', 101),
    ('2026-01-01 12:01:00', 'signup', 101),
    ('2026-01-01 12:02:00', 'page_view', 102);

SELECT event_type, count() AS total
FROM app.events
GROUP BY event_type
ORDER BY total DESC;

In the app database, the Zenifra user has ReplicatedMergeTree as the default table engine, and DDL is replicated. The example above intentionally omits an explicit engine. On three-replica plans, explicitly choosing a non-replicated engine (such as MergeTree) changes the data availability guarantee for that table. Do not apply generic ClickHouse examples with that engine without understanding this distinction. For SQL and table engine semantics, see the official CREATE TABLE reference.

Next steps

• Choose or compare plan topologies.
• Configure DBeaver and clickhouse-client.
• Handle passwords and connection errors.