Hazelcast Cloud Quickstart

Follow this five-minute tutorial to set up a Hazelcast cluster in the cloud. In five minutes, you will learn how to create a cluster, connect to the SQL shell, and use SQL to write data to memory and query that data.

To run a Hazelcast cluster on your local machine instead, see Start a Local Cluster with the CLI.

Step 1. Create a Cluster

Sign up for a Hazelcast Cloud account.
Create a free cluster on the Basic plan. For help creating a cluster, see Create a Hazelcast Cloud Cluster.

Don’t enable encryption on your cluster. At the moment, you can’t connect the CLI to a Hazelcast Cloud cluster if encryption is enabled.

Step 2. Download the CLI Client

Go to Your Clusters and click your cluster.
Click Connect your Application and open the SQL tab.

Download and unzip the client configuration file.

This file contains the credentials that allow the CLI to connect to your Hazelcast Cloud cluster:

hazelcast-client:
  cluster-name: {your-cluster-name} (1)
  network:
    hazelcast-cloud:
      enabled: true (2)
      discovery-token: {your-discovery-token} (3)
  metrics:
    enabled: true (4)

1	The name of your cluster, which you can find in the Credentials section
2	This field tells the client that it is connecting to a Hazelcast Cloud cluster.
3	Your discovery token, which you can find in the Credentials section.
4	This field tells the client to send metrics to the cluster so that they can be displayed in Hazelcast Cloud and/or used by other applications such as Management Center.

Make a note of where you extracted the client configuration file.

Install the Hazelcast CLI client. Use one of the following methods, depending on your operating system.

The CLI client may appear quite large because it is packaged with the full distribution of Hazelcast, Management Center, and a JDK. We are working on a new CLI client that will be more lightweight.

Mac
Linux
Windows

To install the CLI on macOS, use the Homebrew package manager.

brew tap hazelcast/hz
brew install hazelcast

To install the CLI on Linux, you can use either of these package managers, depending on your Linux distribution:

Debian

wget -qO - https://repository.hazelcast.com/api/gpg/key/public | sudo apt-key add -
echo "deb https://repository.hazelcast.com/debian stable main" | sudo tee -a /etc/apt/sources.list
sudo apt update && sudo apt install hazelcast

RPM

wget https://repository.hazelcast.com/rpm/hazelcast-rpm.repo -O hazelcast-rpm.repo
sudo mv hazelcast-rpm.repo /etc/yum.repos.d/
sudo yum install hazelcast

At the moment, Hazelcast does not support any Windows package managers.

The easiest way to use the CLI on Windows is to install the Hazelcast Docker image. The Docker container comes with the hz-cli client. See Installing Hazelcast Open Source

Check that the CLI client is installed.
```
hz-cli -V
```
You should see your installed version of the CLI client.

Step 3. Connect to the SQL Shell

Go to the directory where you extracted the client configuration file.
Connect to the SQL shell on your Hazelcast Cloud cluster.
```
hz-cli -f hazelcast-client.yml sql
```
The -f flag passes the configuration file to the CLI client so that the cluster can authenticate the client, using the credentials.

You should see the SQL prompt:

sql>

Step 4. Create a Mapping to a Map

Before you can query data in a map, you need to create a mapping to one, using the map connector.

In the SQL shell, configure the map connector to set up an SQL connection to a new map called cities.

CREATE MAPPING cities (
__key INT,
countries VARCHAR,
cities VARCHAR)
type IMap OPTIONS('keyFormat'='int', 'valueFormat'='json-flat');

Add some countries and their capital cities to the map.

INSERT INTO cities VALUES
(1, 'United Kingdom','London'),
(2, 'United Kingdom','Manchester'),
(3, 'United States', 'New York'),
(4, 'United States', 'Los Angeles'),
(5, 'Turkey', 'Ankara'),
(6, 'Turkey', 'Istanbul'),
(7, 'Brazil', 'Sao Paulo'),
(8, 'Brazil', 'Rio de Janeiro');

The first argument of the VALUES command is the key of the map entry and the second argument is the value.

Step 5. Run Ad-Hoc Queries

Use the SELECT statement to query all data in the map.

SELECT * FROM cities;

You should see the following:

+------------+--------------------+--------------------+
|       __key|countries           |cities              |
+------------+--------------------+--------------------+
|           2|United Kingdom      |Manchester          |
|           6|Turkey              |Ankara              |
|           1|United Kingdom      |London              |
|           7|Brazil              |Sao Paulo           |
|           8|Brazil              |Rio de Janeiro      |
|           5|Turkey              |Istanbul            |
|           4|United States       |Los Angeles         |
|           3|United States       |New York            |
+------------+--------------------+--------------------+

Query only the countries by filtering on the countries column.

SELECT countries FROM cities;

+--------------------+
|countries           |
+--------------------+
|United Kingdom      |
|Turkey              |
|United Kingdom      |
|Brazil              |
|Brazil              |
|Turkey              |
|United States       |
|United States       |
+--------------------+

Query only the cities by filtering on the cities column.

SELECT cities FROM cities;

+--------------------+
|cities              |
+--------------------+
|Manchester          |
|Ankara              |
|London              |
|Sao Paulo           |
|Rio de Janeiro      |
|Istanbul            |
|Los Angeles         |
|New York            |
+--------------------+

