Clients

Hazelcast Go Client

Hazelcast is a feature-rich and developer-friendly in-memory caching solution for your Go applications.

  • Access Hazelcast data structures plus distributed queues, topics, and more with the Hazelcast Go Client.
  • Declarative configuration support via JSON.
  • SQL support.
  • High-performance aggregation functions, such as sum, average, max, and min, for Hazelcast Map entries. They can run in parallel for each partition and are highly optimized for speed and low-memory consumption.

Quick Start + Download

Quick Start

Get Hazelcast.

Use the following command to install the Hazelcast Go client:

go get github.com/hazelcast/hazelcast-go-client

Next steps:

 

Downloads
Version Downloads Documentation
Hazelcast IMDG Go Client 1.2.0 (latest)
07/05/2022
Hazelcast IMDG Go Client 1.1.1
11/09/2021
Hazelcast IMDG Go Client 1.1.0
09/14/2021
Hazelcast IMDG Go Client 1.0.0
06/13/2021

For all downloads please see the Download Archives

Previous Releases

Code Samples

package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the map.
	myMap, err := client.GetMap(ctx, "my-map")
	if err != nil {
		panic(err)
	}
	// Set a value in the map.
	err = myMap.Set(ctx, "some-key", "some-value")
	if err != nil {
		panic(err)
	}
	// Get the value back and print it.
	value, err := myMap.Get(ctx, "some-key")
	if err != nil {
		panic(err)
	}
	fmt.Println("Got the value back:", value)
}
package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the replicated map.
	myMap, err := client.GetReplicatedMap(ctx, "my-replicated-map")
	if err != nil {
		panic(err)
	}
	// Put a value in the map and retrieve the previous value.
	oldValue, err := myMap.Put(ctx, "some-key", "some-value")
	if err != nil {
		panic(err)
	}
	fmt.Println("Previous value:", oldValue)
	// Get the value back and print it.
	value, err := myMap.Get(ctx, "some-key")
	if err != nil {
		panic(err)
	}
	fmt.Println("Got the value back:", value)
}
package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the multi map.
	myMap, err := client.GetMultiMap(ctx, "my-multi-map")
	if err != nil {
		panic(err)
	}
	// Put values in the map with the same key.
	err = myMap.PutAll(ctx, "some-key", "some-value-1", "some-value-2", "some-value-3")
	if err != nil {
		panic(err)
	}
	// Get the values back and print it.
	values, err := myMap.Get(ctx, "some-key")
	if err != nil {
		panic(err)
	}
	fmt.Println("Got the values back:", values)
}
package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the set.
	mySet, err := client.GetSet(ctx, "my-set")
	if err != nil {
		panic(err)
	}
	// Add items to set.
	// Note that value1 is added twice.
	changed, err := mySet.AddAll(ctx, "value1", "value2", "value1", "value3")
	if err != nil {
		panic(err)
	}
	fmt.Println("Was the set changed?", changed)
	// Print contents of the set
	items, err := mySet.GetAll(ctx)
	if err != nil {
		panic(err)
	}
	// Get the items back and print them.
	fmt.Println("Got the items back:", items)
}
package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the list.
	myList, err := client.GetList(ctx, "my-list")
	if err != nil {
		panic(err)
	}
	_, err = myList.AddAll(ctx, "tic", "toc")
	if err != nil {
		panic(err)
	}
	// Get and print list items.
	items, err := myList.GetAll(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Println("List items:", items)
} 
package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
)

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the queue.
	myQueue, err := client.GetQueue(ctx, "my-queue")
	if err != nil {
		panic(err)
	}
	// Add an item to the queue if space is available (non-blocking).
	added, err := myQueue.Add(ctx, "item 1")
	if err != nil {
		panic(err)
	}
	fmt.Println("Added?", added)
	// Get the head of the queue if available and print item.
	item, err := myQueue.Poll(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Println("Got item:", item)
}
package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
)

// messageListener handles incoming messages to the topic.
func messageListener(event *hazelcast.MessagePublished) {
	fmt.Println("Received message: ", event.Value)
}

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the queue.
	myTopic, err := client.GetTopic(ctx, "my-topic")
	if err != nil {
		panic(err)
	}
	// Add a message listener to the topic.
	_, err = myTopic.AddMessageListener(ctx, messageListener)
	if err != nil {
		panic(err)
	}
	// Publish messages to topic
	for i := 0; i < 10; i++ {
		err = myTopic.Publish(ctx, fmt.Sprintf("Message %d", i))
		if err != nil {
			panic(err)
		}
	}
	// Shutdown the client.
	client.Shutdown(ctx)
}
package main

