Cluster Explorer Guide

Working directly with a ClickHouse cluster

The Altinity Cloud Manager UI provides the Cluster Explorer, a panel that lets you run queries against your ClickHouse databases, work with database schemas, look at processes running inside the cluster, and use a number of useful DBA tools.

If you’re looking for help on a particular aspect of the Cluster Explorer, you can skip ahead to any of the tasks:

  • The Query tab - Run queries against your data, create tables, delete data…anything you can do with a SQL statement.
  • The Schema tab - Look at the details of tables within your databases.
  • The Workload tab - See what’s happening in the system now, including running queries, replications, and mutations.
  • The DBA Tools tab - Use system-level tools to investigate errors, check for schema consistency errors, rebalance storage across your cluster’s disks, and look at detached parts.
  • Importing a dataset - Load large, publicly available datasets into your ClickHouse cluster.

Panel buttons and menus

The top of every tab looks like this:

Menus and buttons in the Cluster Explorer

Figure 1 - Cluster Explorer menus and buttons

The functions of the buttons and menus are:

  • - The back button. Takes you back to the cluster view for this cluster.
  • CLUSTER menu - Clicking this menu displays a dropdown list of all of the clusters in this environment. Whatever you do in the Cluster Explorer will be done on the selected cluster.
    The Cluster menu
  • RUN DDLs ON CLUSTER - If selected, Distributed DDL Queries are run on the cluster.
  • NODE menu - Lets you select the scope of anything you do in the Cluster Explorer. For the maddie-byok cluster, the menu looks like this:
    Menus and buttons in the Cluster Explorer
    Selecting Any means everything you do will be executed on a single node selected by the load balancer. All executes everything on every node. Beyond those two choices, you can select a node from the list of all nodes in this cluster.
  • - lets you import a sample dataset into your ClickHouse cluster. See Importing a dataset below.
  • - The refresh button. Refreshes the display, as you would expect.

The Query tab

When you open the Cluster Explorer, you’ll be on the Query tab:

Query Page

Figure 2 - The Query tab

The text area at the top of the panel lets you run SQL statements by clicking the EXECUTE button. (You can also keep your hands on the keyboard by typing Ctrl or CMD + Enter.)

Beneath the text area are helpful notes with links to ClickHouse documentation and a couple of example queries.

When you execute a query, the results appear under the text area:

Query results

Figure 3 - Query results

Above the text area, the left and right arrows let you move through the queries you’ve executed. The button brings up the Select User dialog:

The Select User dialog

Figure 4 - Changing the user to access the cluster

This lets you select the user (and their permissions) to run the query. The down arrow lets you choose from the users defined for this cluster. If your account has the necessary permissions, you can also click the link in Manage ClickHouse users here to go directly to the user management panel.

The Schema tab

The Schema tab lets you view the databases and tables in your cluster. You can then select a table and see its details.

The schema tab

Figure 5 - The Schema tab

You can click the Show system tables checkbox to see the system tables as well. All of the table names are links. You can also click the filter icon to show only the tables that match a particular value. This example filters the display to show only tables from the mindsdb database:

Filtering databases on a particular valueb

Figure 6 - Filtering to tables from a single database

You can create as many filters as you want; you could add a filter to the display in Figure 6 to show only tables in the mindsdb database with a MaterializedView engine.

When you’re ready to see more details on a particular table, click on a table name to see the Table Details dialog, which has four subtabs:

The Table Description tab

The Table Description tab has a table of the table’s properties. There are dozens of them, some of which are shown here:

Table description column

Figure 7 - The Table Description tab

The Table Schema tab

The Table Schema tab displays the table’s schema via the CREATE statement that created it:

Table schema column

Figure 8 - The Table Schema tab

Click the Copy to Clipboard link to put the schema on the clipboard.

The Sample Rows tab

The Sample Rows tab shows randomly selected rows from the table:

Sample rows column

Figure 9 - The Sample Rows tab

The Column Compression tab

Finally, the Column Compression tab shows the details of the columns in the table and how much they have been compressed:

Column compression column

Figure 10 - The Column Compression tab

The key_flags data indicates whether a given column is the partition key, the primary key, the sorting key, and/or the sampling key.

