Skip to main content

Query API Endpoints

Beta feature. Learn more.

The Query API Endpoints feature allows you to create an API endpoint directly from any saved SQL query in the ClickHouse Cloud console. You'll be able to access API endpoints via HTTP to execute your saved queries without needing to connect to your ClickHouse Cloud service via a native driver.

Before proceeding, ensure you have an API key. You can follow this guide to create an API key.

Creating a saved query​

If you have a saved query, you can skip this step.

Open a new query tab. For demonstration purposes, we'll use the youtube dataset, which contains approximately 4.5 billion records. As an example query, we'll return the top 10 uploaders by average views per video in a user-inputted year parameter:

with sum(view_count) as view_sum,
    round(view_sum / num_uploads, 2) as per_upload
select
    uploader,
    count() as num_uploads,
    formatReadableQuantity(view_sum) as total_views,
    formatReadableQuantity(per_upload) as views_per_video
from
    youtube
where
    toYear(upload_date) = {year: UInt16}
group by uploader
order by per_upload desc
limit 10

Note that this query contains a parameter (year). The SQL console query editor automatically detects ClickHouse query parameter expressions and provides an input for each parameter. Let's quickly run this query to make sure that it works:

Test the example query

Next step, we'll go ahead and save the query:

Save example query

More documentation around saved queries can be found here.

Configuring the Query API Endpoint​

Query API endpoints can be configured directly from query view by clicking the Share button and selecting API Endpoint. You'll be prompted to specify which API key(s) should be able to access the endpoint:

Configure query endpoint

After selecting an API key, the query API endpoint will automatically be provisioned. An example curl command will be displayed so you can send a test request:

Endpoint curl command

Query API parameters​

Query parameters in a query can be specified with the syntax {parameter_name: type}. These parameters will be automatically detected and the example request payload will contain a queryVariables object through which you can pass these parameters.

Testing and monitoring​

Once a Query API endpoint is created, you can test that it works by using curl or any other HTTP client:

endpoint curl test

After you've sent your first request, a new button should appear immediately to the right of the Share button. Clicking it will open a flyout containing monitoring data about the query:

Endpoint monitoring