import (
	"context"
	"fmt"

	"github.com/hazelcast/hazelcast-go-client"
	"github.com/hazelcast/hazelcast-go-client/predicate"
	"github.com/hazelcast/hazelcast-go-client/serialization"
)

func main() {
	ctx := context.TODO()
	// Start the client with defaults.
	client, err := hazelcast.StartNewClient(ctx)
	if err != nil {
		panic(err)
	}
	// Get a reference to the map.
	myMap, err := client.GetMap(ctx, "my-map")
	if err != nil {
		panic(err)
	}
	// Populate the map, error handling is omitted here for brevity
	_ = myMap.Set(ctx, "key-1", serialization.JSON(`{"property: 5}`))
	_ = myMap.Set(ctx, "key-2", serialization.JSON(`{"property": 10}`))
	_ = myMap.Set(ctx, "key-3", serialization.JSON(`{"property": 15}`))
	// Filter the entries in the map based on a predicate and print those.
	pred := predicate.And(predicate.Greater("property", 8), predicate.Less("property", 12))
	entries, err := myMap.GetEntrySetWithPredicate(ctx, pred)
	if err != nil {
		panic(err)
	}
	fmt.Println(entries)
}

Roadmap

Upcoming Go Client Features
  • Hazelcast Serialization 2.0 Support: Querying friendly and space-efficient serialization that has high usability.
  • Backup Acknowledgment: Significantly improved client performance by eliminating the sync backup wait from the client and send the backup ACK to the client.
  • CP Subsystem Support: New Concurrency APIs including FencedLock, AtomicLong, Semaphore, CountDownLatch, and AtomicReference.
Recently Released Go Features
  • SQL Support: Execute SQL queries on Hazelcast.
  • Blue/Green Failover Config: Support of the blue/green deployment and disaster recovery features.
  • External Smart Client Discovery via Load Balancer: Adds a new discovery mechanism that allows the smart client to decide whether it needs to use public addresses for communication with members. As a result, the client does not need a dedicated plugin to communicate with a cluster running on a cloud environment where members are exposed via a load balancer.
  • Connection strategy configuration
  • Go Context Support for all distributed data structures.
  • Data structures including Flake ID Generator and PNCounter.
  • Go Module Support: Allow users to grab a specific client version rather than the master one.
  • More idiomatic API
  • Hazelcast 4 and 5 Compatibility: Client protocol enhancements, architectural improvements, Serialization improvements.
  • Ownerless Client: Simpler design to track member leaves and joins to the cluster.

Features Implemented for this Client

Data Structures
Go Client

Map

Queue

Set

List

MultiMap

Replicated Map

Ring Buffer

Topic

Reliable Topic

JCache

N/A

Cardinality Estimator

Concurrency Primitives
Go Client

Lock

Condition

Semaphore

AtomicLong

AtomicReference

ID Generator

CountDownLatch

CRDT PN Counter

Flake ID Generator

Transactions
Go Client

TxnMap

TxnMultiMap

TxnQueue

TxnList

TxnSet

Query
Go Client

SQL

Query (Predicates)

Paging Predicates

Partition Predicates

Built-in Predicates

Continuous Query Caching

N/A

Listener with Predicate

Projections

Fast Aggregations

Near Cache
Go Client

Near Cache Support

HD Memory

N/A

Preload Cache from Last Used

Eventual Consistency Control

Configuration
Go Client

Declarative Configuration (XML/JSON/YAML)

Programmatic Configuration

Client Configuration Import

Fail Fast on Invalid Configuration

Security
Go Client

SSL Support

XA Transactions

Mutual Authentication

Username/Password Authentication

Custom Authentication Modules

Management Center
Go Client

Management Center Integration / Awareness

Client Near Cache Stats

Client Runtime Stats

Client Operating System Stats

Cloud
Go Client

Hazelcast Cloud

Kubernetes

AWS

Azure

Google Cloud Platform

Pivotal Cloud Foundry

Docker

Apache jclouds

Consul

etcd

Eureka

Heroku

Zookeeper

Infrastructure
Go Client

Open Client Protocol

Smart Client

Unisocket Client

Lifecycle Service

HeartBeat

Backup Acknowledgement to Client

Diagnostics

Serialization
Go Client

DataSerializable

N/A

IdentifiedDataSerializable

Portable Serialization

Custom Serialization

Global Serialization

Client Connectivity
Go Client

Connection Strategy

Connection Retry

Blue/Green Deployments and Disaster Recovery