Package org.apache.arrow.adbc.core

Interface AdbcStatement

All Superinterfaces:
AdbcOptions, AutoCloseable
All Known Implementing Classes:
FlightSqlStatement, JdbcStatement
public interface AdbcStatement extends AutoCloseable, AdbcOptions
A container for all state needed to execute a database query, such as the query itself, parameters for prepared statements, driver parameters, etc.

Statements may represent queries or prepared statements.

Statements may be used multiple times and can be reconfigured (e.g. they can be reused to execute multiple different queries). However, executing a statement (and changing certain other state) will invalidate result sets obtained prior to that execution.

Multiple statements may be created from a single connection. However, the driver may block or error if they are used concurrently (whether from a single thread or multiple threads).

Statements are not required to be thread-safe, but they can be used from multiple threads so long as clients take care to serialize accesses to a statement.

  • Method Details

    • cancel

      default void cancel() throws AdbcException
      Cancel execution of a query.

      This can be used to interrupt execution of a method like executeQuery().

      This method must be thread-safe (other method are not necessarily thread-safe).

      Throws:
      AdbcException
      Since:
      ADBC API revision 1.1.0

    • setOption

      default void setOption(String key, Object value) throws AdbcException
      Deprecated.
      Prefer AdbcOptions.setOption(TypedKey, Object).
      Set a generic query option.
      Throws:
      AdbcException

    • setSqlQuery

      default void setSqlQuery(String query) throws AdbcException
      Set a SQL query to be executed on this statement.
      Parameters:
      query - The SQL query.
      Throws:
      AdbcException

    • setSubstraitPlan

      default void setSubstraitPlan(ByteBuffer plan) throws AdbcException
      Set a Substrait plan to be executed on this statement.
      Parameters:
      plan - The serialized Substrait plan.
      Throws:
      AdbcException

    • bind

      default void bind(VectorSchemaRoot root) throws AdbcException
      Bind this statement to a VectorSchemaRoot to provide parameter values/bulk data ingestion.
      Throws:
      AdbcException

    • executeQuery

      AdbcStatement.QueryResult executeQuery() throws AdbcException
      Execute a result set-generating query and get the result.

      This may invalidate any prior result sets.

      Throws:
      AdbcException

    • executeUpdate

      AdbcStatement.UpdateResult executeUpdate() throws AdbcException
      Execute a query.

      This may invalidate any prior result sets.

      Throws:
      AdbcException

    • executePartitioned

      default AdbcStatement.PartitionResult executePartitioned() throws AdbcException
      Execute a result set-generating query and get a list of partitions of the result set.

      These can be serialized and deserialized for parallel and/or distributed fetching.

      This may invalidate any prior result sets.

      Throws:
      AdbcException

    • executeSchema

      default Schema executeSchema() throws AdbcException
      Get the schema of the result set without executing the query.
      Throws:
      AdbcException
      Since:
      ADBC API revision 1.1.0

    • pollPartitioned

      default Iterator<AdbcStatement.PartitionResult> pollPartitioned() throws AdbcException
      Execute a result set-generating query and get a list of partitions of the result set.

      These can be serialized and deserialized for parallel and/or distributed fetching.

      This may invalidate any prior result sets.

      Throws:
      AdbcException
      Since:
      ADBC API revision 1.1.0

    • getProgress

      default double getProgress() throws AdbcException
      Get the progress of executing a query.
      Throws:
      AdbcException
      Since:
      ADBC API revision 1.1.0

    • getMaxProgress

      default double getMaxProgress() throws AdbcException
      Get the upper bound of the progress.
      Throws:
      AdbcException
      Since:
      ADBC API revision 1.1.0

    • getParameterSchema

      default Schema getParameterSchema() throws AdbcException
      Get the schema for bound parameters.

      This retrieves an Arrow schema describing the number, names, and types of the parameters in a parameterized statement. The fields of the schema should be in order of the ordinal position of the parameters; named parameters should appear only once.

      If the parameter does not have a name, or the name cannot be determined, the name of the corresponding field in the schema will be an empty string. If the type cannot be determined, the type of the corresponding field will be NA (NullType).

      This should be called after AdbcStatementPrepare.

      Throws:
      AdbcException - with AdbcStatusCode.NOT_IMPLEMENTED if the parameters cannot be determined at all.

    • prepare

      void prepare() throws AdbcException
      Turn this statement into a prepared statement.

      Call executeQuery(), executeUpdate(), or executePartitioned() to execute the query.

      Throws:
      AdbcException