This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Quick Start Guide

The minimal steps to get Altinity.Cloud running with your first cluster.

Welcome to Altinity.Cloud! Altinity.Cloud is the fastest, easiest way to set up, administer and use ClickHouse. Your ClickHouse is fully managed so you can focus on your work.

If this is your first time using Altinity.Cloud, this quick start guide will give you the minimum steps to become familiar with the system. When you’re ready to dig deeper and use the full power of ClickHouse in your Altinity.Cloud environment, check out our Administrator and Developer Guides for in depth knowledge and best practices.

1 - Altinity Cloud Manager Introduction

An overview of using the Altinity Cloud Manager (ACM) to managing your ClickHouse clusters with Altinity.Cloud.

26 January 2023 · Read time 3 min

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. https://acm.altinity.cloud/clusters/

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.
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.
Launch Cluster button

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 .
Launch Cluster button

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.
Launch Cluster button

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.

Launch Cluster button

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.

Launch Cluster button

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.

Launch Cluster button

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 example-environment-name appears in your Altinity Cloud Manager (ACM).

Points of interest include:

example-environment - Menu name changes to the selected environment (aka namespace or domain).
2/2 nodes online - Green to indicate running status. Action > Stop to take offline.
0/2 nodes online - Red shows nodes are not running. Action > Resume to start.
stopped - Cluster / node is not running. Action > Resume to start.
6/6 checks passed - Shows green when all 6 checks have completed successfully.
0/6 checks passed - Shows red until all checks have passed. Action > Resume to start.
Shield green - TLS (Transport Layer Security) is enabled.
Actions - Mouse hover shows this light blue shade.
Blue outline - In cluster panel view, moving your mouse cursor over a cluster changes the grey outline to blue; click to view.
Panel view icon - View clusters in panel format.
List view icon - View cluster in a list format.
Address of all clusters - https://acm.altinity.cloud/clusters/
Address of a specific cluster - https://acm.altinity.cloud/cluster/2887

Cluster Launch Wizard summary

Figure 8 – Points of interest from the newly created example-cluster.

2 - Account Creation and Login

How to set up your Altinity.Cloud account, and login to the service.

26 January 2023 · Read time 2 min

Free Trial Account Creation

To start your Altinity.Cloud journey, the first thing you need is an account. New users can sign up for a 14-day Trial account from the following link:

For the free trial to the Altinity.Cloud Anywhere product, which is an on-premises version that you can run in your own Kubernetes environment, see:

Requested information as shown in the following screenshot includes:

  • First Name and Last Name
  • Email (if you provide a Google business email account (this does not include person @Gmail emails), you can login with Auth0 login)
  • Company name
  • Country
  • Cloud Provider that you use (Examples: Amazon, Google)
  • Your managed environment name (eg: my-staging)


Email Validation

When you SUBMIT the Free 14-day Trial form, you will immediately receive an email from Altinity with a validation link that you click to confirm.

First Time Login

Once you validate your email, your request for the Altinity.Cloud free trial will be processed for approval. The Altinity.Cloud (support@altinity.com) team will provide the following login information.

The following example screenshot is an email that you will receive from Altinity.Cloud notifying you that your 14-day Free Trial to Altinity.Cloud has been approved.

  1. Your-altinity is an example of the environment name you supplied Altinity. (NOTE: If your name choice already exists in our system, we will rename it.)

  2. The URL is customized to you and is used once only for the initial login.

  3. Here refers to a Calendar link https://calendly.com/trial-support-team/altinity-cloud-trial-check

  4. Quick Start Guide https://docs.altinity.com/altinitycloud/quickstartguide/

  5. Series of videos https://www.youtube.com/hashtag/altinitycloud

  6. Support email is support@altinity.com

Creating a new password

Clicking the link (item 2) shows the Onboarding window that prompts you to create a new password.

Logging into the Altinity Cloud Manager

Fill in your Altinity Cloud Manager credentials screen and select SIGN IN:

  1. ACM Login
    https://acm.altinity.cloud/login
  2. Login Email
    (example: johnDoe@outlook.com)
  3. Password
    (example: S0me@c0pl3x_password - •••••••••••••••••••• dots show as you type)

Auth0 login

AUTH0 is used to login if you have a Google Gmail account that Altinity.Cloud supports for trusted authentication. Note that in order for this to work, you must have used your Gmail address to register for the Altinity.Cloud Free Trial.

To use Auth0 to login:

  1. Select the Auth0 link from the bottom of the ACM login window.
  2. Select Continue with Google.
  3. If you are not already logged into a Google domain, the usual Google login screen appears. Select the same Google domain email address you registered with Altinity.Cloud to complete the login. NOTE: This does not includ

Privacy Policy

See the Privacy Policy at:

3 - How to Run a SQL Query

This is an introduction to the cluster Explore > Query feature. You will learn how to select a cluster from the included demo and run a SQL query and view the results.

26 January 2023 · Read time 3 min

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.
Cluster Launch Wizard summary

Figure 1 – The home page showing all clusters.


Cluster Launch Wizard summary

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.

Cluster Launch Wizard summary

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.

4 - Cluster Launch Wizard

An introduction to the Cluster Wizard, used to create a new ClickHouse cluster. An overview of the settings is provided, with links to further details.

26 January 2023 · Read time 5 min

Overview - Cluster Launch Wizard (summary)