Change the output to display cities first in alphabetical order. The AS command renames the columns to the given aliases.

This clause does not rename the column in the table.

SELECT cities AS City, countries AS Country
FROM cities
ORDER BY cities;

+--------------------+--------------------+
|City                |Country             |
+--------------------+--------------------+
|Ankara              |Turkey              |
|Istanbul            |Turkey              |
|London              |United Kingdom      |
|Los Angeles         |United States       |
|Manchester          |United Kingdom      |
|New York            |United States       |
|Rio de Janeiro      |Brazil              |
|Sao Paulo           |Brazil              |
+--------------------+--------------------+

Use a filter to display only countries where the name of the city is at least 11 characters long.

SELECT countries FROM cities WHERE LENGTH(cities) >= 11;

+--------------------+
|countries           |
+--------------------+
|Brazil              |
|United States       |
+--------------------+

Use another filter to display only cities beginning with the letter 'L' where the length is greater than 6.

SELECT cities AS City
FROM cities
WHERE cities LIKE 'L%' AND LENGTH(cities) > 6;

+--------------------+
|City                |
+--------------------+
|Los Angeles         |
+--------------------+

Configure the map connector to create a new map table called population2020.

CREATE MAPPING population2020 (
__key INT,
cities VARCHAR,
population INT)
TYPE IMap OPTIONS ('keyFormat'='int', 'valueFormat'='json-flat');

Add the 2020 populations of the following cities.

INSERT INTO population2020 VALUES
(1, 'London', 9304016),
(2, 'Manchester', 2730076),
(3, 'New York', 8622357),
(4, 'Los Angeles', 4085014),
(5, 'Sao Paulo', 12396372),
(6, 'Rio de Janeiro', 6775561),
(7, 'Istanbul', 14804116),
(8, 'Ankara', 3517182);

Use the JOIN clause to merge results from the cities and population2020 tables so you can see which countries had the most populated captial cities in 2020.

SELECT cities.countries AS country, cities.cities AS city, population2020.population AS population
FROM cities
JOIN population2020
ON cities.cities = population2020.cities;

+--------------------+--------------------+------------+
|country             |city                |  population|
+--------------------+--------------------+------------+
|United Kingdom      |Manchester          |     2730076|
|Turkey              |Ankara              |     3517182|
|United Kingdom      |London              |     9304016|
|Brazil              |Sao Paulo           |    12396372|
|Brazil              |Rio de Janeiro      |     6775561|
|Turkey              |Istanbul            |    14804116|
|United States       |Los Angeles         |     4085014|
|United States       |New York            |     8622357|
+--------------------+--------------------+------------+

Use the ORDER BY clause to order the results by population, largest first.

SELECT cities.countries AS country, cities.cities AS city, population2020.population AS population
FROM cities
JOIN population2020
ON cities.cities = population2020.cities
ORDER BY population2020.population DESC;

+--------------------+--------------------+------------+
|country             |city                |  population|
+--------------------+--------------------+------------+
|Turkey              |Istanbul            |    14804116|
|Brazil              |Sao Paulo           |    12396372|
|United Kingdom      |London              |     9304016|
|United States       |New York            |     8622357|
|Brazil              |Rio de Janeiro      |     6775561|
|United States       |Los Angeles         |     4085014|
|Turkey              |Ankara              |     3517182|
|United Kingdom      |Manchester          |     2730076|
+--------------------+--------------------+------------+

Use the SUM() function to find the total population of all the cities in 2020.

SELECT SUM(population2020.population) AS total_population
FROM population2020;

You should see the following:

+--------------------+
|    total_population|
+--------------------+
|            62234694|
+--------------------+

Filter for cities that had a population of more than 5,000,000 in 2020.

SELECT population2020.cities AS large_cities
FROM population2020
WHERE population2020.population > 5000000;

+--------------------+
|large_cities        |
+--------------------+
|New York            |
|Rio de Janeiro      |
|London              |
|Istanbul            |
|Sao Paulo           |
+--------------------+

Display the names of countries and the sum of the city populations. Order by population in ascending order.

SELECT cities.countries AS country, SUM(population2020.population) AS total_population
FROM cities
JOIN population2020
ON cities.cities = population2020.cities
GROUP BY cities.countries
ORDER by sum(population2020.population);

+--------------------+--------------------+
|country             |    total_population|
+--------------------+--------------------+
|United Kingdom      |            12034092|
|United States       |            12707371|
|Turkey              |            18321298|
|Brazil              |            19171933|
+--------------------+--------------------+

Display the names of countries and the sum of the city populations where the sum is > 15000000.

SELECT cities.countries AS country, sum(population2020.population) AS total_population
FROM cities
JOIN population2020
ON cities.cities = population2020.cities
GROUP BY cities.countries HAVING SUM(population2020.population) > 15000000;

+--------------------+--------------------+
|country             |    total_population|
+--------------------+--------------------+
|Turkey              |            18321298|
|Brazil              |            19171933|
+--------------------+--------------------+

The HAVING clause allows you to filter aggregations like you would with the WHERE clause for non-aggregated queries.

Next Steps

Build an application with one of our clients:

Find out more about the statements used in this tutorial:

Explore all available SQL statements.