Skip to content
M↓ View as Markdown ↗

ClickHouse

Connect a ClickHouse database, including ClickHouse Cloud, to Actian AI Analyst so you can build Models on its tables and let your AI Analysts query them. AI Analyst connects over the ClickHouse HTTP interface and browses data as database → table.

Availability

  • Who can do this: members with the Edit capability in the active Workspace. If your organization turns on Restrict connection management, you also need the Manage organization capability.
  • Plan: available unless your organization's plan excludes the ClickHouse connector.
  • Deployment: Actian SaaS and self-managed deployments, unless the deployment's operator has turned the ClickHouse connector off.

Read-only access

AI Analyst runs every ClickHouse query with the readonly=1 setting, so ClickHouse refuses writes for that session. Still, give AI Analyst a user that can only read the data you want to analyze. See Read-only access.

1. Create a read-only user in ClickHouse

Create a dedicated ClickHouse user for AI Analyst:

-- Replace with your chosen username and a secure password
CREATE USER analyst_user IDENTIFIED BY '<your_secure_password>';

2. Grant read access to data

Grant the user SELECT access to the databases AI Analyst should analyze:

-- Grant SELECT on all tables in a specific database
GRANT SELECT ON your_database.* TO analyst_user;

Repeat for each database. For finer control, grant access per table:

GRANT SELECT ON your_database.orders TO analyst_user;
GRANT SELECT ON your_database.customers TO analyst_user;

AI Analyst can only query what this user can access.

3. Allow network access

If your ClickHouse server is protected by a firewall or an IP access list, allow the IP addresses that AI Analyst connects from on your ClickHouse HTTP or HTTPS port (8123 or 8443 by default):

  • Actian SaaS: when your deployment publishes its addresses, the Setup help panel next to the connection form lists them under Which IPs to allow.
  • Self-managed deployment: AI Analyst connects from your own installation's network. Allow its outbound addresses, or ask whoever operates your installation.

If no addresses are listed, or you allowed an address from an earlier version of these docs, see Network access.

Note

If the host is a private network address, Studio shows This looks like a local address. You can still save the connection, but AI Analyst can only connect if its servers can reach that network, for example through a VPN, peering or an allowlist.

4. Set up the connection in AI Analyst

  1. In Studio, open Connections and click the plus button (Add connection).
  2. Under Warehouses, select ClickHouse.
  3. Under Connection details, enter a Name and, optionally, a Description. Select Private to this Workspace if only the current Workspace should use the connection. See Connections and Workspaces.
  4. Under Credentials, fill in:
    • Host: your ClickHouse server hostname without protocol, such as your-instance.clickhouse.cloud.
    • Port: 8123 by default (HTTP). Use 8443 for HTTPS, or your instance's custom port.
    • Database: the default database AI Analyst connects to.
    • Username: analyst_user.
    • Password: the password you set.
    • SSL mode: Disable (default, HTTP) or Require (HTTPS).
  5. Click Test connection.
  6. When the test succeeds, select the databases to expose under Schemas.
  7. Click Save connection.

ClickHouse Cloud users

AI Analyst does not switch on SSL or change the port for you. For ClickHouse Cloud, set SSL mode to Require and Port to 8443, or paste an https:// connection string that includes the port (:8443), as described below.

Note

  • Save connection stays unavailable until the test passes. A successful test is valid for five minutes, and changing a connection field resets it. If either happens, test again.
  • The password is encrypted at rest and never shown again after you save.

Paste a connection string

Instead of typing each field, you can click Paste a connection string, paste a URL, and click Fill the form. For example:

https://<user>:<password>@<host>.clickhouse.cloud:8443/<database>

AI Analyst fills Host, Port, Database, Username and Password. Include the port in the URL. Without it, Port stays at 8123. A URL that starts with https:// sets SSL mode to Require, and http:// sets it to Disable. Nothing is sent until you test the connection.

Troubleshooting

When a test fails, the form shows a short summary, such as Authentication failed or Could not reach the warehouse. Expand it to see the error that ClickHouse returned.

Symptom Likely cause What to do
The test fails or times out against ClickHouse Cloud SSL mode is Disable or Port is 8123. Set SSL mode to Require and Port to 8443.
The test fails with a network error A firewall or IP access list blocks AI Analyst, or the host or port is wrong. Review step 3 and check Host and Port.
The test fails with an authentication error Wrong username or password. Check the credentials.
A database is missing from Schemas The user has no SELECT grant on that database. Grant access as in step 2, then test again.

For connections that already exist, see Manage connections and Data source health monitoring.

Next steps

Create Models on the tables you want to analyze (see Creating models) and add them to an AI Analyst (see Models).