This section covers the Altinity Cloud Manager ClickHouse cluster creation feature called the Cluster Launch Wizard. This getting started guide walks you through the steps to create a new cluster from scratch.

  • The Detailed reference link takes you to section on the Wizard Settings Detail page that explains each setting.
  • Where indicated, additional settings and resources can be obtained upon request from Altinity Technical Support at: https://altinity.com/contact/

The following wizard screens are covered on this page:

  1. ClickHouse Setup | Detailed reference
  2. Resources Configuration | Detailed reference
  3. High Availability Configuration | Detailed reference
  4. Connection Configuration | Detailed reference
  5. Uptime Schedule | Detailed reference
  6. Review & Launch | Detailed reference

The following illustration shows a summary of the various screens available in the Cluster Wizard.

Restore Wizard summary

Figure 1 – Each of the Restore Wizard screens and the available settings.



Launch Cluster

The Altinity Cloud Manager (ACM) is where your existing clusters are shown. https://acm.altinity.cloud/clusters/ If this is the first time you have seen this page, or you have deleted all of your clusters, this page will be blank and show the text string: "You don’t have any clusters running at this moment."

Points of interest marked by the red pins include:

  • The your.environment name is what you signed up with. Note that a read-only demo environment is included.
  • 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.

To begin the creation of a new ClickHouse cluster:

  1. Select the LAUNCH CLUSTER button.
Launch Cluster button

Figure 2 – The Altinity Cloud Manager (ACM) home page, selecting the LAUNCH CLUSTER button.


  1. Starting with the ClickHouse Setup screen, fill in the information required by each wizard screen clicking NEXT to navigate.
Launch Cluster wizard screens

Figure 3 – Each of the 6 Cluster Launch Wizard screens and the available settings.


1. ClickHouse Setup

After selecting the LAUNCH CLUSTER button, the first wizard setup screen appears ClickHouse Setup.

Enter the following then click NEXT:

Cluster Launch Wizard summary

Figure 4 – The wizard screen 1 of 6 ClickHouse Setup.


2. Resources Configuration

The second screen is Resources Configuration, where you choose the CPU and storage settings. If you need more resources that what is displayed, contact Altinity Support.

Enter the following then click NEXT:

Cluster Launch Wizard summary

Figure 5 – The wizard screen 2 of 6 Resources Configuration.


3. High Availability Configuration

This screen covers server redundancy and failover.

Enter the following then click NEXT:

Cluster Launch Wizard summary

Figure 6 – The wizard screen 3 of 6 High Availability Configuration.


4. Connection Configuration

This screen covers communication details such as port settings and endpoint information.

Enter the following then click NEXT:

Cluster Launch Wizard summary

Figure 7 – The wizard screen 4 of 6 Connection Configuration.


5. Uptime Schedule

This lets you choose the type of schedule for when the cluster is allowed run.

Set the Uptime Schedule so that the server never turns off, then click NEXT:

Cluster Launch Wizard summary

Figure 8 – The wizard screen 5 of 6 Uptime Schedule.


6. Review & Launch

There is nothing to add or change on this review screen.

This is last chance where you can use the BACK button and change previously entered settings, then return to this screen. If there are no changes, select the LAUNCH button to save the settings and start the cluster provisioning process.

The following information is presented:

Cluster Launch Wizard summary

Figure 9 – The last wizard screen 6 of 6 Review & Launch.


Cluster view after Wizard finishes

The example-cluster appears in your Altinity Cloud Manager (ACM). Any new cluster will appear as another panel or another row in a table listing.

Points of interest include:

example-environment - Menu name changes to the selected environment (aka namespace or domain). 2/2 nodes online - Green to indicate running status. Action > Stop to take offline. 0/2 nodes online - Red shows nodes are not running. Action > Resume to start. stopped - Cluster / node is not running. Action > Resume to start. 6/6 checks passed - Shows green when all 6 checks have completed successfully. 0/6 checks passed - Shows red until all checks have passed. Action > Resume to start. Shield green - TLS (Transport Layer Security) is enabled. Actions - Mouse hover shows this light blue shade. Blue outline - In cluster panel view, moving your mouse cursor over a cluster changes the grey outline to blue; click to view. Panel view icon - View clusters in panel format. List view icon - View cluster in a list format. Address of all clusters - https://acm.altinity.cloud/clusters/ Address of a specific cluster - https://acm.altinity.cloud/cluster/2887

Cluster Launch Wizard summary

Figure 10 – Points of interest from the newly created example-cluster.

5 - Wizard Settings Detail

Details for the various Cluster wizard settings.

26 January 2023 · Read time 11 min

Overview

Purpose

This section provides a detailed discussion of the settings that expands on the overview of the Cluster Launch Wizard.

See Also:

The following diagram is a snapshot view of the 6 wizard screens showing the settings that are discussed on this page:

Cluster Launch Wizard summary
Figure 1 Summary list of settings in each of the Cluster Wizard screens.




Create a new ClickHouse cluster

  1. From the Altinity.Cloud Manager, create a new ClickHouse cluster by selecting the LAUNCH CLUSTER button.
    Cluster Launch Wizard summary


ClickHouse Setup

These are ClickHouse-related settings. (Screen 1 of 6) Name | ClickHouse Version | ClickHouse User Name | ClickHouse User Password

  1. Fill in the 4 ClickHouse Setup fields.
  2. Select NEXT to advance to the next cluster wizard screen Resources Configuration.
  3. Or, select CANCEL to close the wizard without saving.

