com.hazelcast.sql

Interface SqlService

public interface SqlService

A service to execute SQL statements.

In order to use the service, Jet engine must be enabled - SQL statements are executed as Jet jobs. On members, the hazelcast-sql.jar must be on the classpath, otherwise an exception will be thrown; on client, it is not necessary.

Overview

Hazelcast is currently able to execute distributed SQL queries using the following connectors:

• IMap
• Kafka
• Files

When an SQL statement is submitted to a member, it is parsed and optimized by the hazelcast-sql module, that is based on Apache Calcite. 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.

SQL statements are not atomic. INSERT/SINK can fail and commit part of the data.

Usage

Before you can access any object using SQL, a mapping has to be created. See the reference manual for the CREATE MAPPING command.

When a query is executed, an 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");
             ...
         }
     }
 

Method Summary

Modifier and Type	Method and Description
SqlResult	execute(SqlStatement statement) Executes an SQL statement.
default SqlResult	execute(String sql, Object... arguments) Convenient method to execute a distributed query with the given parameter values.
default long	executeUpdate(String sql, Object... arguments) Convenience method to execute a distributed non-DQL statement (that is a statement that does not return rows) with the given parameter values.

Method Detail

execute

@Nonnull
default SqlResult execute(@Nonnull
                                   String sql,
                                   Object... arguments)

Convenient method to execute a distributed query with the given parameter values.

Converts passed SQL string and parameter values into an SqlStatement object and invokes execute(SqlStatement).

Parameters:

sql - SQL string

arguments - query parameter values that will be passed to SqlStatement.setParameters(List)

Returns:

result

Throws:

NullPointerException - if the SQL string is null

IllegalArgumentException - if the SQL string is empty

HazelcastSqlException - in case of execution error

See Also:

SqlService, SqlStatement, execute(SqlStatement)

executeUpdate

default long executeUpdate(@Nonnull
                           String sql,
                           Object... arguments)

Convenience method to execute a distributed non-DQL statement (that is a statement that does not return rows) with the given parameter values.

Converts passed SQL string and parameter values into an SqlStatement object and invokes execute(SqlStatement).

This method can be used for statements other than "SELECT" queries. The returned value is the SqlResult.updateCount() value.

Parameters:

sql - SQL string

arguments - query parameter values that will be passed to SqlStatement.setParameters(List)

Returns:

The number of updated(/inserted/deleted) rows.

Throws:

NullPointerException - if the SQL string is null

IllegalArgumentException - if the SQL string is empty

HazelcastSqlException - in case of execution error

Since:

5.3

See Also:

SqlService, SqlStatement, execute(SqlStatement), execute(String, Object...)

execute

@Nonnull
SqlResult execute(@Nonnull
                           SqlStatement statement)

Executes an SQL statement.

Parameters:

statement - statement to be executed

Returns:

result

Throws:

NullPointerException - if the statement is null

HazelcastSqlException - in case of execution error

See Also:

SqlService