ClickHouse Interface

Tinybird is compatible with the ClickHouse® HTTP interface, enabling you to connect popular BI tools, SQL clients, and data visualization platforms directly to your Tinybird Data Sources.

This interface provides a standardized way to query your data using SQL, making it easy to integrate Tinybird with your existing analytics workflow and third-party tools.

The ClickHouse connection to Tinybird is read-only. You can use it to query, visualize, and analyze data from your Tinybird Data Sources, but you cannot modify data through this connection.

Connection parameters

To connect any ClickHouse®-compatible tool to Tinybird, use these standard connection parameters:

Basic connection settings

Protocol: HTTPS
Host: clickhouse.<REGION>.tinybird.co
Port: 443 (HTTPS)
SSL/TLS: Required (enabled)

Replace <REGION> with your workspace region (e.g., eu-west-1.aws, us-east-1).

Authentication

Username: <WORKSPACE_NAME>  # Optional, for identification purposes
Password: <TOKEN>           # Your Tinybird Auth Token

The username field is not used for authentication but helps identify the connection. The actual authentication is done via the Auth Token in the password field.

Auth Token requirements

Your Auth Token must have the following permissions:

  • Read access to Workspace Data Sources
  • Read access to Organization Data Sources (if needed)

Available databases

The ClickHouse interface exposes four databases:

  • <your_workspace_name>: Contains your Workspace's Data Sources.
  • tinybird: Contains Workspace Service Data Sources, such as tinybird.datasources_ops_log and tinybird.pipe_stats_rt.
  • organization: Contains Organization Data Sources, such as organization.workspaces and organization.pipe_stats_rt.
  • system: Contains system tables, such as system.tables and system.columns.

Compatible tools

Tinybird's ClickHouse® interface enables integration with various BI tools and SQL clients:

Business Intelligence platforms

SQL clients and IDEs

Other compatible tools

Any tool that supports ClickHouse® HTTP interface can potentially work with Tinybird, including:

  • Tableau (via its ClickHouse® connector)
  • Looker (via custom connection)
  • DataGrip and other JetBrains IDEs
  • Retool and other low-code platforms

Limitations

The interface is read-only. You cannot perform INSERT, UPDATE, DELETE, or any DDL operations (CREATE, ALTER, DROP).

Observability

Queries made through the ClickHouse® interface are logged as Query API requests in the pipe statistics Data Sources. You can monitor these queries using:

  • tinybird.pipe_stats_rt and tinybird.pipe_stats - Workspace-level statistics
  • organization.pipe_stats_rt and organization.pipe_stats - Organization-level statistics

ClickHouse® queries appear with pipe_id and pipe_name as 'query_api'. The actual SQL query is available in the parameters column under the q field.

For more details, see Service Data Sources.

Troubleshooting

Invalid host or region

Error: Connection refused

Verify your region and use the correct host format: clickhouse.<region>.tinybird.co

Authentication failures

Error: Authentication failed
  • Check your Auth Token is valid and not expired
  • Ensure the token has read permissions for the workspace
  • Verify the token is entered in the password field

SSL/TLS errors

Error: SSL connection error
  • Ensure SSL/TLS is enabled in your client
  • Use port 443 with HTTPS protocol
  • Check that your client supports TLS 1.2 or higher.

Query timeouts

Error: Query timeout
  • Add appropriate WHERE clauses to filter data
  • Use LIMIT to reduce result set size
  • Consider querying Materialized Views instead of raw data

Getting help

If you encounter issues not covered here:

  1. Check the specific tool integration guide
  2. Review your Auth Token permissions in the Tinybird UI
  3. Test the connection with a simple query
  4. Contact Tinybird support for additional assistance

Next steps

  • Choose your BI tool and follow the specific integration guide
  • Set up dashboards and visualizations with your Tinybird data
  • Explore advanced querying patterns for your use case
  • Consider creating Materialized Views for frequently accessed aggregations
Updated