To see the full-sized ClickHouse Setup screen, see:

ClickHouse Setup

Cluster Launch Wizard ❯ ClickHouse Setup


Name

This is the DNS-compliant name of the cluster.

  • Example: example-cluster

Name of the cluster
Figure 2 – The Name of the cluster example-cluster in the ClickHouse Setup wizard screen.

The Name of your cluster must follow DNS name restrictions as follows:

Allowed

  • Name must start with a letter
  • Lower case letters (a to z)
  • Numbers (0 to 9)
  • Hyphens, also named dash or minus character (-)
  • 15 character limit

Disallowed

  • Periods (.)
  • Special characters ( > ’ , " ! # )

UI Text

  • “Cluster name tag will be used in ClickHouse configuration and it may contain only lowercase letters [a-z], numbers [0-9] and hyphens [-] in between”

ClickHouse Version

This lets you choose which version of ClickHouse to use, from a list in the Altinity Builds category or any other ClickHouse Community Builds.

ClickHouse Version
Figure 3 The ClickHouse software version number from the cluster wizard ClickHouse Setup screen.

Altinity Builds

Altinity Stable Builds are tested, proven stable builds with 6-month test cycles. They are based on ClickHouse Long Term Support (LTS) releases and are supported for up to 3 years. These release numbers include the phrase Altinity Stable Build.

See also:

Example values: (Your system may be different.)

  • 21.1.11 Altinity Stable Build
  • 21.3.20 Altinity Stable Build
  • 21.8.15 Altinity Stable Build
  • 22.3.12 Altinity Stable Build
  • Custom Version (Image Identifier)
Community Builds

This is a list of all available ClickHouse versions. Example values: (Your system may be different.)

  • 21.3.20.1 Altinity Stable (community build)
  • 21.8.15.7 Altinity Stable (community build)
  • 21.11.11.1
  • 22.3.12.19 Altinity Stable (community build)
  • 22.6.8.35
  • 22.8.10.29
  • Custom Version (Image Identifier)

UI Text

  • “ClickHouse Version will be the same across all Cluster nodes”

ClickHouse User Name

ClickHouse User Name
Figure 4 The ClickHouse User Name from the cluster wizard ClickHouse Setup screen.

This is the Account name of the ClickHouse administrator. By default, this name is set to admin.

  • Example: admin

UI Text

  • “ClickHouse user will be created with the specified login”

ClickHouse User Password

ClickHouse User Name
Figure 5 The ClickHouse User Password from the cluster wizard ClickHouse Setup screen.

  • Passwords need to be at lease 12 characters.
  • Too-short passwords produce an Error: Invalid ClickHouse user password.
  • As you type past 12 characters, the red banner will go away.
  • Click the Show password icon then copy and paste to the right Confirm Password field.
  • Example: ThisI5Ac0Plexp4ssW0rd | Confirm Password •••••••••••••••••••••

UI Text

  • This password will be assigned to the ClickHouse User The minimum password length is 12 characters. Consider adding digits capital letters and special symbols to make password more secure


Resources Configuration

Sets the CPU size, RAM/memory and storage settings. (Screen 2 of 6) Node Type | Node Storage (GB) | Number of Volumes | Volume Type | Number of shards

  1. Fill in the 5 Resources Configuration fields.
  2. Select NEXT to advance to the next cluster wizard screen High Availability Configuration.
  3. Or, select BACK to return to the previous cluster wizard screen ClickHouse Setup.
  4. Or, select CANCEL to close the wizard without saving.

To see the full-sized Resources Configuration screen, see:

Resources Configuration

Cluster Launch Wizard ❯ Resources Configuration



Node Type

CPU and RAM sizes for the node. The names in the drop-down menu will differ depending on which environment you are using. (E.g., between AWS and GCP.) Contact Altinity Technical Support if you need additional node types.

ClickHouse User Name
Figure 6 The Node Type (CPU and RAM) from the cluster wizard Resources Configuration screen.

  • Clusters can later be scaled up or down dynamically.
  • Example: m5.large (CPU x2, RAM 7 GB)

More Information

Available sizes (set by your Cloud provider):

Example

  • m5.large (CPU x2. RAM 7 GB)
  • m5.xlarge (CPU x4. RAM 14 GB)
  • m5.2xlarge (CPU x8. RAM 29 GB)
  • m5.4xlarge (CPU x16. RAM 58 GB)
  • m5.8xlarge (CPU x32. RAM 120 GB)
  • c5.18xlarge (CPU x72. RAM 128.9 GB)

UI Text

  • “Node Type will be the same across all ClickHouse hosts”

Node Storage

The size of each cluster node in GB (gigabytes).

ClickHouse User Name
Figure 7 The Node Storage size in GB from the cluster wizard Resources Configuration screen.

  • Each node has the same storage area.
  • Example: 100 (GB)

UI Text

  • “Each ClickHouse host will have specified amount of local volume storage”

Number of Volumes

Depending on the cloud provider you are using, creating more volumes may improve query performance.

ClickHouse User Name
Figure 8 The Number of Volumes to set, from the cluster wizard Resources Configuration screen.

UI Text

  • “Network storage can be split to several volumes for a better query performance”

Volume Type

These are SSD block storage volumes provided by Amazone AWS, Google GCP, or other cloud providers.

The choices are:

  • gp2-encrypted
  • gp3-encrypted

ClickHouse User Name
Figure 9 The Volume Type gp2-encrypted or gp3-encrypted from the cluster wizard Resources Configuration screen.

UI Text

  • “Defines volume claim storage class for each ClickHouse host”

Number of Shards

Shards group nodes that work together to share data and improve performance. Replicating shards is done to increase availability and speed up recovery if one shard goes down.

ClickHouse User Name
Figure 10 The Number of Shards to create, from the cluster wizard Resources Configuration screen.

Where quotas are in place, the UI string “x / y (ie. 1 of 20) shards will be used”.

UI Text

  • “Each shard will required X number of
  • ClickHouse hosts where X is the number
  • of replicas of this shard (X = 2)”


High Availability Configuration

These are redundancy and failover settings. (Screen 3 of 6) Number of Replicas | Zookeeper Configuration | Zookeeper Node Type | Enable Backups

  1. Fill in the 4 High Availability Configuration fields.
  2. Select NEXT to advance to the next cluster wizard screen Connection Configuration.
  3. Or, select BACK to return to the previous cluster wizard screen Resources Configuration.
  4. Or, select CANCEL to close the wizard without saving.

UI Text

  • “Please contact Altinity Support if you need more resources”

To see the full-sized High Availability Configuration screen, see:

High Availability

Cluster Launch Wizard ❯ High Availability Configuration


Number of Replicas

ClickHouse User Name
Figure 11 The Number of Replicas to create, from the cluster wizard High Availability Configuration screen.

  • 1 | 2 | 3
  • Number of Replicas for each Cluster Shard
  • Replicas: x / y Replicas will be used (appears if Altinity Support has set usage quotas)

UI Text

  • “Number of Replicas for each Cluster shard”

Quotas set by Altinity

If bar charts appears, this means Altinity Support has set quotas for your domain.

ClickHouse User Name
Figure 12 The graphs for CPU and Storage appear if Altinity Support has set quotas. From the cluster wizard High Availability Configuration screen.

  • CPU: x / y vCPUs will be used
  • Storage: x / y GB will be used

Zookeeper Configuration

ClickHouse User Name
Figure 13 The Zookeeper Configuration and Zookeeper Node Type from the cluster wizard High Availability Configuration screen.

  • Example: Dedicated

UI Text

  • “You can pick a shared Zookeeper cluster, Launch a dedicated one or do not use Zookeeper at all.”

Zookeeper Node Type

  • Default

Enable Backups

Whether or not backups occur.

ClickHouse User Name
Figure 14 The Enable Backups checkbox and Backup Schedule from the cluster wizard High Availability Configuration screen.

  • Example: True (checked)

Backup Schedule

This is the frequency that data backups happen.

  • Example: Daily

UI Text

  • [ none ]

Number of Backups to keep

ClickHouse User Name
Figure 15 The Number of Backups to keep from the cluster wizard High Availability Configuration screen.

  • Example: 7

UI Text

  • [ none ]


Connection Configuration

Used to set the communications protocols. (Screen 4 of 6) Endpoint | Use TLS | Load Balancer Type | Protocols | Datadog integration | IP restrictions

  1. Fill in the 5 Connection Configuration fields.
  2. Select NEXT to advance to the next cluster wizard screen Uptime Schedule.
  3. Or, select BACK to return to the previous cluster wizard screen High Availability Configuration.
  4. Or, select CANCEL to close the wizard without saving.

UI Text

  • “Please contact Altinity Support if you need more resources.”

To see the full-sized Connection Configuration screen, see:

Connection Configuration

Cluster Launch Wizard ❯ Connection Configuration


Endpoint

The Endpoint is the access point domain name to your cluster. The URL breaks down as follows:

  • example-cluster is the name of the cluster
  • customer-domain is your environment
  • altinity.cloud is the parent for all environments
  • Example: example-cluster.customer-domain.altinity.cloud

ClickHouse User Name
Figure 16 The Endpoint URL from the cluster wizard Connection Configuration screen.

UI Text

  • “Access point Domain Name”

Use TLS

When True, the connection to the Cluster Endpoints will be secured with TLS.

  • Example: True (checked)

ClickHouse User Name
Figure 17 The Use TLS checkbox from the cluster wizard Connection Configuration screen.

UI Text

  • “Connection to the Cluster Endpoints will be secured with TLS”

Load Balancer Type

Choice of the Load Balancer you want to use.

  • Example: Altinity Edge Ingress

ClickHouse User Name
Figure 18 The Load Balancer Type (Altinity Edge Ingress is selected) from the cluster wizard Connection Configuration screen.

UI Text

  • [ none ]

Protocols

Port settings. By default, these settings cannot be unchecked.

  • Binary Protocol (port: 9440) = True (checked) UI Text - “This enables native ClickHouse protocol connection”
  • HTTP Protocol (port: 8443) = True (checked) UI Text - “This enables native ClickHouse protocol connection”

ClickHouse User Name
Figure 19 The Protocols ports to enable, from the cluster wizard Connection Configuration screen.

Datadog integration

For logging purposes, you can request that the third-party application Datadog be set up by Altinity Support.

  • Datadog integration (disabled) - This entire section is dimmed.
  • Send Logs = False (unchecked)
  • Send Metrics = False (unchecked)

ClickHouse User Name
Figure 20 If Altinity Support has enabled this, Datadog integration is selectable. From the cluster wizard Connection Configuration screen.

UI Text

  • [ none ]

IP restrictions

This is used to increase security by using a whitelist, or allowlist of IP numbers to restrict access.

Note that Altinity needs to have certain ports open in order to maintain your tenancy.

  • IP restrictions
  • Enabled False (unchecked) - This is the default setting
  • Enabled True (checked) - Turn on this setting then add IP numbers

ClickHouse User Name
Figure 21 If Altinity Support has enabled this, *IP restrictions lets you whitelists IP numbers. From the cluster wizard Connection Configuration screen.

UI Text

  • Restricts ClickHouse client connections to the provided list of IP addresses in CIDR format. Multiple entries can be separated by new lines or commas

    Note:
    34.238.65.247,
    44.195.72.25,
    100.24.75.12,
    10.0.0.0/8,
    172.16.0.0/12,
    192.168.0.0/16,
    10.128.0.0/23,
    10.128.2.0/23,
    10.128.4.0/23
    is added automatically as it is required for Altinity.Cloud to operate.


Uptime Schedule

Used to set a schedule for when the clusters should run. (Screen 5 of 6) For this Quick Start Guide, the servers are set to ALWAYS ON. Always On | Stop When Inactive | On Schedule


To see the full-sized Uptime Schedule screen, see:

Uptime Schedule

Cluster Launch Wizard ❯ Uptime Schedule


To set (or remove) an Uptime Schedule:

  1. Click one of the three Uptime Schedule settings.
  2. Select NEXT to advance to the last cluster wizard screen Review & Launch.
  3. Or, select BACK to return to the previous cluster wizard screen Connection Configuration.
  4. Or, select CANCEL to close the wizard without saving.

ClickHouse User Name
Figure 22 The cluster , Uptime Schedule lets you set when you want your clusters to run. From the cluster wizard Uptime Schedule screen.

Sets server uptime. See the General User Guide > Uptime Schedule Settings page for setting details .

Always On

Use this setting to run your cluster 24/7.

UI Text

  • “Altinity.Cloud shall not trigger any Stop or Resume Operations on this Cluster automatically”

Stop When Inactive

Use this setting to stop clusters from running after a set number of hours. Servers must be manually restarted.

  • Example: Hours of inactivity 24

UI Text

  • “The cluster will be stopped automatically when there is no activity for a given amount of hours”

On Schedule

Use this setting to schedule the times in each of the days of a week to run.

UI Text

  • Uptime Schedule for .
  • “Schedule (Time in GMT)”
  • “Monday Tuesday Wednesday Thursday Friday Saturday Sunday”
  • “Active”, “All Day”, “From: hh:mm AM/PM To: hh:mm AM/PM”

Review & Launch

This is the last chance to review settings before saving and launching the new ClickHouse cluster. (Screen 6 of 6)

  1. Select LAUNCH to save and start the cluster.
  2. Or, select BACK to return to the previous cluster wizard screen Uptime Schedule.
  3. Or, select CANCEL to close the wizard without saving.

To see the full-sized Review & Launch screen, see:

Review & Launch

Cluster Launch Wizard ❯ Review & Launch


ClickHouse User Name
Figure 23 The last wizard screen Review & Launch displays your CPU and RAM choices and a cost estimate.

Cluster Cost Estimate

UI Text You are about to launch cluster example-cluster with 1 shards with replication which will require:

  • 2 x CH Nodes m5.large
  • 14 GB of memory in total
  • 200 GB of storage volume in total
  • Estimated Cluster cost: $0.76/hour ($547.20/month)

Select LAUNCH to save and start the cluster.

ClickHouse User Name

Figure 24 – The LAUNCH button on the last wizard screen Review & Launch.

Conclusion

Launching a new cluster using the Cluster Launch Wizard is now complete.

Continue on to the next section:

6 - Creating Tables and Adding Data

How to use Explore on your cluster to run SQL queries to create tables, import data, and view schema and table data.

26 January 2023 · Read time 3 min

Overview - Creating Tables

This section is for first time users that have just learned how to create a ClickHouse cluster, and now want to add tables and data.

The Altinity.Cloud Manager (ACM) screens used on this page are:

  • ACM home page ❯ Clusters
  • ACM: Cluster (name) > Explore > Query tab
  • ACM: Cluster (name) > Explore > Schema tab
  • ACM: Cluster (name) > Explore > Schema tab > Table (name)
  • ACM: Cluster (name) > Explore > Schema tab > Table (name) > Table Details > Sample Rows

Creating Tables

The next step after creating a new ClickHouse cluster is to create tables. After completing this example, two empty tables are created:

  • events_local
  • events

Prerequisite

  • Open the UI screen: ACM: Cluster (name) > Explore > Schema tab

To create two tables in your blank cluster by using a SQL Query:

  1. From the domain menu, select your domain (ie. your.domain). https://acm.altinity.cloud/clusters

  2. In your cluster (ie. example-cluster), select EXPLORE. Confirm that the Query tab is selected.

  3. To create the first table called events_local table, copy and paste in the following SQL query then EXECUTE:

    CREATE TABLE IF NOT EXISTS events_local ON CLUSTER '{cluster}' (
        event_date  Date,
        event_type  Int32,
        article_id  Int32,
        title       String
    ) ENGINE = ReplicatedMergeTree('/clickhouse/{cluster}/tables/{shard}/{database}/{table}', '{replica}')
        PARTITION BY toYYYYMM(event_date)
        ORDER BY (event_type, article_id);
    
  4. To create the second table called events, copy and paste in the following SQL query then EXECUTE:

    CREATE TABLE events ON CLUSTER '{cluster}' AS events_local
       ENGINE = Distributed('{cluster}', default, events_local, rand())
    
  5. Below the EXECUTE button, the following information displays after running each SQL query:

    example-cluster.your-domain.altinity.cloud:8443 (query time: 0.335s)

    chi-example-cluster-example-cluster-0-0	9000	0		1	0
    chi-example-cluster-example-cluster-0-1	9000	0		0	0
    
  6. In the Schema tab, confirm that the two tables events_local and events are present.


Adding Data

In the Query tab, SQL commands are used to add data to your ClickHouse tables and to verify the additions.


Prerequisite

  • Open the UI screen: ACM: Cluster (name) > Explore > Schema tab

To add data to the events_local table:

  1. Copy and paste the following to the cluster Query field then Execute:

    INSERT INTO events VALUES(today(), 1, 13, 'Example');
    
  2. Verify that the data has been added to events_local by running the query:

    SELECT * FROM events;
    
  3. The following response appears below the EXECUTE button.

    ┌─event_date─┬─event_type─┬─article_id─┬─title───┐
     2023-01-04           1          13  Example 
    └────────────┴────────────┴────────────┴─────────┘
    

Viewing Schema and Data

The Schema tab contains a list of your ClickHouse tables and data in your cluster.


Prerequisite

  • Open the UI screen: ACM: Cluster (name) > Explore > Schema tab
  • UI screen: ACM: Cluster (name) > Explore > Schema tab > Table (name) > Table Details > Sample Rows

To view the Adding:

  1. Select the Schema tab. Two tables are listed, events_local and events.

  2. Within the Schema tab, select the Table link called events_local.

  3. In the Table Details dialog box, select the tab Sample Rows. The following information appears.

    ┌─event_date─┬─event_type─┬─article_id─┬─title───┐
     2023-01-04           1          13  Example 
    └────────────┴────────────┴────────────┴─────────┘
    
  4. Select DONE to close the Table Details window.

7 - ClickHouse Ubuntu Terminal Remote Client

How to install the ClickHouse Ubuntu command line client and connect to your Altinity.Cloud cluster.

26 January 2023 · Read time 2 min

Overview - Ubuntu ClickHouse Client

This section covers the installation of the ClickHouse client on the Linux OS Ubuntu 20.04.
After installation, you will be able to run use ClickHouse queries from the terminal.

Updating Ubuntu

  1. Update your Ubuntu OS and confirm the version with the following commands:

    sudo apt-get update
    sudo apt-get upgrade
    lsb_release -a
    

Installing ClickHouse drivers

To install ClickHouse drivers on Ubuntu 20.04:

  1. Copy and paste each of the following lines to your Ubuntu terminal in sequence:

    sudo apt-get install -y apt-transport-https ca-certificates dirmngr
    sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 8919F6BD2B48D754
    echo "deb https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
    sudo apt-get update
    sudo apt-get install -y clickhouse-client
    clickhouse-client --version
       ClickHouse client version 22.12.3.5 (official build).
    

More information

Logging on to your cluster

  1. From the Connection Details, copy and paste the text string to your Ubuntu terminal:

     clickhouse-client -h example-cluster.your-domain.altinity.cloud --port 9440 -s --user=admin --password
    

ClickHouse terminal response

  1. After you enter your ClickHouse cluster password, you enter the ClickHouse interactive mode.
    ClickHouse prompt example: example-cluster :)

    (test2) user@xubuntu:~$ clickhouse-client -h example-cluster.your-domain.altinity.cloud --port 9440 -s --user=admin --password
    ClickHouse client version 22.12.3.5 (official build).
    Password for user (admin): 
    *********
    
    Connecting to example-cluster.your-domain.altinity.cloud:9440 as user admin.
    Connected to ClickHouse server version 22.3.15 revision 54455.
    
    ClickHouse server version is older than ClickHouse client. 
    It may indicate that the server is out of date and can be upgraded.
    
    example-cluster :) 
    

