Package 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

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      SqlResult execute​(SqlStatement statement)
      Executes an SQL statement.
      default SqlResult execute​(java.lang.String sql, java.lang.Object... arguments)
      Convenient method to execute a distributed query with the given parameter values.
      default long executeUpdate​(java.lang.String sql, java.lang.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

      • executeUpdate

        default long executeUpdate​(@Nonnull
                           java.lang.String sql,
                           java.lang.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:
        java.lang.NullPointerException - if the SQL string is null
        java.lang.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:
        java.lang.NullPointerException - if the statement is null
        HazelcastSqlException - in case of execution error
        See Also:
        SqlService