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
-
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. 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:
Debianwget -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
RPMwget 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 thecities
andpopulation2020
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 theWHERE
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.