ClickHouse query examples

  1. At the ClickHouse prompt, enter the query command show tables:

    example-cluster :) show tables
    
    SHOW TABLES
    
    Query id: c319298f-2f28-48fe-96ca-ce59aacdbc43
    
    ┌─name─────────┐
    │ events       │
    │ events_local │
    └──────────────┘
    
    2 rows in set. Elapsed: 0.080 sec.
    
  2. At the ClickHouse prompt, enter the query select * from events:

    example-cluster :) select * from events
    
    SELECT *
    FROM events
    
    Query id: 0e4d08b3-a52d-4a03-917d-226c6a2b00ac
    
    ┌─event_date─┬─event_type─┬─article_id─┬─title───┐
    │ 2023-01-04 │          113 │ Example │
    │ 2023-01-10 │          113 │ Example │
    │ 2023-01-10 │          114 │ Example │
    └────────────┴────────────┴────────────┴─────────┘
    
    3 rows in set. Elapsed: 0.073 sec.
    

To quit, or exit from the ClickHouse interactive mode:

  1. Enter the exit command to return to your Ubuntu shell environment.

    example-cluster :) exit
    Bye.
    

This completes the quick start guide to installing ClickHouse command-line client on an Ubuntu OS.

Related links

Troubleshooting

Make sure you have the latest ClickHouse client installed to avoid connection issues.

