Quick Start Guide

• 1: Altinity Cloud Manager Introduction
• 2: Account Creation and Login
• 3: Launch Cluster Wizard
• 4: The Cluster Explorer

1 - Altinity Cloud Manager Introduction

Overview - Altinity Cloud Manager

This section introduces the Altinity Cloud Manager for managing ClickHouse cluster environments. The Altinity Cloud Manager (ACM) is where your existing clusters are shown.

Points of interest marked by the red pins include:

• The your.environment name is what you signed up with, otherwise a cluster name appears hear in this menu.
• The John Doe is an example of your logged-in name.
• The left pane collapses or expands the text labels beside the icons.
• The Launch Cluster text tag refers to the call-to-action LAUNCH CLUSTER button.

Figure 1 – The Altinity Cloud Manager (ACM) home screen with no clusters showing.

Looking at the Demo

To switch to the demo environment:

1. Use the environment menu to switch to demo to see the clusters.

Figure 2 – The environment menu, where the demo name is selected.

The demo environment has several example clusters:

• posthog
• clickhouse101
• meetup
• github

Panel View

To see the detail for the cluster named clickhouse101:

1. In the cluster named clickhouse101, hover over pane, the outline turns blue, then click .

Figure 3 – The demo environment showing several cluster panels.

List View

The list view provides a spreadsheet table view of your clusters.

1. Select the List View icon.

Figure 4 – The list view of all the demo clusters.

Cluster Dashboard view

Selecting a cluster name from a panel view or list view displays the settings that were set by the Cluster Launch Wizard.

Figure 5 – Detailed settings view of the cluster clickhouse101.

Explore View

While viewing your cluster, selecting the Explore button displays the Query screen. This is where SQL queries are run on your cluster. Note the additional tabs for Schema, Workload and DBA Tools.

Figure 6 – The cluster Query tab screen. This is where SQL queries are run.

Grafana Monitoring View

From your cluster dashboard view, selecting the Monitoring View in Grafana link displays the graphs shown in the following screenshot.

Figure 7 – The Grafana graphs for the K8S Namespace demo, for the cluster named clickhouse101.

A Wizard-Created Cluster

When you create a new cluster using the LAUNCH CLUSTER Wizard, the new cluster appears in the Altinity Cloud Manager (ACM):

Figure 8 – Points of interest from the newly created cluster

From the Clusters view you can see the newly created cluster, maddie-ch. It was marked as a development cluster (as opposed to a production cluster), its infrastructure is healthy (the green “2/2 nodes online” bar), TLS is enabled (the green shield), and the cluster itself is healthy (the green “6/6 tests passed” bar).

2 - Account Creation and Login

There are two ways you can create an Altinity.Cloud account:

• Create a free trial account
• Sign up for an AWS Marketplace subscription

We’ll cover both of those here.

Create a free trial Altinity.Cloud account

To start your Altinity.Cloud journey, the first thing you need is an account. New users can sign up for a 14-day Altinity.Cloud trial account on the trial request page.

NOTE: You must use a corporate email address to register for an account. Addresses such as *@gmail.com or *@yahoo.com are not accepted.

You’ll get an email to verify your email address. Be sure to check your spam folder if you don’t get an email shortly.

Once you verify your email, your request for the Altinity.Cloud free trial will be processed for approval. If approved, you’ll get an email from the Altinity.Cloud team (support@altinity.com). In that email, click the “Get Started” link. You’ll be asked to create a password for your new account.

With your new password defined, you’ll be taken to the ACM login screen:

You can log in with your email and password, or click the Auth0 link at the bottom to login through Google. The email address you use with Auth0 must be the same one you used when you signed up for the trial account.

Once you’re logged in, you’re ready to get started!

Sign up for an AWS Marketplace subscription

Altinity.Cloud for ClickHouse is listed in AWS Marketplace for AWS customers to simplify software licensing, procurement, control and governance.

You can subscribe to the Altinity.Cloud through the AWS Marketplace and get billed through the AWS billing system for the Altinity.Cloud services.

To use Altinity.Cloud services through AWS Marketplace subscription you need to:

1. Subscribe to Altinity.Cloud for ClickHouse in the AWS Marketplace
2. Register your new account on the registration form.

Search for Altinity.Cloud for ClickHouse in AWS Marketplace and click the View purchase options button:

You’ll be redirected to the Subscribe page. Click the Subscribe button to purchase Altinity.Cloud for ClickHouse:

On the top of the Subscribe page, click the Set up your account button to start the Altinity.Cloud registration process.

You’ll be redirected to altinity.com. Click the CONTINUE button to continue:

Fill out the registration form and click SUBMIT:

Once you verify your email, you’ll get an email from the Altinity.Cloud team (support@altinity.com). In that email, click the “Get Started” link. You’ll be asked to create a password for your new account.

