Skip to content

Query API 2.11.7⚓︎

Hydrolix Query API endpoints

Contact: Hydrolix Support support@hydrolix.net

Servers⚓︎

Description URL
https://{hostname}.hydrolix.live/ https://{hostname}.hydrolix.live/

Query⚓︎

POST /query⚓︎

Query via POST

Description

Use POST as the default query mechanism for the HTTP Query API. A valid SQL query must be specified in the POST body. For example:

1
SELECT count() FROM sample.taxi_trips

You can query our test data directly from this page (use the host try3). See SQL reference for examples.

Input parameters

Parameter In Type Default Nullable Description
hdx_query_admin_comment query string No Add an admin comment to the query which is stored in active query. This field is filled automatically by Superset or Grafana to include username information in order to track users activity.
hdx_query_comment query string No Add a comment to the query which is stored in active query, this allows user to explain the query. For example if you have a query running every X min as part of a reporting tool you can include this information the comment of the query.
hdx_query_max_concurrent_partitions query integer No Hydrolix query processing generally requires each query process to extract data from many HDX partitions. This flag sets a limit on the number of partitions which a query peer reads from at the same time. Note that this setting is applied per-process. For example, if four-core query peer runs four processes, and each of these opens up to 25 partitions, then each query peer may have as many as 100 partitions open at once. Decreasing this setting from its default setting of 25 may slow down query performance. Increasing this setting beyond 25 risks excessive memory pressure on the peer. Tread carefully.
hdx_query_max_partitions query integer No Number of partition a query is allowed to access. If that number is exceeded, the query will not be allowed to run as it'll read more partition than allowed.
hdx_query_max_peers query integer No By default, Hydrolix distributes query processing across all available query peers in order to maximize massively parallel processing. Setting this flag instructs the query head to instead use only a subset of available peers. If a number greater than the number of available peers is given, all available peers are used.
hdx_query_max_timeout_sec query integer No Number of seconds before a query is canceled. A value of 0 means that there is no limit. Any other value above 0 will cancel the query when the specified number of seconds is reached.
hdx_query_max_timerange_sec query integer No Specify the maximum timerange allowed in the query, for example 86400 will limit the timerange to 1 day. If you don't have any timerange filtering in your query this options will not work as we calculate the difference between timestamp in the WHERE clause.
hdx_query_output_file_enabled query boolean No Indicates whether you want to save a query result to a file on your cloud storage. The query is saved in the format instructed by hdx_query_output_format in a randomly generated filename.
hdx_query_output_filename query string No Indicates whether you want to save a query result to a file on your cloud storage. The query is saved in the format instructed by hdx_query_output_format in the filename specified, this will overwrite the file it's already present.
hdx_query_pool_name query string No A string with a pool name can be used to instruct Hydrolix where a query should run. Given a set of pools, using the name of a given pool will run the query only in peers belonging to the pool chosen. If the parameter is not set, the query will run in all available peers from all pools by default.

Request body

1
"string"
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body 
1
2
3
4
{
    "type": "string",
    "default": "SELECT count() FROM sample.taxi_trips"
}

Response 200 OK 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "meta": [
        {
            "name": "string",
            "type": "string"
        }
    ],
    "data": "string",
    "rows": 0,
    "statistics": {
        "elapsed": 10.12,
        "rows_read": 0,
        "bytes_read": 0
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
    "required": [
        "data",
        "meta",
        "rows",
        "statistics"
    ],
    "type": "object",
    "properties": {
        "meta": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string"
                    }
                }
            }
        },
        "data": {
            "type": "string"
        },
        "rows": {
            "type": "integer"
        },
        "statistics": {
            "required": [
                "bytes_read",
                "elapsed",
                "rows_read"
            ],
            "type": "object",
            "properties": {
                "elapsed": {
                    "type": "number"
                },
                "rows_read": {
                    "type": "integer"
                },
                "bytes_read": {
                    "type": "integer"
                }
            }
        }
    }
}

Response headers

Name Description Schema
date string(date-time)
content-encoding string
content-type string
x-clickhouse-query-id Unique query identifier, supplied each time a query is executed. More information [available here](https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/) string
x-clickhouse-format The format of the response Body. More information [available here](https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/) string
x-clickhouse-timezone The time zone applied to the data. More information [available here](https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/) string
x-hdx-query-stats Statistics and information covering how the query was executed and by how many resources. More information [available here](https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/) string
traceparent A traceId. Unused. string

