Serializing into JSON

If you want to query JSON strings that are stored in Hazelcast, you can serialize them, using HazelcastJsonValue.

HazelcastJsonValue is a lightweight wrapper that tells a Hazelcast cluster to treat a given string as JSON. Using this information, members can create metadata to optimize queries for data in the string. As a result, it’s best to use HazelcastJsonValue when you want to be able to query JSON values stored in Hazelcast clusters.

Serializing into HazelcastJsonValue

To serialize a JSON string into HazelcastJsonValue, pass the string directly to the new HazelcastJsonValue() constructor.

Hazelcast does not validate the given string. It is your responsibility to use a well-formed JSON string as a HazelcastJsonValue.
String person1 = "{ \"name\": \"John\", \"age\": 35 }";
String person2 = "{ \"name\": \"Jane\", \"age\": 24 }";
String person3 = "{ \"name\": \"Trey\", \"age\": 17 }";
String person4 = "{ \"name\": \"Phil\", \"age\": 30 }";
String person5 = "{ \"name\": \"May\"}";

IMap<Integer, HazelcastJsonValue> idPersonMap = instance.getMap("jsonValues");

idPersonMap.put(1, new HazelcastJsonValue(person1));
idPersonMap.put(2, new HazelcastJsonValue(person2));
idPersonMap.put(3, new HazelcastJsonValue(person3));
idPersonMap.put(4, new HazelcastJsonValue(person4));
idPersonMap.put(5, new HazelcastJsonValue(person4));

JSON Metadata

By default, for each HazelcastJsonValue object stored in a map, Hazelcast also stores a metadata object, which helps you to query JSON faster.

This metadata object is created every time a HazelcastJsonValue is put into a map and is stored in the on-heap or off-heap memory, depending on the map’s in-memory format setting.

Depending on your application’s needs, you may want to turn off metadata creation to both decrease latency when adding objects to a map and to increase throughput. You can configure this setting using a metadata policy.

Hazelcast Clients

HazelcastJsonValue does not require any Java classes on the member. As a result, clients can serialize data into JSON without any need to upload code to the member.

Clients do not validate JSON strings. If you store malformed JSON strings on the cluster, the member will log formatting errors only when you try to query the JSON data.


When you map columns to a json data type, SQL treats any strings in that column as JSON. As a result, you can either use raw JSON strings or HazelcastJsonValue.

To learn more about JSON in SQL, see Working with JSON Data in SQL.