@Beta public interface SqlService
The service is in beta state. Behavior and API might change in future releases. Binary compatibility is not guaranteed between minor or patch releases.
If this cluster is a Hazelcast Jet cluster, a statement can be executed by either the default SQL backend or by Hazelcast Jet backend, as a Jet job. If some of the features used in a statement isn't supported by the default backend, the engine will attempt to execute it using Jet. This class is the API to both backends.
The text below summarizes features supported by the default SQL engine. For a summary of Hazelcast Jet SQL features
see com.hazelcast.jet.sql
package javadoc in Hazelcast Jet (once released).
hazelcast-sql
module, that is based
on Apache Calcite. The hazelcast-sql
must be in the classpath, otherwise
an exception will be thrown.
During optimization a statement is converted into a directed acyclic graph (DAG) that is sent to cluster members for execution.
Results are sent back to the originating member asynchronously and returned to the user via SqlResult
.
partitioned
schema. The partitioned
schema is included into a default search path, therefore an IMap could be referenced in an SQL statement with or without the
schema name.
Columns are extracted from objects as follows:
Portable
objects, field names used in the Portable.writePortable(PortableWriter)
method
are used to populate the column list
__key
and this
, respectively. If
key (value) object has fields, then the whole key (value) field is exposed as a normal field. Otherwise the field is hidden.
Hidden fields can be accessed directly, but are not returned by SELECT * FROM ...
queries.
If the member that initiates a query doesn't have local entries for the given IMap, the query fails.
Consider the following key/value model:
class PersonKey { private long personId; private long deptId; public long getPersonId() { ... } public long getDepartmentId() { ... } } class Person { public String name; }This model will be resolved to the following table columns:
SqlResult
is returned. You may get row iterator from the result. The result must be closed
at the end. The code snippet below demonstrates a typical usage pattern:
HazelcastInstance instance = ...; try (SqlResult result = instance.sql().execute("SELECT * FROM person")) { for (SqlRow row : result) { long personId = row.getObject("personId"); String name = row.getObject("name"); ... } }
Modifier and Type | Method and Description |
---|---|
SqlResult |
execute(SqlStatement statement)
Executes an SQL statement.
|
default SqlResult |
execute(String sql,
Object... params)
Convenient method to execute a distributed query with the given parameters.
|
@Nonnull default SqlResult execute(@Nonnull String sql, Object... params)
Converts passed SQL string and parameters into an SqlStatement
object and invokes execute(SqlStatement)
.
sql
- SQL stringparams
- query parameters that will be passed to SqlStatement.setParameters(List)
NullPointerException
- if the SQL string is nullIllegalArgumentException
- if the SQL string is emptyHazelcastSqlException
- in case of execution errorSqlService
,
SqlStatement
,
execute(SqlStatement)
@Nonnull SqlResult execute(@Nonnull SqlStatement statement)
statement
- statement to be executedNullPointerException
- if the statement is nullHazelcastSqlException
- in case of execution errorSqlService
Copyright © 2021 Hazelcast, Inc.. All rights reserved.