With your new password defined, you’ll be taken to the ACM login screen:

You can log in with your email and password, or click the Auth0 link at the bottom to login through Google. The email address you use with Auth0 must be the same one you used when you signed up for your AWS subscription.

Once you’re logged in, you’re ready to get started!

If you have any issues with registration or your subscription, please contact the Altinity.Cloud support team.

3 - Launch Cluster Wizard

This section covers the Altinity Cloud Manager Launch Cluster Wizard.

Launch Cluster

The Altinity Cloud Manager (ACM) is where your existing ClickHouse clusters are shown. If you don’t have any clusters, you’ll see “You don’t have any clusters running at this moment.”

Points of interest marked by the red pins in Figure 2 include:

• Your environment name and username are displayed at the top of the screen.
• The left pane collapses or expands the text labels beside the icons.

Click LAUNCH CLUSTER to get started.

Figure 1 – The ACM Clusters page

1. ClickHouse Setup

The first tab in the wizard is the ClickHouse Setup tab.

Figure 2 – The ClickHouse Setup tab

Field details

Name

Enter a name for your new cluster. The name will become part of a URL once the cluster is deployed, so it must follow these rules:

• It must begin with a lowercase letter [a-z]
• It can only contain lowercase letters [a-z], numbers [0-9], and hyphens
• It must end with either a letter or a number
• It can’t be more than 15 characters long.

ClickHouse Version

Select the version of ClickHouse you want your cluster to use. You can click the down arrow to see a list of available versions. ALTINITY BUILDS is selected by default; that lets you choose which Altinity Stable Build you want to use. You can also click COMMUNITY BUILDS to see other versions of ClickHouse.

Beneath the ClickHouse version is a link to the release notes for the build you’ve selected. The release notes have extensive details of what is new and changed and fixed in each release. Click the link to open the release notes in a new browser tab.

ClickHouse User Name

Currently this is admin and can’t be changed.

ClickHouse User Password

Enter and confirm a password at least 12 characters long. NOTE: The Next button is disabled until the password is at least 12 characters long and the two passwords match.

NOTE: If the only node types available aren’t capable of running a ClickHouse cluster, you’ll see an error message:

Figure 3 - “CPU type can’t run ClickHouse” error

If you see this error, you’ll need to change the capacities of your Altinity.Cloud environment. Contact Altinity Support for help.

Click NEXT to continue.

2. Resources Configuration

With the basics of your ClickHouse cluster defined, it’s time to give it some CPUs and storage.

Figure 4 – The Resources Configuration tab

Field details

Node Type

Click the down arrow to see what machine types are available. Each item in the list will tell you how many CPUs and how much RAM that machine type has.

Node Storage

The amount of storage in GB that each ClickHouse host will have. If the environment doesn’t have enough resources to meet your requirements, the graphs of CPU and Storage usage will turn red. You can reduce the amount of storage each ClickHouse node will have. If that’s not an option, contact Altinity Support.

Volume Type

Click the down arrow to see what classes of storage are available for your ClickHouse clusters.

Number of Shards

Enter the number of shards you want for your ClickHouse cluster. The graphs of CPU and Storage usage will be updated as you change the number of shards.

Cluster Role

This can be Not set, Development, or Production. These are simply labels applied to your ClickHouse clusters; they can make it easier manage your clusters. It’s perfectly fine to leave this as Not set.

Click NEXT to continue.

3. High Availability Configuration

This tab covers server redundancy and failover.

Figure 5 – The High Availability Configuration tab

Field details

Number of Replicas

Select 1, 2, or 3. The CPU and Storage graphs will update as you change the number of replicas.

Availability Zones

Select which availability zones you want to use. NOTE: It is highly recommended that you use at least two availability zones.

Zookeeper Configuration

Currently the only available option is Dedicated.

Backup Schedule

The default schedule is to do a backup daily at 5:00 AM and to keep seven backups. You can click the ADD SETTING button to define another schedule.

Click NEXT to continue.

4. Connection Configuration

Next you need to define your ClickHouse cluster’s connections to the outside world.

Figure 6 – The Connection Configuration tab

Field details

Endpoint

This is the endpoint of your cluster. Notice that the value here is the cluster name you defined in the first tab combined with an Altinity domain.

Alternate Endpoints

You can define alternate endpoints for your cluster. The name of the alternate endpoint can contain lowercase letters, numbers, and hyphens. It must start with a letter, and it cannot end with a hyphen.

Figure 7 – Defining an Alternate Endpoint

For example, you might want an endpoint that uses your organization’s domain, such as cluster.environment.example.com instead of cluster.environment.altinity.cloud. You might also want to create an alternate endpoint and use it as the ClickHouse access point in your applications. With that approach, pointing the alternate endpoint to another cluster lets you switch the cluster your applications are using without changing the applications at all.

Contact Altinity support to set up an alternate endpoint.

