How to try

There are several ways to try CHYT.

The simplest way is to run a query via the Query Tracker web interface. You can use a public clique with the ch_public alias. This is the main public clique found on every cluster of CHYT's presence.

Note

In YTsaurus 24.1 and lower, a clique alias is specified with an asterisk at the beginning. For example, *ch_public. In the current version, *ch_public and ch_public are the same alias.

Attention

All YTsaurus users have access to the public clique, so there is a risk that it may not be available due to queries from other users or be occupied by other people's computations. In this regard, important processes and dashboards must not be based on a public clique. A public clique is essentially a demo version of CHYT. We highly recommend creating a separate clique for your team.

HTTP interface

A clique is accessed via heavy YTsaurus HTTP proxies. The most convenient way to access a clique is to send a query to the name of the corresponding cluster and process the redirect. When using the cURL utility, this means that you must specify the --location-trusted flag.

Below is an example of how to query a clique using the cURL command line utility, knowing the cluster name (YT_PROXY), the YTsaurus access token (YT_TOKEN), and the clique alias (CHYT_ALIAS).

$ curl --location-trusted -H "Authorization: OAuth $YT_TOKEN" "$YT_PROXY/chyt?chyt.clique_alias=$CHYT_ALIAS" -d 'SELECT Avg(a) FROM "//sys/clickhouse/sample_table"'
224.30769230769232

How to specify a clique alias

You can specify a clique alias in the special chyt.clique_alias URL parameter (see the example above) or in the user field using any of the authorization methods (information about the actual user is contained in the token). For example, http://cluster.domain.com/chyt?user=my-clique&password=my-token.

Attention

Authentication (clique alias + token) via different combinations of parameters isn't allowed. For example, the following query contains an error: -H 'X-ClickHouse-User: my-clique' 'http://cluster.domain.com/chyt?password=my-token' (the alias is specified in the X-ClickHouse-User/Key headers, and the token is specified in the user/password URL parameters)

Note

In the old version, queries use the http://$YT_PROXY/query path.

When CHYT is accessed using the deprecated /query path, the alias is passed via the database url parameter. When CHYT is accessed using the new /chyt path, the alias is taken from user or the chyt.clique_alias URL parameter.

Exclusive connection port

Not all clients support custom paths. Special ports can be configured on the HTTP Proxy to access CHYT. These ports don't require custom paths to be specified. For the numbers of dedicated ports, please contact the YTsaurus cluster administrator. The instructions on how you can configure these ports will be added in the near future.

ODBC interface

You can use CHYT from Tableau via the Clickhouse ODBC Driver.

To do this, you just need to make the ODBC configuration represented below. The YT_TOKEN variable denotes the YTsaurus access token (AQAD-qJ…), CHYT_ALIAS is the alias of the clique (ch_public), and YT_PROXY is the cluster name.

[ClickHouse]
Driver = <path to driver libclickhouseodbc>
# For example /usr/local/opt/clickhouse-odbc/lib/libclickhouseodbc.dylib
user = $CHYT_ALIAS
password = $YT_TOKEN
url = http://$YT_PROXY/chyt
port = 80
# trace = 1
# TraceFile=/tmp/odbc.log

Below is an example of how to access CHYT via the ODBC interface from the command line using the isql utility. To do this, write the ~/.odbc.ini configuration file, install the Clickhouse ODBC driver from the official repository, and use the isql utility.

isql -v clickhouse
+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+
SQL> SELECT * FROM "//tmp/sample_table"
+--+
| a|
+--+
| 2|
| 9|
| 6|
| 4|
| 8|
| 3|
| 1|
| 5|
| 7|
| 0|
+--+
SQLRowCount returns 10
10 rows fetched

JDBC interface

The JDBC driver is configured in a similar way to the ODBC driver, see the example below. The YT_TOKEN variable denotes the YTsaurus access token (AQAD-qJ…), CHYT_ALIAS is the ID/alias of the clique (ch_public), and YT_PROXY is the cluster name.

JDBC URL = jdbc:clickhouse://{host}:{port}/chyt?chyt.clique_alias={clique_alias}
host = $YT_PROXY
user = $CHYT_ALIAS
password = $YT_TOKEN
port = 80

Besides that, you need to change the driver properties:

check_for_redirects=true;
use_path_as_db=false.

The JDBC driver can be used as a basis for using DBeaver, an open-source database management program. DBeaver 6.1.5 was used for testing. If the ClickHouse-JDBC driver is not installed automatically, download it manually. You must use a driver version higher than 0.1.55.

CLI and Python API

CHYT has the official Python API and the official command line utility. For more information, see CLI and Python API.