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.

A full PDF version of this document is available through this link: Quick Start Guide PDF

1 - Account Creation and Login

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

Create an Account

To start your Altinity.Cloud journey, the first thing you need is an account. New users can sign up for a test account on the Altinity.Cloud Test Drive page. Enter your contact information, and an Altinity.Cloud rep will get right with you.

Once finished, the Altinity.Cloud team will reach out to you with your login credentials. Altinity.Cloud uses your email address as your username, and you’ll be assigned an initial password.

Login to Altinity.Cloud

There are two methods to login:

Login with Username and Password

If you’ve used any web site, you’re likely familiar with this process.

To login to Altinity.Cloud with your username and password:

  1. Enter your username - in this case your email address - in the field marked Login.
  2. Enter your Password, then click Sign In.

Login with Auth0

Auth0 allows you to authenticate to Altinity.Cloud through a trusted authentication provider, in this case Google. Once set up, you can click Auth0 authenticate through your Google account.

  • Requirements: In order to use Auth0, you must have a Google account with the same email address that you use for Altinity.Cloud.

To setup authentication with Auth0 for the first time:

  1. Access the Altinity.Cloud page.
  2. Select Auth0.
  3. Select the Google account to use for authentication.
    IMPORTANT NOTE: The Google account must have the same email address as your Altinity.Cloud account.
  4. Select Continue with Google, and you’ll be in Altinity.Cloud.

After you’ve completed the Auth0 setup process, you can login to Altinity.Cloud by selecting Auth0 from the login page.

2 - Explore Clusters View

An overview of managing your ClickHouse clusters with Altinity.Cloud.

Explore Clusters View

Once you’ve logged in to Altinity.Cloud, let’s take a moment and familiarize ourselves with the environment. The default page is the Clusters View.

The Clusters View page is separated into the following sections:

Clusters View
  • A: Cluster Creation: Clusters can be created from scratch with Launch Cluster.
  • B: Clusters: Each cluster associated with your Altinity.Cloud account is listed in either tile format, or as a short list. They’ll display a short summary of their health and performance. By selecting a cluster, you can view the full details.
  • C: User and Environment Management:
    • Change to another environment.
    • Manage environments and zookeepers.
    • Update account settings.

3 - Create Your First Cluster

How to create your first ClickHouse cluster with Altinity.Cloud.

Time to make your first cluster! For this example, we’re creating a minimally sized cluster, but you can rescale your cluster later to make it the exact size you need for your ClickHouse needs.

As of October 21, 2021, Altinity.Cloud supports Google Compute Platform (GCP) and Amazon Web Services (AWS). For more information, see the Altinity.Cloud Administrator Guide.

To create your first cluster:

  1. From the Clusters View page, select Launch Cluster. This starts the Cluster Launch Wizard.

  2. The first page is Resources Configuration, where we set the name, size and authentication for the new cluster. When finished, click Next. Use the following settings:

    Setting Value
    Name Cluster names will be used to create the DNS name of the cluster. Therefore, cluster names must follow DNS name restrictions (letters, numbers, and dashes allowed, periods and special characters are not).
    Cluster names must start with a letter, and should be 15 characters at most.
    Node Type Select m5.large
    This is the size of the node. This selection gives us a cluster with 2 CPUs and around 7 GB RAM. Recall that we can rescale this cluster later. For more information, see the Administrator Guide.
    Node Storage Set to 30 GB.
    The size of each Cluster node in GB (gigabytes). Each node will have the same storage area.
    Number of Volumes Set to 1.
    Network storage can be split into separate volumes. Use more volumes to increase query performance.
    Volume Type Select gp2 (Not Encrypted).
    Volumes can be either encrypted or unencrypted, depending on your security requirements.
    Number of Shards Set to 1.
    The shard represents a set of nodes. Shards can then be replicated to provide increased availability and recovery.
    ClickHouse Version Select the most recent Altinity Stable Build.
    Your ClickHouse cluster can use the version that best meets your needs. Note that all nodes will run the same ClickHouse version.
    ClickHouse User Name Auto-set to admin.
    The default administrative user.
    ClickHouse User Password and Confirm Password Set to your security requirements. Both the ClickHouse User Password and Confirm Password must match.
  3. The next page is High Availability Configuration. This is where you can set your replication, Zookeeper, and backup options. Use the following values for your first cluster, then click Next to continue:

    Setting Value
    Data Replication Set to Enabled.
    Data replication duplicates data across replica clusters for increased performance and availability.
    Number of Replicas Set to 2.
    Only required if Data Replication is Enabled.
    Sets the number of replicas for each cluster shard.
    Zookeeper Configuration The only option at this time is Dedicated
    Apache Zookeeper manages synchronization between the clusters.
    Zookeeper Node Type Default is selected by default.
    Enable Backups Set to Enabled by default and cannot be disabled as of this time.
    Backup Schedule and Number of Backups to keep Is set to Daily and 5, and can not be changed as of this time.
  4. The Connection Configuration page determines how to communicate with your new cluster. Set the following values, then select Next to continue:

    Setting Value
    Endpoint This is automatically set based on your cluster name. It will display the final DNS name for your cluster end point.
    Use TLS Set to Enabled.
    When enabled, communications with your cluster are encrypted with TLS.
    Load Balancer Type Select Altinity Edge Ingress.
    IMPORTANT NOTE: This setting requires clients to support SNI (Server Name Indication). This will require the most current ClickHouse client and Python clickhouse-driver.
    This setting cannot be changed after the cluster is created.
    1. Protocols can restrict communications to the Altinity.Cloud cluster based on your organizations needs. By default **Binary Protocol (port:9440) and HTTP Protocol (port: 8443) are enabled.
    2. Datadog integration: Not enabled at this time. Stay tuned for future developments.
    3. IP restrictions: Restrict IP communications to the cluster to specific IP addresses. For more information, see the Administrator Guide. Leave blank for now.
  5. Last page! Review & Launch lets you double check your settings and see the estimated cluster cost. When you’re ready, click Launch.