Use TLS

We strongly recommend that you keep this box checked.

Load Balancer Type

Currently the only available value is Altinity Edge Ingress.

Protocols

Port 9440 enables the ClickHouse binary protocl, and port 8443 enables HTTP connections. You’ll typically want to leave both of these selected.

Datadog Integration

Currently disabled

IP restrictions

This is disabled by default. If you enable it, you’ll see a text box where you can enter ranges of IP addresses in CIDR format. Only requesters from those IP address ranges will be allowed to connect to your cluster.

Figure 8 – The IP restrictions field

Click NEXT to continue.

5. Uptime Schedule

You’re almost done! The final configuration option is to determine when your ClickHouse cluster should run.

Figure 9 – The Uptime Schedule tab

There are three options:

• ALWAYS ON - Self-explanatory; your cluster is always on.
• STOP WHEN INACTIVE - Lets you define how many hours your ClickHouse cluster can be idle before it is stopped.
• ON SCHEDULE - Lets you define specific times when your cluster is on. See Uptime Schedule Settings for complete details about how to set an uptime schedule.

Click NEXT to continue.

6. Review & Launch

Finally, you have a chance to review your options before you provision and deploy the ClickHouse cluster. You can’t change anything on this screen, but you can use the BACK button to make changes on earlier tabs.

Figure 10 – The Review & Launch tab

If everything looks good, click LAUNCH to launch your new ClickHouse cluster.

Cluster view with your new ClickHouse cluster

When your cluster is deployed and running, you’ll see something like this:

Figure 11 – A newly created cluster

In the display, we’ve created a new cluster named maddie-ch. The green indicator beneath the cluster name tells us 2 of 2 nodes are running. The green indicator in the Health field tells us 6 of 6 tests passed.

Congratulations! You now have a new ClickHouse cluster.

4 - The Cluster Explorer

Overview - Using the cluster Explore > Query

This example shows how to navigate from the cluster home page and how to use Explore > Query to run a query a ClickHouse database on the included demo cluster called github.

The following screenshot shows the step-by-step sequence of events, starting from your cluster home page (A), then selecting the ClickHouse database repository demo github cluster against which you will run the example SQL query in the Explore > Query screen (B).

To run a SQL query from the demo cluster named github:

1. Enter the URL into a browser: https://acm.altinity.cloud/clusters/
2. From the domain menu, select demo.
3. Within the cluster called github, select EXPLORE. Note that the URL changes to: https://acm.altinity.cloud/cluster/337/explore (see Figure 2 B-1) . Note that the menu title shows that CLUSTER:GITHUB is selected (see Figure 2 B-3).
4. Under the Query History, paste the text of the example SQL query.
5. Select EXECUTE to run the query.
6. Optionally, select and copy the results of the query.

Figure 1 – The home page showing all clusters.

Figure 2 – The Explore of the demo > github cluster viewing the Query tab.

SQL Query script

The following SQL script generates a 3-column report from a github database from 2019 to 2023 that the collates the number of pull requests (PRs) made by unique contributors.

SELECT toStartOfYear(merged_at) m, sum(merged) prs, uniq(creator_user_login) contributors
  FROM github_events
 WHERE merged_at>='2019-01-01'
   AND event_type = 'PullRequestEvent'
   AND repo_name in ('ClickHouse/ClickHouse', 'yandex/ClickHouse')
 GROUP BY m
 ORDER BY m

Code snippet 1 – The input, an example SQL query script to get 4 years of unique pull request contributor totals.

Query explanation

The SQL query visualization shows the Input (green) data sources and Output (red) 3 columns M, PRs and Contributors.

Figure 3 – The example SQL query script and visualization.

First select the start of the year for the merged_at column (line 1), the sum of the merged column (m), and the unique values in the creator_user_login column from the github_events table (line 2).

Include only the rows where the merged_at column is on or after January 1, 2019 (line 3) and the event_type column is ‘PullRequestEvent’ (line 4) and the repo_name column is either ‘ClickHouse/ClickHouse’ or ‘yandex/ClickHouse’ (line 5).

Group the results (line 6) by the start of the year for the merged_at column (from line 3)

Lastly, order the results (line 7) by the start of the year for the merged_at column.

SQL Query results

The results of the query appear below the EXECUTE button, listing 3 columns titled m (year), PRs and Contributors.

┌──────────m─┬──prs─┬─contributors─┐
│ 2019-01-01 │ 2278 │          232 │
│ 2020-01-01 │ 6000 │          300 │
│ 2021-01-01 │ 7766 │          366 │
│ 2022-01-01 │ 5639 │          392 │
│ 2023-01-01 │  157 │           41 │
└────────────┴──────┴──────────────┘

Code snippet 2 – The output, 3 columns of year (m), PRs and contributors showing 4 years of unique pull request contributor totals.