Mapping to Hazelcast Maps
Before you can query entries in maps, you need to create a mapping with the map connector so that the SQL service knows how to access the entries in the most efficient way.
What is the Map Connector
The map connector allows you to create mappings to a distributed map in a local Hazelcast cluster.
If you use Hazelcast Enterprise, you can set up permissions to restrict clients' access to maps.
For example, to restrict reads on maps, you can use the
read permissions. To restrict inserts, you can use the
For details, see Client Security.
Creating a Mapping to a Map
To create a mapping to a map in SQL, you must tell Hazelcast how to serialize/deserialize the keys and values by specifying the
valueFormat options in the
CREATE MAPPING statement.
For maps whose keys and values are primitives, you need to set these options to the SQL type that corresponds to the primitive:
For example, to create a mapping for
CREATE MAPPING my_map TYPE IMap OPTIONS ( 'keyFormat'='int', 'valueFormat'='varchar' )
For a reference, see SQL Data Types.
For object formats, you must specify other options, depending on the serialization format:
If your map’s keys or values are portable, you need to provide the following additional options:
valuePortableVersion(optional, default is
For example, to create a mapping for a map where both key and value are portable:
CREATE MAPPING my_map TYPE IMap OPTIONS ( 'keyFormat' = 'portable', 'keyPortableFactoryId' = '123', 'keyPortableClassId' = '456', 'keyPortableVersion' = '0', -- optional 'valueFormat' = 'portable', 'valuePortableFactoryId' = '123', 'valuePortableClassId' = '789', 'valuePortableVersion' = '0' -- optional )
If you omit a column list from the
CREATE MAPPING statement, Hazelcast will
resolve the column names and types by looking at the
found using the given factory ID, class ID, and version.
ClassDefinition with the given IDs is not known to the cluster,
you must provide a column list so that Hazelcast can use it to create the
For more information about this serialization option, see Implementing Portable Serialization.
If your map’s keys or values are compact, you need to provide the following additional options:
The column list is mandatory and Hazelcast will create the
schema based on the column list.
The benefit of this format is that it doesn’t deserialize the whole key
or value when reading only a subset of fields. Also it doesn’t require a
custom Java class to be defined on the cluster, so it’s usable for
non-Java clients similar to
Portable. And it is more space-efficient than
Example mapping where both key and value are
CREATE MAPPING my_map ( id INT EXTERNAL NAME "__key.id", name VARCHAR, surname VARCHAR, age INT) TYPE IMap OPTIONS ( 'keyFormat' = 'compact', 'keyCompactTypeName' = 'personId', 'valueFormat' = 'compact', 'valueCompactTypeName' = 'person', )
For more information about this serialization option, see Compact Serialization (BETA).
For maps whose values are stored in JSON, you must declare the field names in the column list.
For example, to create a mapping for a map whose values are JSON objects with the
CREATE MAPPING my_map( __key BIGINT, ticker VARCHAR, amount INT) TYPE IMap OPTIONS ( 'keyFormat' = 'bigint', 'valueFormat' = 'json-flat')
There are no additional options for this format.
By default, Hazelcast serializes JSON into
HazelcastJsonValue objects, which allows you to query its fields.
JSON’s type system doesn’t match SQL’s exactly. For example, JSON
numbers have unlimited precision, but such numbers are typically not
portable. We convert SQL integer and floating-point types into JSON
numbers. We convert the
DECIMAL type, as well as all temporal types,
to JSON strings.
Hazelcast doesn’t yet support the
For maps whose keys or values are serialized with Java serialization,
IdentifiedDataSerializable, you need to provide the name of the Java class into which you want to serialize data, using the following additional options:
CREATE MAPPING my_map TYPE IMap OPTIONS ( 'keyFormat' = 'java', 'keyJavaClass' = 'java.lang.Long', 'valueFormat' = 'java', 'valueJavaClass' = 'com.example.Person')
If the Java class corresponds to one of the basic data types (numbers,
dates, strings), that type will be used for the key or value
and mapped as a column named
__key for keys and
this for values. In
the example above, the key will be mapped with the
BIGINT type. In
fact, the above
keyJavaClass duo is equivalent to
If the Java class is not one of the basic types:
Hazelcast will analyze the class using reflection and use its properties as column names.
Hazelcast recognizes public fields and JavaBean-style getters. If some property has a non-primitive type, it will be mapped under the
The class must be available to the cluster.
You can either add the class to the members' classpaths by creating a JAR file and adding it to the
libdirectory, or you can use user code deployment. User code deployment must be enabled on the members, see Deploying User Code from Clients for details.