Query Interfaces

Query interfaces supported

Hydrolix provides multiple query interfaces for interoperability with

HTTP Query API
ClickHouse HTTP
ClickHouse native
MySQL

Client applications

The following pages demonstrate client applications using Hydrolix cluster interfaces.

ClickHouse client uses the ClickHouse native protocol
DBeaver depends on the ClickHouse HTTP interface
JDBC Driver uses the Hydrolix query API
Python Library uses the ClickHouse native protocol
Splunk with Hydrolix Search uses a new hdxsearch Splunk Query Language command
Splunk with DB Connect uses the ClickHouse HTTP interface
MySQL Client uses the MySQL protocol
Apache Spark Connector reads Hydrolix data files directly (and depends on the Configuration API)

Other applications not listed above may be compatible with one (or more) of the supported, published interfaces available from Hydrolix clusters.

Authentication

The HTTP query API and ClickHouse HTTP interfaces support both JWT bearer token-based and username/password-based query authentication.

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:

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"
)

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

The ClickHouse native and MySQL interfaces support the username/password authentication mechanism.

HTTP query API

Each cluster runs the Hydrolix HTTP query API. The API endpoint is https://{myhost}.hydrolix.live/query.

We recommend the POST endpoint, although there is also a GET endpoint.

HTTP query API example

$ printf "%s\n" "SELECT COUNT(*) FROM hydro.logs WHERE timestamp > NOW() - INTERVAL 1 HOUR;" \
  | curl -X POST \
      --data-binary @- \
      --header "Authorization: Bearer ${JWT_ACCESS_TOKEN}" \
      https://{myhost}.hydrolix.live/query
2354732

Hydrolix UI

The Hydrolix UI running on your cluster allows direct interaction with the query system from a browser. The Hydrolix UI depends on the HTTP Query API. This environment is good for exploration, but isn't well-suited for result sets larger than 10,000 rows. For this, use alternative clients or 3rd Party Integrations query system from a browser.

Hydrolix UI query example

The UI is available by directly connecting to the cluster over the standard HTTPS port, tcp/443 at https://{myhost}.hydrolix.live/.

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.

ClickHouse HTTP query example

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

ClickHouse native

The Native interface supports any clients or client libraries capable of the ClickHouse native protocol. Use tunable disable_traefik_native_port to turn off the server.

Example ClickHouse native connection

$ clickhouse-client -h {myhost}.hydrolix.live --port 9440 -u '[email protected]' -s
ClickHouse client version 25.3.2.39 (official build).
Connecting to {myhost}.hydrolix.live:9440 as user [email protected].
Password for user ([email protected]): 
Connecting to {myhost}.hydrolix.live:9440 as user [email protected].
Connected to ClickHouse server version 24.8.6.

ClickHouse server version is older than ClickHouse client. It may indicate that the server is out of date and can be upgraded.

query-peer :)

📘
Hydrolix ClickHouse engine versioning
Your ClickHouse client may report server version mismatch. The Hydrolix fork of the ClickHouse engine follows upstream, so isn't synchronized.

MySQL

The MySQL interface supports any clients or client libraries capable of MySQL protocol. Use tunable disable_traefik_mysql_port to turn off the server.