It will take a little while before your new cluster is ready, so grab your coffee or tea or other hydrating beverage. When it’s complete, you’ll see your new cluster with all nodes online and all health checks passed.

4 - Your First Queries

How to use Cluster Explore to run queries, view table structures and available processes.

Once your cluster is created, time to create some tables and do some queries.

For those experienced with ClickHouse, this will be very familiar. For people who are new to ClickHouse, creating tables is very similar to other SQL based databases, with some extra syntax that defines the type of table we’re making. This is part of what gives ClickHouse its speed. For complete details on ClickHouse commands, see the ClickHouse SQL Reference Guide.

Cluster Explore

The Cluster Explore page allows you to run queries, view the schema, and check on processes for your cluster. It’s a quick way of getting into your ClickHouse database, run commands and view your schema straight from your web browser. We’ll be using this to generate our first tables and input some data.

To access Cluster Explore for your cluster, just click Explore for the specific cluster to manage.

For our example, we’re going to create two tables:

  • events_local: This table will use the ReplicatedMergeTree table engine. If you don’t know about table engines, don’t worry about that for now. See the ClickHouse Engines page for complete information.
  • events: This table will be distributed on your cluster with the Distributed table engine.

In our examples, we’ll be using macro variables - these are placed between curly brackets and let us use the same SQL commands on different clusters and environments without having to fill in every detail. Any time you see an entry like {cluster} or {shard} you should recognize those as a macro variable.

The commands below will create these tables into the default database on your cluster.

Create Tables

To create your first tables:

  1. From the Clusters View select Explore for the cluster to manage.

  2. The Query tab is selected by default. (This may change in future releases.)

  3. For our first table, copy and paste the following into the Query window, then select 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);
    

    You should see the following under Execute confirming the command ran, just replacing docdemo with your cluster:

    docdemo.demo.beta.altinity.cloud:8443 (query time: 0.342s)
    chi-docdemo-docdemo-0-0	9000 0	 	1	0
    chi-docdemo-docdemo-0-1	9000 0	 	0	0
    
  4. Now let’s create our second table. Back in the Query window, enter the following and select Execute:

    CREATE TABLE events ON CLUSTER '{cluster}' AS events_local
        ENGINE = Distributed('{cluster}', default, events_local, rand())
    

    Once again, you should see confirmation under Execute:

    docdemo.demo.beta.altinity.cloud:8443 (query time: 0.162s)
    chi-docdemo-docdemo-0-0	9000 0	 	1	0
    chi-docdemo-docdemo-0-1	9000 0	 	0	0
    
  5. Now that we have some tables, let’s not leave them empty. Inserting data into a ClickHouse table is very similar to most SQL systems. Let’s Insert our data, then do a quick Select on it. Enter the following Insert command into Query, then select Execute:

    INSERT INTO events VALUES(today(), 1, 13, 'Example');
    

    You’ll see the results confirmed under Execute, just like before.

    OK.
    

    Then enter the following Select command and select Execute again:

    SELECT * FROM events;
    

    The results will look like the following:

    docdemo.demo.beta.altinity.cloud:8443 (query time: 0.018s)
    ┌─event_date─┬─event_type─┬─article_id─┬─title───┐
    │ 2020-11-19 │          113 │ Example │
    └────────────┴────────────┴────────────┴─────────┘
    

View Schema

The Database Schema shows a graphical view of your cluster’s database, the tables in it, and their structure.

To view your Schema:

  1. From the Clusters View select Explore for the cluster to manage.
  2. Select Schema.

You can expand the databases to display the tables in each database, or select the table to view its details, schema, and some sample rows.

View Processes

To view current actions running on your cluster select Processes. This displays what processes are currently running, what user account they are running under, and allows you to view more details regarding the process.

5 - Connect Remote Clients