Problem

  • Error Code: 210 SSL connection unexpectedly closed.
  • Problem result: Cannot connect to ACM Cluster with clickhouse-client terminal command.
ubuntu@ip-172-31-16-238:~$ clickhouse-client -h test-anywhere.awsanywhere.altinity.cloud --port 9440 -s --user=admin --password=supersecretpassword123

# Error response: note the older version of the ClickHouse client v18.16.1
ClickHouse client version 18.16.1.
Connecting to test-anywhere.awsanywhere.altinity.cloud:9440 as user admin.
Code: 210. DB::NetException: SSL connection unexpectedly closed (test-gap-anyw.awsanywhere.altinity.cloud:9440, 33.33.33.333)

Reason for the error

When you have an outdated version of the ClickHouse client software installed, you may fail to connect to your ACM cluster. The issue may be that a standard apt-get install or apt-get upgrade will not retrieve the latest version of the ClickHouse client as shown in this example terminal listing.

sudo apt install clickhouse-client
...
# Note the older client
Get:25 http://us-east-2.ec2.archive.ubuntu.com/ubuntu focal/universe amd64 clickhouse-common amd64 18.16.1+ds-7 [9266 kB]
Get:26 http://us-east-2.ec2.archive.ubuntu.com/ubuntu focal/universe amd64 clickhouse-client amd64 18.16.1+ds-7 [138 kB]
---

