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:

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:

  1. Sign into the Hazelcast Viridian console.

  2. Click Create New Cluster.

  3. Click Create Development Cluster.

  4. Update the cluster name if you want to. You cannot change the cluster name after the cluster is created.

  5. Click Create Cluster.

  6. 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.

  • Java

  • Node.js

  • Python

  • .NET

  • C++

  • Go

  • SQL (CLI)

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.

  1. In the Quick Connection Guide on your cluster, click on the Java icon and then click Download.

  2. Extract the ZIP file.

  3. From a command prompt, change into the root directory of the extracted files.

  4. Execute one of the following commands to run your client:

    1. If you use Linux or Mac, execute:

      ./mvnw clean compile exec:java@client-with-ssl

    2. 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 a cities map with data.

  5. To query data in the cities map, you need to create a mapping to it. In step 3 of the Quick Connection Guide on your cluster, click Dashboard.

  6. In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.

  7. Paste the following command into the SQL browser and execute it.

    CREATE OR REPLACE MAPPING cities (
__key VARCHAR,
country VARCHAR,
city VARCHAR,
population INT)
type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');

  8. 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. The client comes with some other examples that are commented out. To try those examples, you can uncomment them and run the application again.

Before you begin:

  1. In the Quick Connection Guide, click on the NodeJS icon and then click Download.

  2. Extract the ZIP file.

  3. From a command prompt, change into the root directory of the extracted files.

  4. 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 a cities map with data.

  5. To query data in the cities map, you need to create a mapping to it. In step 3 of the Quick Connection Guide on your cluster, click Dashboard.

  6. In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.

  7. Paste the following command into the SQL browser and execute it.

    CREATE OR REPLACE MAPPING cities (
__key VARCHAR,
country VARCHAR,
city VARCHAR,
population INT)
type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');

  8. 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. The client comes with some other examples that are commented out. To try those examples, you can uncomment them and run the application again.

Before you begin:

  1. In the Quick Connection Guide, click on the Python icon and then click Download.

  2. Extract the ZIP file.

  3. From a command prompt, change into the root directory of the extracted files.

  4. 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 a cities map with data.

To query data in the cities map, you need to create a mapping to it.

  1. In step 3 of the Quick Connection Guide on your cluster, click Dashboard.

  2. In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.

  3. Paste the following command into the SQL browser and execute it.

    CREATE OR REPLACE MAPPING cities (
__key VARCHAR,
country VARCHAR,
city VARCHAR,
population INT)
type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');

  4. 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. The client comes with some other examples that are commented out. To try those examples, you can uncomment them and run the application again.

Before you begin:

  • Install .NET.

  • If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.

  1. In the Quick Connection Guide, click on the .NET icon and then click Download.

  2. Extract the ZIP file.

  3. From a command prompt, change into the root directory of the extracted files.

  4. 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 a cities map with data.

To query data in the cities map, you need to create a mapping to it.

  1. In step 3 of the Quick Connection Guide on your cluster, click Dashboard.

  2. In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.

  3. Paste the following command into the SQL browser and execute it.

    CREATE OR REPLACE MAPPING cities (
__key VARCHAR,
country VARCHAR,
city VARCHAR,
population INT)
type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');

  4. 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. The client comes with some other examples that are commented out. To try those examples, you can uncomment them and run the application again.

Before you begin:

  • Install vcpkg.

  • If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.

  1. In the Quick Connection Guide, click on the C++ icon and then click Download.

  2. Extract the ZIP file.

  3. From a command prompt, change into the root directory of the extracted files.

  4. Execute one of the following commands to run your client:

    1. 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

    2. 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 a cities map with data.

To query data in the cities map, you need to create a mapping to it.

  1. In step 3 of the Quick Connection Guide on your cluster, click Dashboard.

  2. In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.

  3. Paste the following command into the SQL browser and execute it.

    CREATE OR REPLACE MAPPING cities (
__key VARCHAR,
country VARCHAR,
city VARCHAR,
population INT)
type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');

  4. 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. The client comes with some other examples that are commented out. To try those examples, you can uncomment them and run the application again.

Before you begin:

  • Install Go.

  • If you’ve followed the onscreen Quick Connection Guide, jump straight to step 6.

  1. In the Quick Connection Guide, click on the C++ icon and then click Download.

  2. Extract the ZIP file.

  3. From a command prompt, change into the root directory of the extracted files.

  4. 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 a cities map with data.

To query data in the cities map, you need to create a mapping to it.

  1. In step 3 of the Quick Connection Guide on your cluster, click Dashboard.

  2. In Cluster Details, click Management Center, and then from the top toolbar click SQL Browser.

  3. Paste the following command into the SQL browser and execute it.

    CREATE OR REPLACE MAPPING cities (
__key VARCHAR,
country VARCHAR,
city VARCHAR,
population INT)
type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');

  4. 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. The client comes with some other examples that are commented out. To try those examples, you can uncomment them and run the application again.

If you’ve followed the onscreen Quick Connection Guide, jump straight to step 7.

  1. Install the Hazelcast CLI client for your operating system.

    Mac
    brew tap hazelcast/hz
brew install hazelcast-enterprise
    Linux 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-enterprise
    Linux 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-enterprise
    Windows

    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 Enterprise Docker image. The Docker container comes with the hz-cli client. See Installing Hazelcast Enterprise.

  2. Check that the CLI client is installed.

    hz-cli -V

    You should see your installed version of the CLI client.

  3. In the Quick Connection Guide, click the SQL icon and then click Download.

  4. Extract the ZIP file which contains credentials that allow the Hazelcast CLI to connect to your cluster.

  5. From a command prompt, change into the root directory where you extracted the ZIP file.

  6. 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.

  7. 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');

  8. 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);

  9. 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.

  1. 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.

  2. 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.

  3. 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       |
+--------------------+

  4. 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            |
+--------------------+

  5. 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              |
+--------------------+--------------------+

  6. 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       |
+--------------------+

  7. 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         |
+--------------------+

Summary

You learned how to connect to a cluster and use SQL to query data in the cluster.

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: