Package org.apache.arrow.adbc.core

Interface AdbcConnection

All Superinterfaces:

AdbcOptions, AutoCloseable

All Known Implementing Classes:

FlightSqlConnection, JdbcConnection

public interface AdbcConnection
extends AutoCloseable, AdbcOptions

A connection to a AdbcDatabase.

Connections 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 connection.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	AdbcConnection.GetObjectsDepth	The level of nesting to retrieve for getObjects(GetObjectsDepth, String, String, String, String[], String).

Method Summary

Modifier and Type	Method	Description
default AdbcStatement	bulkIngest(String targetTableName, BulkIngestMode mode)	Create a new statement to bulk insert a VectorSchemaRoot into a table.
default void	cancel()	Cancel execution of a query.
default void	commit()	Commit the pending transaction.
AdbcStatement	createStatement()	Create a new statement that can be executed.
default boolean	getAutoCommit()	Get the autocommit state.
default String	getCurrentCatalog()	Get the current catalog.
default String	getCurrentDbSchema()	Get the current schema.
default ArrowReader	getInfo()	Get metadata about the driver/database.
ArrowReader	getInfo(int @Nullable [] infoCodes)	Get metadata about the driver/database.
default ArrowReader	getInfo(AdbcInfoCode[] infoCodes)	Get metadata about the driver/database.
default IsolationLevel	getIsolationLevel()	Get the isolation level used by transactions.
default ArrowReader	getObjects(AdbcConnection.GetObjectsDepth depth, String catalogPattern, String dbSchemaPattern, String tableNamePattern, String[] tableTypes, String columnNamePattern)	Get a hierarchical view of all catalogs, database schemas, tables, and columns.
default boolean	getReadOnly()	Get whether the connection is read-only.
default ArrowReader	getStatisticNames()	Get the names of additional statistics defined by this driver.
default ArrowReader	getStatistics(String catalogPattern, String dbSchemaPattern, String tableNamePattern, boolean approximate)	Get statistics about the data distribution of table(s).
default Schema	getTableSchema(String catalog, String dbSchema, String tableName)	Get the Arrow schema of a database table.
default ArrowReader	getTableTypes()	Get a list of table types supported by the database.
default ArrowReader	readPartition(ByteBuffer descriptor)	Create a result set from a serialized PartitionDescriptor.
default void	rollback()	Rollback the pending transaction.
default void	setAutoCommit(boolean enableAutoCommit)	Toggle whether autocommit is enabled.
default void	setCurrentCatalog(String catalog)	Set the current catalog.
default void	setCurrentDbSchema(String dbSchema)	Set the current schema.
default void	setIsolationLevel(IsolationLevel level)	Change the isolation level used by transactions.
default void	setReadOnly(boolean isReadOnly)	Toggle whether the connection is read-only.

Methods inherited from interface org.apache.arrow.adbc.core.AdbcOptions

getOption, setOption

Methods inherited from interface java.lang.AutoCloseable

close

Method Details

cancel

default void cancel()
             throws AdbcException

Cancel execution of a query.

This can be used to interrupt execution of a method like getObjects(GetObjectsDepth, String, String, String, String[], String)}.

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

Throws:

AdbcException

Since:

ADBC API revision 1.1.0

commit

default void commit()
             throws AdbcException

Commit the pending transaction.

Throws:

AdbcException

createStatement

AdbcStatement createStatement()
                       throws AdbcException

Create a new statement that can be executed.

Throws:

AdbcException

bulkIngest

default AdbcStatement bulkIngest(String targetTableName,
 BulkIngestMode mode)
                          throws AdbcException

Create a new statement to bulk insert a VectorSchemaRoot into a table.

Bind data to the statement, then call AdbcStatement.executeUpdate(). See BulkIngestMode for description of behavior around creating tables.

Throws:

AdbcException

readPartition

default ArrowReader readPartition(ByteBuffer descriptor)
                           throws AdbcException

Create a result set from a serialized PartitionDescriptor.

Parameters:

