Skip to content

ClickHouse HTTP

Each cluster runs the ClickHouse HTTP query interface on port 8088. Use tunable disable_traefik_clickhouse_http_port to turn off the server.

Clients may authenticate with credentials or present an authorization token.

Present an authorization token⚓︎

Get the bearer token, which is good for the next 24 hours, to authenticate future API calls. This command assumes you've set the $HDX_HOSTNAME, $HDX_USER and $HDX_PASSWORD environment variables:

1
2
3
4
5
6
7
8
export HDX_TOKEN=$(
  curl -v -X POST -H "Content-Type: application/json" \
  https://$HDX_HOSTNAME/config/v1/login/ \
  -d "{
    \"username\":\"$HDX_USER\",
    \"password\":\"$HDX_PASSWORD\"  
  }" | jq -r ".auth_token.access_token"
)

ClickHouse HTTP query example⚓︎

If the token is valid, the ClickHouse HTTP server returns an HTTP 200 and the response.

1
2
3
4
5
$ printf "%s\n" "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;" \
  | curl --data-binary @- \
      --header "Authorization: Bearer $HDX_TOKEN" \
      https://{myhost}.hydrolix.live:8088/
2136727

If the token is invalid, the ClickHouse HTTP server returns an HTTP 401 and the following error.

1
2
3
4
{
    "error": "Code: 516. DB::Exception: : Authentication failed: password is incorrect, or there is no user with such name.\n\nIf you have installed ClickHouse and forgot password you can reset it in the configuration file.\nThe password for default user is typically located at /etc/clickhouse-server/users.d/default-password.xml\nand deleting this file will reset the password.\nSee also /etc/clickhouse-server/users.xml on the server where ClickHouse is installed.\n\n. (AUTHENTICATION_FAILED)",
    "query": "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;\n"
}

If the token is empty, the ClickHouse HTTP server returns an HTTP 401 and the following error.

1
2
3
4
{
    "error": "std::exception. Code: 1001, type: h::db::ContextError, e.what() = <ContextError no authentication token provided> (version 24.8.6.1)",
    "query": "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;\n"
}

Authenticate with credentials⚓︎

Local user accounts can authenticate with credentials.

If the credentials are valid, the ClickHouse HTTP server returns an HTTP 200 and the response.

1
2
3
4
5
6
$ printf "%s\n" "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;" \
  | curl \
         --user "${HDX_USERNAME}:${HDX_PASSWORD}" \
         --data-binary @- \
      https://{myhost}.hydrolix.live:8088/
2136727

If the credentials are invalid, the ClickHouse HTTP server returns an HTTP 400 and the following error.

1
2
3
4
{
    "error": "<TurbineApiAuthenticatorError api login failed with provided username/password 'username@example.com'. <HttpPermanentResponseError error=request_failed status_code=401 path=/config/v1/login {\"detail\":\"Could not login\"}>>",
    "query": "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;\n"
}

Learn more on the Enable Query Authentication, User Authentication, and Configure IP Access pages.