Hazelcast Viridian Hello World
In this tutorial, you’ll learn how to connect a client to a cluster and use SQL to query data in the cluster.
Before you Begin
You need the following:
-
Access to a command prompt such as Terminal for Mac or Powershell for Windows.
Step 1. Start a Viridian Serverless Development Cluster
Development clusters are for fast, iterative development while you prototype your application. To create a development cluster, do the following:
-
Sign into the Hazelcast Viridian console.
-
Click Create New Cluster.
-
Click Create Development Cluster.
-
Update the cluster name if you want to. You cannot change the cluster name after the cluster is created.
-
Click Create Cluster.
-
Wait while your cluster is created. When the cluster is up and running, a Quick Connection Guide is displayed with instructions for connecting a sample client to it.
Step 2. Connect a Sample Client
To connect to your Viridian Serverless cluster, you need a Hazelcast client. The cluster comes with sample clients that are preconfigured to connect to your cluster and add some sample data to a map. A map is an in-memory, key/value data structure that is often used as a cache.
Choose a client and follow the instructions.
Before you begin:
-
Install Java 8-17 and set the
JAVA_HOME
environment variable to the location of your JRE. -
If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.
-
In the Quick Connection Guide on your cluster, click on the Java icon and then click Download.
-
Extract the ZIP file.
-
From a command prompt, change into the root directory of the extracted files.
-
Execute one of the following commands to run your client:
-
If you use Linux or Mac, execute:
./mvnw clean compile exec:java@client-with-ssl
-
If you use Windows, execute:
mvnw.cmd clean compile exec:java@client-with-ssl
When you see
Connection Successful!
in the output, the client is successfully connected to your Serverless cluster and populates acities
map with data.
-
-
To query data in the
cities
map:-
In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.
-
Continue to the next step to query your sample data in the SQL browser.
-
Take a moment, to read the code in the ClientWithSSL.java file to understand how the client connected.
|
Before you begin:
-
If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.
-
In the Quick Connection Guide, click on the NodeJS icon and then click Download.
-
Extract the ZIP file.
-
From a command prompt, change into the root directory of the extracted files.
-
Execute the following command to run your client:
npm run client_with_ssl
When you see
Connection Successful!
in the output, the client is successfully connected to your Serverless cluster and populates acities
map with data. -
To query data in the
cities
map:-
In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.
-
Continue to the next step to query your sample data in the SQL browser.
-
Take a moment, to read the code in the client_with_ssl.js file to understand how the client connected.
|
Before you begin:
-
If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.
-
In the Quick Connection Guide, click on the Python icon and then click Download.
-
Extract the ZIP file.
-
From a command prompt, change into the root directory of the extracted files.
-
Execute the following command to run your client:
python3 -m pip install -r requirements.txt && python client_with_ssl.py
When you see
Connection Successful!
in the output, the client is successfully connected to your Serverless cluster and populates acities
map with data. -
To query data in the
cities
map:-
In step 3 of the Quick Connection Guide on your cluster, click Dashboard.
-
In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.
-
Continue to the next step to query your sample data in the SQL browser.
-
Take a moment, to read the code in the client_with_ssl.py file to understand how the client connected.
|
Before you begin:
-
If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.
-
In the Quick Connection Guide, click on the .NET icon and then click Download.
-
Extract the ZIP file.
-
From a command prompt, change into the root directory of the extracted files.
-
Execute the following command to run your client:
dotnet run --project ClientWithSsl
When you see
Connection Successful!
in the output, the client is successfully connected to your Serverless cluster and populates acities
map with data. -
To query data in the
cities
map:-
In step 3 of the Quick Connection Guide on your cluster, click Dashboard.
-
In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.
-
Continue to the next step to query your sample data in the SQL browser.
-
Take a moment, to read the code in the program.cs file to understand how the client connected.
|
Before you begin:
-
If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.
-
In the Quick Connection Guide, click on the C++ icon and then click Download.
-
Extract the ZIP file.
-
From a command prompt, change into the root directory of the extracted files.
-
Execute one of the following commands to run your client:
-
If you use Linux or Mac, execute:
vcpkg install "hazelcast-cpp-client[openssl]" && cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake && cmake --build build && ./build/client_with_ssl
-
If you use Windows:
vcpkg install "hazelcast-cpp-client[openssl]" && cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake && cmake --build build && ./build/client_with_ssl
If the target triplet doesn’t match your operating system, you may need to provide a target suffix to the
install
command. For example:vcpkg install "hazelcast-cpp-client[openssl]:x64-windows"
The location of the compiled binary may change according to configuration and system defaults.
When you see
Connection Successful!
in the output, the client is successfully connected to your Serverless cluster and populates acities
map with data.
-
-
To query data in the
cities
map:-
In step 3 of the Quick Connection Guide on your cluster, click Dashboard.
-
In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.
-
Continue to the next step to query your sample data in the SQL browser.
-
Take a moment, to read the code in the client_with_ssl.cpp file to understand how the client connected.
|
Before you begin:
-
If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.
-
In the Quick Connection Guide, click on the C++ icon and then click Download.
-
Extract the ZIP file.
-
From a command prompt, change into the root directory of the extracted files.
-
Execute the following commands to run your client:
go mod tidy && go run client_with_ssl.go
When you see
Connection Successful!
in the output, the client is successfully connected to your Serverless cluster and populates acities
map with data. -
To query data in the
cities
map:-
In step 3 of the Quick Connection Guide on your cluster, click Dashboard.
-
In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.
-
Continue to the next step to query your sample data in the SQL browser.
-
Take a moment, to read the code in the client_with_ssl.go file to understand how the client connected.
|
If you’ve followed the onscreen Quick Connection Guide, jump straight to step 7.
-
Install the Hazelcast CLI client for your operating system.
Macbrew tap hazelcast/hz brew install hazelcast-enterprise
Linux 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-enterprise
Linux 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-enterprise
WindowsAt the moment, Hazelcast does not support any Windows package managers. The easiest way to use the CLI on Windows is to install the Hazelcast Enterprise Docker image. The Docker container comes with the
hz-cli
client. See Installing Hazelcast Enterprise. -
Check that the CLI client is installed.
hz-cli -V
You should see your installed version of the CLI client.
-
In the Quick Connection Guide, click the SQL icon and then click Download.
-
Extract the ZIP file which contains credentials that allow the Hazelcast CLI to connect to your cluster.
-
From a command prompt, change into the root directory where you extracted the ZIP file.
-
Execute the following command to connect the SQL shell to your cluster. You may need add a path to the hz-cli program.
hz-cli -f hazelcast-client-with-ssl.yml sql
A SQL prompt is displayed:
sql>
The Hazelcast CLI client is successfully connected to your Serverless cluster.
-
Create a mapping to a new map called
cities
.CREATE OR REPLACE MAPPING cities ( __key INT, country VARCHAR, city VARCHAR, population INT) type IMap OPTIONS('keyFormat'='int', 'valueFormat'='json-flat');
-
Add some data to the map.
INSERT INTO cities VALUES (1, 'United Kingdom','London', 9540576), (2, 'United Kingdom','Manchester', 2770434), (3, 'United States', 'New York', 19223191), (4, 'United States', 'Los Angeles', 3985520), (5, 'Turkey', 'Ankara', 5309690), (6, 'Turkey', 'Istanbul', 15636243), (7, 'Brazil', 'Sao Paulo', 22429800), (8, 'Brazil', 'Rio de Janeiro', 13634274);
-
Continue to the next step to query your sample data in the SQL browser.
Step 3. Query the Cache with SQL
Now that you have some data in your cluster, you can query it, using SQL. If you’re using the CLI, enter the following queries in the SQL prompt. If you’re using a client library, enter the following queries in the SQL browser.
-
Execute the following
SELECT
statement to query all data in the map.SELECT * FROM cities;
+------------+--------------------+--------------------+--------------+ | __key|country |city |population | +------------+--------------------+--------------------+--------------+ | 2|United Kingdom |Manchester |2770434 | | 6|Turkey |Ankara |5309690 | | 1|United Kingdom |London |9540576 | | 7|Brazil |Sao Paulo |22429800 | | 8|Brazil |Rio de Janeiro |13634274 | | 5|Turkey |Istanbul |15636243 | | 4|United States |Los Angeles |3985520 | | 3|United States |New York |19223191 | +------------+--------------------+--------------------+--------------+
The results are in a random order because the data is distributed across the cluster. Whenever a cluster member has the result, it returns it to the client.
-
Order the results by the key.
SELECT * FROM cities ORDER BY __key;
Now you see the results start from key 1 and end with key 8.
-
Query only the countries by filtering on the
countries
column.SELECT country FROM cities;
+--------------------+ |country | +--------------------+ |United Kingdom | |Turkey | |United Kingdom | |Brazil | |Brazil | |Turkey | |United States | |United States | +--------------------+
-
Query only the cities by filtering on the
cities
column.SELECT city FROM cities;
+--------------------+ |city | +--------------------+ |Manchester | |Ankara | |London | |Sao Paulo | |Rio de Janeiro | |Istanbul | |Los Angeles | |New York | +--------------------+
-
Change the output to display cities first in alphabetical order.
SELECT city, country FROM cities ORDER BY city;
+--------------------+--------------------+ |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 country FROM cities WHERE LENGTH(city) >= 11;
+--------------------+ |country | +--------------------+ |Brazil | |United States | +--------------------+
-
Use another filter to display only cities beginning with the letter 'L' where the length is greater than 6.
SELECT city FROM cities WHERE city LIKE 'L%' AND LENGTH(city) > 6;
+--------------------+ |City | +--------------------+ |Los Angeles | +--------------------+
Next Steps
Learn more about Serverless:
Try a tutorial.
Find out more about the SQL statements used in this tutorial:
Learn more about using clients: