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 Plans in the left navigation.

  3. Click Create cluster in the Serverless tab.

  4. Click Create Development Cluster.

  5. Select a region.

    For best performance, use a region that’s closest to your client application or data stores. The closer your clients and data are to the cluster, the lower the network latency.
  6. Give your cluster a memorable name. You cannot change your cluster name after it has been created.

It takes a few minutes to create a Viridian Serverless cluster. When the cluster state changes from Pending to Running, you can start using it.

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

  • Go

  • C++

  • SQL (CLI)

  1. Make sure that you have Java 8-17 installed and the JAVA_HOME environment variable is set to the location of your JRE.

  2. Sign into the Hazelcast Viridian console.

  3. Click Connect Client.

  4. Go to the Java tab and download the ZIP file.

  5. Extract the ZIP file and change into the extracted directory.

  6. Execute the application from your command prompt:

    When you see Connection Successful! in the output, the application is finished.

    1. Execute the following if you use Linux or Mac:

      ./mvnw clean compile exec:java@client-with-ssl
    2. Execute the following if you use Windows:

      mvnw.cmd clean compile exec:java@client-with-ssl
  7. In the Hazelcast Viridian console, go to Management Center and click SQL Browser in the top toolbar.

  8. Enter the following in the SQL Browser to create a mapping to the cities map. The sample client that you just executed created this map for you and filled it with data.

    CREATE OR REPLACE MAPPING cities (
    __key VARCHAR,
    country VARCHAR,
    city VARCHAR,
    population INT)
    type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');
  9. 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.
  1. Install Node.js 10 or newer.

  2. Go to the Node.js tab and download the ZIP file.

  3. Extract the ZIP file, change into the extracted root directory and execute the following command:

    npm run client_with_ssl

    When you see Connection Successful! in the output, the application is finished.

  4. In the Hazelcast Viridian console, go to Management Center and click SQL Browser in the top toolbar.

  5. Enter the following in the SQL Browser to create a mapping to the cities map. The sample client that you just executed created this map for you and filled it with data.

    CREATE OR REPLACE MAPPING cities (
    __key VARCHAR,
    country VARCHAR,
    city VARCHAR,
    population INT)
    type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');
  6. 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.
  1. Install Python 3.6 or newer.

  2. Go to the Python tab and download the ZIP file.

  3. Extract the ZIP file, change into the extracted root directory and execute the following command:

    python3 -m pip install -r requirements.txt && python client_with_ssl.py

    When you see Connection Successful! in the output, the application is finished.

  4. In the Hazelcast Viridian console, go to Management Center and click SQL Browser in the top toolbar.

  5. Enter the following in the SQL Browser to create a mapping to the cities map. The sample client that you just executed created this map for you and filled it with data.

    CREATE OR REPLACE MAPPING cities (
    __key VARCHAR,
    country VARCHAR,
    city VARCHAR,
    population INT)
    type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');
  6. 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.
  1. Install .NET.

  2. Go to the .Net tab and download the ZIP file.

  3. Extract the ZIP file, change into the extracted directory and execute the following command:

    dotnet run --project ClientWithSsl

    When you see Connection Successful! in the output, the application is finished.

  4. In the Hazelcast Viridian console, go to Management Center and click SQL Browser in the top toolbar.

  5. Enter the following in the SQL Browser to create a mapping to the cities map. The sample client that you just executed created this map for you and filled it with data.

    CREATE OR REPLACE MAPPING cities (
    __key VARCHAR,
    country VARCHAR,
    city VARCHAR,
    population INT)
    type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');
  6. 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.
  1. Install Go.

  2. Go to the Go tab and download the ZIP file.

  3. Extract the ZIP file, change into the extracted directory and execute the following command:

    go mod tidy && go run client_with_ssl.go

    When you see Connection Successful! in the output, the application is finished.

  4. In the Hazelcast Viridian console, go to Management Center and click SQL Browser in the top toolbar.

  5. Enter the following in the SQL Browser to create a mapping to the cities map. The sample client that you just executed created this map for you and filled it with data.

    CREATE OR REPLACE MAPPING cities (
    __key VARCHAR,
    country VARCHAR,
    city VARCHAR,
    population INT)
    type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');
  6. 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.
  1. Install vcpkg.

  2. Go to the C++ tab and download the ZIP file.

  3. Extract the ZIP file, change into the extracted directory, and execute the program:

    When you see Connection Successful! in the output, the application is finished.

    1. Execute the following if you use Linux or Mac:

      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. Execute the following 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.

  4. In the Hazelcast Viridian console, go to Management Center and click SQL Browser in the top toolbar.

  5. Enter the following in the SQL Browser to create a mapping to the cities map. The sample client that you just executed created this map for you and filled it with data.

    CREATE OR REPLACE MAPPING cities (
    __key VARCHAR,
    country VARCHAR,
    city VARCHAR,
    population INT)
    type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');
  6. 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.
  1. Install the Hazelcast CLI client. Use one of the following methods, depending on 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. Sign into the Hazelcast Viridian console.

  4. Click Connect Client.

  5. Go to the SQL tab and download the ZIP file.

  6. Extract the ZIP file.

    This file contains the credentials that allow the CLI to connect to your cluster.

  7. Change into the directory where you extracted the ZIP file.

  8. Connect to the SQL shell on your cluster.

    hz-cli -f hazelcast-client-with-ssl.yml sql

    You should see the SQL prompt:

    sql>
  9. Create a mapping to a new map called cities.

    CREATE OR REPLACE MAPPING cities (
    __key VARCHAR,
    country VARCHAR,
    city VARCHAR,
    population INT)
    type IMap OPTIONS('keyFormat'='varchar', 'valueFormat'='json-flat');
  10. Add some data to the map.

    INSERT INTO cities VALUES
    (1, 'United Kingdom','London', 9_540_576),
    (2, 'United Kingdom','Manchester', 2_770_434),
    (3, 'United States', 'New York', 19_223_191),
    (4, 'United States', 'Los Angeles', 3_985_520),
    (5, 'Turkey', 'Ankara', 5_309_690),
    (6, 'Turkey', 'Istanbul', 15_636_243),
    (7, 'Brazil', 'Sao Paulo', 22_429_800),
    (8, 'Brazil', 'Rio de Janeiro', 13_634_274);

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. Use the 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