Solution The solution is to follow the instructions on this page:

8 - ClickHouse Python Client

How to install the ClickHouse Python driver, and connect to your Altinity.Cloud ClickHouse Cluster from a Python program or a Python console.

26 January 2023 · Read time 4 min

Overview - Python ClickHouse Client

This section covers the installation and use of the Python ClickHouse client.
After installation, you will be able to run use ClickHouse queries on any platform that will run Python3.

  • You must first have completed Creating Tables and Adding Data.
  • You have copied the Connection Details from your cluster.
  • Python version 3.7 (or later) is installed (this page is tested using Python 3.11.1)

More information


Installing the ClickHouse Python driver

Install ClickHouse drivers using the Python 3 PIP package installer:

pip install clickhouse-driver

Example Python program

The following Python program demonstrates:

  • Importing the clickhouse-driver library (that was previously installed by the Python 3 PIP package installer)
  • Connecting to your ClickHouse cluster example-cluster
  • Listing all of the tables that exist in the example-cluster
  • Listing the data in the example table events_local
  • Showing the version number of the Python clickhouse-driver (0.2.5)

Shortcut for experienced users

  • Python program filename: ClickHouse-example.py (copy and paste the code)
  • Update the program strings for the cluster name from Connection Details link on your cluster, such as: your-company-example yourpasswordhere
  • Run the command: python3 ClickHouse-example.py

Instructions

  1. Modify the following in the Python program ClickHouse-example.py as follows:

    • Change the cluster name, replacing your-company-example
    • Change password yourpasswordhere to your own ClickHouse cluster name

  1. Run the program from the terminal or your IDE:

    • python3 ClickHouse-example.py

Code Snippet 1 - ClickHouse-example.py


import clickhouse_driver
print(clickhouse_driver.__version__)

# No return characters:
# Replace your-company-example
# Replace yourpasswordhere 
# client = Client('example-cluster.your-company-example.altinity.cloud', user='admin', password='yourpasswordhere', port=9440, secure='y', verify=False)

# Connect to your cluster
from clickhouse_driver import Client
client = Client('example-cluster.your-company-example.altinity.cloud',
                user='admin',
                password='yourpasswordhere',
                port=9440,
                secure='y',
                verify=False)

# Show tables
tables = client.execute('SHOW TABLES in default')
print(tables)


# Show data
result = client.execute('SELECT * FROM default.events')
print(result)


# Show ClickHouse Python driver version
version = (clickhouse_driver.__version__)
print("ClickHouse Python version: ", version)

Python program response

[('events',), ('events_local',)]
[(datetime.date(2023, 1, 4), 1, 13, 'Example'), (datetime.date(2023, 1, 10), 1, 13, 'Example'), (datetime.date(2023, 1, 10), 1, 14, 'Example')]
ClickHouse Python version:  0.2.5

Python Console

This section shows how you can use the Python console to interactively connect to your ClickHouse cluster on Altinity and send SQL queries.

  • First copy your Connection Details from your cluster you want to communicate with.
  • Bring up the terminal and enter Python console mode, then copy and paste the following commands shown after the Python console prompt »>:
# Get into Python console mode
python3
>>>

# Getting the ClickHouse Python driver version number
>>> import clickhouse_driver
>>> print(clickhouse_driver.__version__)
0.2.5

# Connect to your ClickHouse cluster (replace <HOSTNAME> and <PASSWORD>)
>>> from clickhouse_driver import Client
>>> client = Client('<HOSTNAME>', user='admin', password=<PASSWORD>, port=9440, secure='y', verify=False)

# Confirm that the client object is created
>>> print(client)
<clickhouse_driver.client.Client object at 0x107730910>

# Show all tables
>>> client.execute('SHOW TABLES in default')
[('events',), ('events_local',)]

# Show data
>>> result = client.execute('SELECT * FROM default.events')
>>> print(result)
[(datetime.date(2023, 1, 4), 1, 13, 'Example'), (datetime.date(2023, 1, 10), 1, 13, 'Example'), (datetime.date(2023, 1, 10), 1, 14, 'Example')]

# ClickHouse Version 0.2.5 as of January 2023
version = (clickhouse_driver.__version__)
print("ClickHouse Python version: ", version)
ClickHouse Python version:  0.2.5

Checking your ClickHouse Version from PIP

To check your Python ClickHouse version installation from the terminal, enter:

  • pip show clickhouse-driver
username)   ~ 
username)   ~ pip show clickhouse-driver

        Name:  clickhouse-driver
     Version:  0.2.5
     Summary:  Python driver with native interface for ClickHouse
   Home-page:  https://github.com/mymarilyn/clickhouse-driver
      Author:  Konstantin Lebedev
Author-email:  kostyan.lebedev@gmail.com
     License:  MIT
    Location:  /Users/username/lib/python3.11/site-packages
    Requires:  pytz, tzlocal
 Required-by: 

This concludes the Quick Start instructions for how to use the Python3 ClickHouse driver.


Related links

9 - ClickHouse Macintosh (Monterey) Client

How to install the ClickHouse Python terminal client on a Macintosh running Monterey using the Brew package installer, and connect to your Altinity.Cloud ClickHouse Cluster.

26 January 2023 · Read time 4 min

Overview - Macintosh ClickHouse Client

This section covers the installation and use of the Mac ClickHouse client.
After installation, you will be able to run ClickHouse queries from a Macintosh terminal.
The following ClickHouse install instructions using Brew is tested to work on Monterey (OS version 12.1)

Prerequisites

  • You have copied the Connection Details from your cluster.
  • Python version 3.7 (or later) is installed
  • The PIP Python Package installer is installed
  • The Brew package installer is installed

More information

Installing ClickHouse on macOS

Installation of the macOS ClickHouse client uses the Brew package installer.

To install macOS ClickHouse client:

  1. Enter each of the four lines in turn. The final step starts ClickHouse.

    brew tap altinity/clickhouse
    brew tap-info --json altinity/clickhouse
    brew install clickhouse
    brew services start clickhouse
    

Checking the ClickHouse Version Installed

This step checks the installed version of the ClickHouse macOS client.
You will note that it is not necessary to login to ClickHouse to run this command.

To check the installed ClickHouse version from a macOS terminal:

  1. Enter the following string:

    clickhouse client -q 'SELECT version()'
    22.7.2.1
    

Note that you are still in the macOS shell, not the ClickHouse interactive mode, as the following examples demonstrate.

Logging on to your ClickHouse cluster

To login to your cluster from the macOS terminal:

  1. From the Connection Details, copy and paste the string of text into the macOS terminal:

    clickhouse-client -h example-cluster.your-cluster.altinity.cloud --port 9440 -s --user=admin --password
    

ClickHouse terminal response

  1. Enter your ClickHouse cluster password at the prompt.

  2. The ClickHouse version number is displayed, and the interactive prompt mode shows:
    example-cluster :)

    ClickHouse client version 22.7.2.1.
    
    Password for user (admin): 
    ********
    
    Connecting to example-cluster.your-cluster.altinity.cloud:9440 as user admin.
    Connected to ClickHouse server version 22.3.15 revision 54455.
    
    ClickHouse server version is older than ClickHouse client. 
    It may indicate that the server is out of date and can be upgraded.
    
    example-cluster :) 
    

Running ClickHouse Queries

To display all the tables in your cluster from a macOS terminal:

  1. At the ClickHouse prompt, enter the query command show tables:

    example-cluster :) show tables
    
    SHOW TABLES
    
    Query id: c04f8699-33db-4f4f-9a5b-e92fd25b6bb6
    
    Password for user (admin):
    Connecting to example-cluster.your-cluster.altinity.cloud:9440 as user admin.
    Connected to ClickHouse server version 22.3.15 revision 54455.
    
    ClickHouse server version is older than ClickHouse client. 
    It may indicate that the server is out of date and can be upgraded.
    
    ┌─name─────────┐
    │ events       │
    │ events_local │
    └──────────────┘
    
    2 rows in set. Elapsed: 0.073 sec.
    

To display the data in the in your cluster table named events from a macOS terminal:

  1. At the ClickHouse prompt, enter the query command select * from events:

    example-cluster :) select * from events
    
    SELECT *
    FROM events
    
    Query id: 998dbb3e-786e-404e-9d17-f044a6098191
    
    Password for user (admin):
    Connecting to example-cluster.your-cluster.altinity.cloud:9440 as user admin.
    Connected to ClickHouse server version 22.3.15 revision 54455.
    
    ClickHouse server version is older than ClickHouse client. 
    It may indicate that the server is out of date and can be upgraded.
    
    ┌─event_date─┬─event_type─┬─article_id─┬─title───┐
    │ 2023-01-04 │          113 │ Example │
    │ 2023-01-10 │          113 │ Example │
    │ 2023-01-10 │          114 │ Example │
    └────────────┴────────────┴────────────┴─────────┘
    
    3 rows in set. Elapsed: 0.074 sec.
    
    example-cluster :)
    

To quit, or exit from the ClickHouse interactive mode:

  1. Enter the exit command to return to your macOS shell environment.

    example-cluster :) exit
    Bye.
    

This concludes the Quick Start instructions for how to install and use the Macintosh ClickHouse terminal client.


Related links