Response 502 Bad Gateway

GET /query⚓︎

Query via GET

Description

Using the GET Method a valid SQL query must be specified in query parameter query=SQL statement. For example:

1
SELECT count() FROM sample.taxi_trips

You can query our test data directly from this page (use the host try3). See SQL reference for examples.

Input parameters

Parameter In Type Default Nullable Description
hdx_query_admin_comment query string No Add an admin comment to the query which is stored in active query. This field is filled automatically by Superset or Grafana to include username information in order to track users activity.
hdx_query_comment query string No Add a comment to the query which is stored in active query, this allows user to explain the query. For example if you have a query running every X min as part of a reporting tool you can include this information the comment of the query.
hdx_query_max_concurrent_partitions query integer No Hydrolix query processing generally requires each query process to extract data from many HDX partitions. This flag sets a limit on the number of partitions which a query peer reads from at the same time. Note that this setting is applied per-process. For example, if four-core query peer runs four processes, and each of these opens up to 25 partitions, then each query peer may have as many as 100 partitions open at once. Decreasing this setting from its default setting of 25 may slow down query performance. Increasing this setting beyond 25 risks excessive memory pressure on the peer. Tread carefully.
hdx_query_max_partitions query integer No Number of partition a query is allowed to access. If that number is exceeded, the query will not be allowed to run as it'll read more partition than allowed.
hdx_query_max_peers query integer No By default, Hydrolix distributes query processing across all available query peers in order to maximize massively parallel processing. Setting this flag instructs the query head to instead use only a subset of available peers. If a number greater than the number of available peers is given, all available peers are used.
hdx_query_max_timeout_sec query integer No Number of seconds before a query is canceled. A value of 0 means that there is no limit. Any other value above 0 will cancel the query when the specified number of seconds is reached.
hdx_query_max_timerange_sec query integer No Specify the maximum timerange allowed in the query, for example 86400 will limit the timerange to 1 day. If you don't have any timerange filtering in your query this options will not work as we calculate the difference between timestamp in the WHERE clause.
hdx_query_output_file_enabled query boolean No Indicates whether you want to save a query result to a file on your cloud storage. The query is saved in the format instructed by hdx_query_output_format in a randomly generated filename.
hdx_query_output_filename query string No Indicates whether you want to save a query result to a file on your cloud storage. The query is saved in the format instructed by hdx_query_output_format in the filename specified, this will overwrite the file it's already present.
hdx_query_pool_name query string No A string with a pool name can be used to instruct Hydrolix where a query should run. Given a set of pools, using the name of a given pool will run the query only in peers belonging to the pool chosen. If the parameter is not set, the query will run in all available peers from all pools by default.

Response 200 OK 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "meta": [
        {
            "name": "string",
            "type": "string"
        }
    ],
    "data": "string",
    "rows": 0,
    "statistics": {
        "elapsed": 10.12,
        "rows_read": 0,
        "bytes_read": 0
    }
}
⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
{
    "required": [
        "data",
        "meta",
        "rows",
        "statistics"
    ],
    "type": "object",
    "properties": {
        "meta": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string"
                    }
                }
            }
        },
        "data": {
            "type": "string"
        },
        "rows": {
            "type": "integer"
        },
        "statistics": {
            "required": [
                "bytes_read",
                "elapsed",
                "rows_read"
            ],
            "type": "object",
            "properties": {
                "elapsed": {
                    "type": "number"
                },
                "rows_read": {
                    "type": "integer"
                },
                "bytes_read": {
                    "type": "integer"
                }
            }
        }
    }
}

Response headers

Name Description Schema
date string(date-time)
content-encoding string
content-type string
x-clickhouse-query-id Unique query identifier, supplied each time a query is executed. More information [available here](https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/) string
x-clickhouse-format The format of the response Body. More information [available here](https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/) string
x-clickhouse-timezone The time zone applied to the data. More information [available here](https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/) string
x-hdx-query-stats Statistics and information covering how the query was executed and by how many resources. More information [available here]()https://docs.hydrolix.io/latest/exploring-data/query-troubleshooting/query-http-response-headers/ string
traceparent A traceId. Unused. string

Response 502 Bad Gateway