The Workload tab

The Workload tab shows you what’s happening in the system now:

Workloads page

Figure 11 - The Workload tab

It has four subtabs:

The Running Queries tab

The Running Queries tab shows the details of all the currently running queries:

Currently running queries

Figure 12 - The Running Queries tab

Selecting one or more queries activates the button. Be aware that not all queries can be killed; if you’d like to know more, see the Altinity Knowledge Base article on killing queries.

The Query Stats tab

The Query Stats tab gives you insight on how your queries are performing:

Query stats tab

Figure 13 - The Query Stats tab

Statistics include the average run time for a query, the maximum run time for a query, the average memory used, and how many bytes were read or written for a query. You can see statistics for queries across different time frames (an hour, a day, a week, or a month).

Clicking on an individual query displays a long list of details for that query, such as its status, when it was run, how long it took to execute, and how many bytes and rows were read and written. Here are a few of those details:

Query detail

Figure 14 - Details of a query

The Replication Queue tab

The Replication Queue tab displays any replications that are in progress:

Replication Queue tab

Figure 15 - The Replication Queue tab

Statistics include the database and table involved for each replication, details about exceptions, postponed replications, and the number of times a replication was tried.

The Mutations tab

The Mutations tab displays information about mutations (ALTER TABLE commands), with the option to display details for any completed mutations:

Mutations tab

Figure 16 - The Mutations tab

For each mutation, the display includes information about the host, database, and table being mutated, the command used, and any failures, along with other useful data.

Selecting one or more mutations activates the button.

See the ClickHouse documentation for more details on the ALTER TABLE command.

The DBA Tools tab

DBA Tools page

Figure 17 - The DBA Tools tab

It has five subtabs:

The Errors tab

The Errors tab, as you would expect, displays any errors that have occurred:

Errors tab

Figure 18 - The Errors tab

Details include the last time an error occurred, how many times it has occurred, and the error message.

The Schema Consistency tab

The Schema Consistency tab displays any schema consistency issues. Hopefully you have no issues and see this:

Schema Consistency tab

Figure 19 - The Schema Consistency tab

The Disks Balance tab

The Disks Balance tab has two tabs itself: The Distribution tab, which shows all of the disks in your ClickHouse cluster and how much free space is available on each, and the Rebalance tab, which lets you rebalance your data among your cluster’s disks.

The Distribution tab displays a graph of your disks and how much free space is available on each:

Disks Balance Distribution tab

Figure 20 - The Rebalance subtab of the Disks Balance tab

The Rebalance tab lets you, well, rebalance your data:

Disks Balance Rebalance tab

Figure 21 - The Rebalance subtab of the Disks Balance tab

Clicking the button rebalances the cluster’s disks. You should only rebalance your disks if you’ve gotten an alert that one of your disks is nearly full and you have at least one disk with plenty of space. Note that the ACM will not rebalance your disks if none of them have significant free space, and it will not rebalance the disks unless a significant amount of storage is involved.

The Detached Parts tab

The Detached Parts tab displays any detached parts in your ClickHouse cluster.

Detached Parts tab

Figure 22 - The Detached Parts tab

Selecting one or more parts activates the button.

See the Altinity Knowledge Base article on Detached Parts for more information.

The Crashes tab

The Crashes tab displays the details of any crash that may have occurred:

Crashes tab

Figure 23 - The Crashes tab

[ClickHouse rarely crashes, so we don’t have an example to show here.]

Importing a dataset

The Cluster Explorer makes it easy to import a sample dataset. When you click the button, you’ll see this dialog:

Select a dataset to import

Figure 24 - The Import Dataset wizard

Select the dataset you want and click NEXT. Next you’ll be asked about the database schema:

Use the database schema

Figure 25 - The Schema tab of the Import Dataset wizard

In this example, three tables will be created when you click the button: central_park_weather_observations, taxi_zones, and tripdata. You can expand each of the entries to look at the CREATE statement and change the engine parameters if you want. Clicking the button restores the original statement.

Click to import the data:

Importing the dataset

Figure 26 - Tracking dataset import progress

Clicking the Processes tab link takes you to the Running Queries tab.