How to install the command line and Python clients, and connect to your Altinity.Cloud ClickHouse Cluster.

Now that we’ve shown how to create a cluster and use ClickHouse SQL queries into your new cluster, let’s connect to it remotely.

For the following, we’re going to be using the clickhouse-client program, but the same process will help you gain access from your favorite client.

Full instructions for installing ClickHouse can be found on the ClickHouse Installation page. We’ll keep this simple and assume you’re using a Linux environment like Ubuntu. For this example, we set up a virtual machine running Ubuntu 20.04.

First, we need to know our connection details for our Altinity.Cloud ClickHouse cluster. To view your connection details:

  1. From the Clusters View, select Connection Details for the cluster to manage.

  2. From here, you can copy and paste the settings for the ClickHouse client from your cluster’s Connection Details. For example:

    clickhouse-client -h yourdataset.yourcluster.altinity.cloud --port 9440 -s --user=admin --password
    

ClickHouse Client

The ClickHouse Client is a command line based program that will be familiar to SQL based users.

Setting Up ClickHouse Client in Linux

If you’ve already set up ClickHouse client, then you can skip this step. These instructions are modified from the Altinity Stable Builds Quick Start Guides to quickly get a ClickHouse client running on your system.

Deb Linux Based Installs

For those who need quick instructions on how to install ClickHouse client in their deb based Linux environment (like Ubuntu), use the following:

  1. Update the apt-get local repository:

    sudo apt-get update
    
  2. Install the Altinity package signing keys:

    sudo sh -c 'mkdir -p /usr/share/keyrings && curl -s https://builds.altinity.cloud/apt-repo/pubkey.gpg | gpg --dearmor > /usr/share/keyrings/altinity-dev-archive-keyring.gpg'
    
  3. Update the apt-get repository to include the Altinity Stable build repository with the following commands:

    sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/altinity-dev-archive-keyring.gpg] https://builds.altinity.cloud/apt-repo stable main" > /etc/apt/sources.list.d/altinity-dev.list'
    
    sudo apt-get update
    
  4. Install the most current version of the Altinity Stable Build for ClickHouse client with the following:

    sudo apt-get install clickhouse-client
    

macOS Based Installs

For macOS users, the Altinity Stable for ClickHouse client can be installed through Homebrew with the through the Altinity Homebrew Tap for ClickHouse with the following quick command:

brew install altinity/clickhouse/clickhouse

Connect With ClickHouse Client

If your ClickHouse client is ready, then you can copy and paste your connection settings into your favorite terminal program, and you’ll be connected.

clickhouse-client to Altinity.Cloud demo

ClickHouse Python Driver

Users who prefer Python can use the clickhouse-driver to connect through Python. These instructions are very minimal, and are intended just to get you working in Python with your new Altinity.Cloud cluster.

These instructions are in the bash shell and require the following be installed in your environment:

  • Python 3.7 and above

  • The Python module venv

  • git

  • IMPORTANT NOTE: Install the clickhouse-driver 0.2.0 or above which has support for Server Name Indication (SNI) when using TLS communications.

To connect with the Python clickhouse-driver:

  1. (Optional) Setup your local environment. For example:

    python3 -m venv test 
    . test/bin/activate
    
  2. Install the driver with pip3:

    pip3 install clickhouse-driver
    
  3. Start Python.

  4. Add the client and connection details. The Access Point provides the necessary information to link directly to your cluster.

    AltinityCloud Cluster Connection Details

    Import the clickhouse_driver client and enter the connection settings:

    from clickhouse_driver import Client
    client = Client('<HOSTNAME>', user='admin', password=<PASSWORD>, port=9440, secure='y', verify=False)
    
  5. Run client.execute and submit your query. Let’s just look at the tables from within Python:

    >>> client.execute('SHOW TABLES in default')
    [('events',), ('events_local',)]
    
  6. You can perform selects and inserts as you need. For example, continuing from our Your First Queries using Cluster Explore.

    >>> result = client.execute('SELECT * FROM default.events')
    >>> print(result)
    [(datetime.date(2020, 11, 23), 1, 13, 'Example')]
    

For more information see the article ClickHouse And Python: Getting To Know The ClickHouse-driver Client.

6 - Conclusion

Closing instructions for the Altinity.Cloud Quick Start Guide.

There are several ways of running ClickHouse to take advantage of the robust features and speed in your big data applications. Altinity.Cloud makes it easy to start up a cluster the way you need, manage it, and connect to it so you can go from concept to execution in the fastest way possible.

If you have any questions, please feel free to Contact Us at any time.

7 - FAQ

Frequently Asked Questions

When using Launch Cluster, I can’t Click Next or complete the process

Make sure that all of your settings are filled in. Some common gotchas are:

  • Make sure that the ClickHouse User Password field has been entered and confirmed.
  • Cluster names must follow DNS name restrictions (letters, numbers, and dashes allowed, periods and special characters are not).
  • Cluster names must start with a letter, and should be 15 characters at most.