descriptor - The descriptor to load (PartitionDescriptor.getDescriptor().

Returns:

A statement that can be immediately executed.

Throws:

AdbcException

See Also:

• AdbcStatement.PartitionResult

getInfo

ArrowReader getInfo(int @Nullable [] infoCodes)
             throws AdbcException

Get metadata about the driver/database.

Parameters:

infoCodes - The metadata items to fetch.

Throws:

AdbcException

getInfo

default ArrowReader getInfo(AdbcInfoCode[] infoCodes)
                     throws AdbcException

Get metadata about the driver/database.

Parameters:

infoCodes - The metadata items to fetch.

Returns:

A statement that can be immediately executed.

Throws:

AdbcException

getInfo

default ArrowReader getInfo()
                     throws AdbcException

Get metadata about the driver/database.

Returns:

A statement that can be immediately executed.

Throws:

AdbcException

getObjects

default ArrowReader getObjects(AdbcConnection.GetObjectsDepth depth,
 String catalogPattern,
 String dbSchemaPattern,
 String tableNamePattern,
 String[] tableTypes,
 String columnNamePattern)
                        throws AdbcException

Get a hierarchical view of all catalogs, database schemas, tables, and columns.

The result is an Arrow dataset with the following schema:

The definition of the GetObjects result schema.

Field Name	Field Type
catalog_name	utf8
catalog_db_schemas	list[DB_SCHEMA_SCHEMA]

DB_SCHEMA_SCHEMA is a Struct with fields:

The definition of DB_SCHEMA_SCHEMA.

Field Name	Field Type
db_schema_name	utf8
db_schema_tables	list[TABLE_SCHEMA]

TABLE_SCHEMA is a Struct with fields:

The definition of TABLE_SCHEMA.

Field Name	Field Type
table_name	utf8 not null
table_type	utf8 not null
table_columns	list[COLUMN_SCHEMA]
table_constraints	list[CONSTRAINT_SCHEMA]

COLUMN_SCHEMA is a Struct with fields:

The definition of COLUMN_SCHEMA.

Field Name	Field Type	Comments
column_name	utf8 not null
ordinal_position	int32	(1)
remarks	utf8	(2)
xdbc_data_type	int16	(3)
xdbc_type_name	utf8	(3)
xdbc_column_size	int32	(3)
xdbc_decimal_digits	int16	(3)
xdbc_num_prec_radix	int16	(3)
xdbc_nullable	int16	(3)
xdbc_column_def	utf8	(3)
xdbc_sql_data_type	int16	(3)
xdbc_datetime_sub	int16	(3)
xdbc_char_octet_length	int32	(3)
xdbc_is_nullable	utf8	(3)
xdbc_scope_catalog	utf8	(3)
xdbc_scope_schema	utf8	(3)
xdbc_scope_table	utf8	(3)
xdbc_is_autoincrement	bool	(3)
xdbc_is_generatedcolumn	bool	(3)

Notes:

1. The column's ordinal position in the table (starting from 1).
2. Database-specific description of the column.
3. Optional value. Should be null if not supported by the driver. xdbc_ values are meant to provide JDBC/ODBC-compatible metadata in an agnostic manner.

CONSTRAINT_SCHEMA is a Struct with fields:

The definition of CONSTRAINT_SCHEMA.

Field Name	Field Type	Comments
constraint_name	utf8 not null
constraint_type	utf8 not null	(1)
constraint_column_names	list[utf8] not null	(2)
constraint_column_usage	list[USAGE_SCHEMA]	(3)

1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE'.
2. The columns on the current table that are constrained, in order.
3. For FOREIGN KEY only, the referenced table and columns.

USAGE_SCHEMA is a Struct with fields:

The definition of USAGE_SCHEMA.

Field Name	Field Type
fk_catalog	utf8
fk_db_schema	utf8
fk_table	utf8 not null
fk_column_name	utf8 not null

Parameters:

depth - The level of nesting to display. If ALL, display all levels (up through columns). If CATALOGS, display only catalogs (i.e. catalog_schemas will be null), and so on. May be a search pattern (see class documentation).

catalogPattern - Only show tables in the given catalog. If null, do not filter by catalog. If an empty string, only show tables without a catalog. May be a search pattern (see class documentation).

dbSchemaPattern - Only show tables in the given database schema. If null, do not filter by database schema. If an empty string, only show tables without a database schema. May be a search pattern (see class documentation).

tableNamePattern - Only show tables with the given name. If an empty string, only show tables without a catalog. May be a search pattern (see class documentation).

tableTypes - Only show tables matching one of the given table types. If null, show tables of any type. Valid table types can be fetched from getTableTypes().

columnNamePattern - Only show columns with the given name. If null, do not filter by name. May be a search pattern (see class documentation).

Throws:

AdbcException

getStatistics

default ArrowReader getStatistics(String catalogPattern,
 String dbSchemaPattern,
 String tableNamePattern,
 boolean approximate)
                           throws AdbcException

Get statistics about the data distribution of table(s).

The result is an Arrow dataset with the following schema:

The definition of the GetStatistics result schema.

Field Name	Field Type
catalog_name	utf8
catalog_db_schemas	list[DB_SCHEMA_SCHEMA] not null

DB_SCHEMA_SCHEMA is a Struct with fields:

The definition of DB_SCHEMA_SCHEMA.

Field Name	Field Type
db_schema_name	utf8
db_schema_statistics	list[STATISTICS_SCHEMA] not null

STATISTICS_SCHEMA is a Struct with fields:

The definition of STATISTICS_SCHEMA.

Field Name	Field Type	Comments
table_name	utf8 not null
column_name	utf8	(1)
statistic_key	int16 not null	(2)
statistic_value	VALUE_SCHEMA not null
statistic_is_approximate	bool not null	(3)

1. If null, then the statistic applies to the entire table.
2. A dictionary-encoded statistic name (although we do not use the Arrow dictionary type). Values in [0, 1024) are reserved for ADBC. Other values are for implementation-specific statistics. For the definitions of predefined statistic types, see StandardStatistics. To get driver-specific statistic names, use getStatisticNames().
3. If true, then the value is approximate or best-effort.

VALUE_SCHEMA is a dense union with members:

The definition of VALUE_SCHEMA.

Field Name	Field Type
int64	int64
uint64	uint64
float64	float64
binary	binary

Parameters:

catalogPattern - Only show tables in the given catalog. If null, do not filter by catalog. If an empty string, only show tables without a catalog. May be a search pattern (see class documentation).

dbSchemaPattern - Only show tables in the given database schema. If null, do not filter by database schema. If an empty string, only show tables without a database schema. May be a search pattern (see class documentation).

tableNamePattern - Only show tables with the given name. If an empty string, only show tables without a catalog. May be a search pattern (see class documentation).

approximate - If false, request exact values of statistics, else allow for best-effort, approximate, or cached values. The database may return approximate values regardless, as indicated in the result. Requesting exact values may be expensive or unsupported.

Throws:

AdbcException

getStatisticNames

default ArrowReader getStatisticNames()
                               throws AdbcException

Get the names of additional statistics defined by this driver.

The result is an Arrow dataset with the following schema:

The definition of the GetStatistics result schema.

Field Name	Field Type
statistic_name	utf8 not null
statistic_key	int16 not null

Throws:

AdbcException

getTableSchema

default Schema getTableSchema(String catalog,
 String dbSchema,
 String tableName)
                       throws AdbcException

Get the Arrow schema of a database table.

Parameters:

catalog - The catalog of the table (or null).

dbSchema - The database schema of the table (or null).

tableName - The table name.

Returns:

The table schema.

Throws:

AdbcException

getTableTypes

default ArrowReader getTableTypes()
                           throws AdbcException

Get a list of table types supported by the database.

The result is an Arrow dataset with the following schema:

The definition of the result schema.

Field Name	Field Type
table_type	utf8 not null

Throws:

AdbcException

rollback

default void rollback()
               throws AdbcException

Rollback the pending transaction.

Throws:

AdbcException - if a database error occurs

getAutoCommit

default boolean getAutoCommit()
                       throws AdbcException

Get the autocommit state.

Connections start in autocommit mode by default.

Throws:

AdbcException

setAutoCommit

default void setAutoCommit(boolean enableAutoCommit)
                    throws AdbcException

Toggle whether autocommit is enabled.

Throws:

AdbcException

getCurrentCatalog

default String getCurrentCatalog()
                          throws AdbcException

Get the current catalog.

Throws:

AdbcException

Since:

ADBC API revision 1.1.0

setCurrentCatalog

default void setCurrentCatalog(String catalog)
                        throws AdbcException

Set the current catalog.

Throws:

AdbcException

Since:

ADBC API revision 1.1.0

getCurrentDbSchema

default String getCurrentDbSchema()
                           throws AdbcException

Get the current schema.

Throws:

AdbcException

Since:

ADBC API revision 1.1.0

setCurrentDbSchema

default void setCurrentDbSchema(String dbSchema)
                         throws AdbcException

Set the current schema.

Throws:

AdbcException

Since:

ADBC API revision 1.1.0

getReadOnly

default boolean getReadOnly()
                     throws AdbcException

Get whether the connection is read-only.

Connections are not read-only by default.

Throws:

AdbcException

setReadOnly

default void setReadOnly(boolean isReadOnly)
                  throws AdbcException

Toggle whether the connection is read-only.

Throws:

AdbcException

getIsolationLevel

default IsolationLevel getIsolationLevel()
                                  throws AdbcException

Get the isolation level used by transactions.

Throws:

AdbcException

setIsolationLevel

default void setIsolationLevel(IsolationLevel level)
                        throws AdbcException

Change the isolation level used by transactions.

Throws:

AdbcException