Package org.apache.arrow.adbc.driver.jdbc

Class JdbcConnection

java.lang.Object

org.apache.arrow.adbc.driver.jdbc.JdbcConnection

All Implemented Interfaces:

AutoCloseable, AdbcConnection, AdbcOptions

public class JdbcConnection
extends Object
implements AdbcConnection

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.arrow.adbc.core.AdbcConnection

AdbcConnection.GetObjectsDepth

Method Summary

Modifier and Type	Method	Description
AdbcStatement	bulkIngest(String targetTableName, BulkIngestMode mode)	Create a new statement to bulk insert a VectorSchemaRoot into a table.
void	close()
void	commit()	Commit the pending transaction.
AdbcStatement	createStatement()	Create a new statement that can be executed.
boolean	getAutoCommit()	Get the autocommit state.
String	getCurrentCatalog()	Get the current catalog.
String	getCurrentDbSchema()	Get the current schema.
ArrowReader	getInfo(int @Nullable [] infoCodes)	Get metadata about the driver/database.
IsolationLevel	getIsolationLevel()	Get the isolation level used by transactions.
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.
boolean	getReadOnly()	Get whether the connection is read-only.
ArrowReader	getStatisticNames()	Get the names of additional statistics defined by this driver.
ArrowReader	getStatistics(String catalogPattern, String dbSchemaPattern, String tableNamePattern, boolean approximate)	Get statistics about the data distribution of table(s).
Schema	getTableSchema(String catalog, String dbSchema, String tableName)	Get the Arrow schema of a database table.
ArrowReader	getTableTypes()	Get a list of table types supported by the database.
void	rollback()	Rollback the pending transaction.
void	setAutoCommit(boolean enableAutoCommit)	Toggle whether autocommit is enabled.
void	setCurrentCatalog(String catalog)	Set the current catalog.
void	setCurrentDbSchema(String dbSchema)	Set the current schema.
void	setIsolationLevel(IsolationLevel level)	Change the isolation level used by transactions.
void	setReadOnly(boolean isReadOnly)	Toggle whether the connection is read-only.
String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

cancel, getInfo, getInfo, readPartition

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

getOption, setOption

Method Details

commit

public void commit()
            throws AdbcException

Description copied from interface: AdbcConnection

Commit the pending transaction.

Specified by:

commit in interface AdbcConnection

Throws:

AdbcException

createStatement

public AdbcStatement createStatement()
                              throws AdbcException

Description copied from interface: AdbcConnection

Create a new statement that can be executed.

Specified by:

createStatement in interface AdbcConnection

Throws:

AdbcException

bulkIngest

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

Description copied from interface: AdbcConnection

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.

Specified by:

bulkIngest in interface AdbcConnection

Throws:

AdbcException

getInfo

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

Description copied from interface: AdbcConnection

Get metadata about the driver/database.

Specified by:

getInfo in interface AdbcConnection

Parameters:

infoCodes - The metadata items to fetch.

Throws:

AdbcException

getObjects

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

Description copied from interface: AdbcConnection

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

Specified by:

getObjects in interface AdbcConnection

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 AdbcConnection.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

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

Description copied from interface: AdbcConnection

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 AdbcConnection.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

Specified by:

getStatistics in interface AdbcConnection

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

public ArrowReader getStatisticNames()
                              throws AdbcException

Description copied from interface: AdbcConnection

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

Specified by:

getStatisticNames in interface AdbcConnection

Throws:

AdbcException

getTableSchema

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

Description copied from interface: AdbcConnection

Get the Arrow schema of a database table.

Specified by:

getTableSchema in interface AdbcConnection

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

public ArrowReader getTableTypes()
                          throws AdbcException

Description copied from interface: AdbcConnection

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

Specified by:

getTableTypes in interface AdbcConnection

Throws:

AdbcException

rollback

public void rollback()
              throws AdbcException

Description copied from interface: AdbcConnection

Rollback the pending transaction.

Specified by:

rollback in interface AdbcConnection

Throws:

AdbcException - if a database error occurs

getAutoCommit

public boolean getAutoCommit()
                      throws AdbcException

Description copied from interface: AdbcConnection

Get the autocommit state.

Connections start in autocommit mode by default.

Specified by:

getAutoCommit in interface AdbcConnection

Throws:

AdbcException

setAutoCommit

public void setAutoCommit(boolean enableAutoCommit)
                   throws AdbcException

Description copied from interface: AdbcConnection

Toggle whether autocommit is enabled.

Specified by:

setAutoCommit in interface AdbcConnection

Throws:

AdbcException

getCurrentCatalog

public String getCurrentCatalog()
                         throws AdbcException

Description copied from interface: AdbcConnection

Get the current catalog.

Specified by:

getCurrentCatalog in interface AdbcConnection

Throws:

AdbcException

setCurrentCatalog

public void setCurrentCatalog(String catalog)
                       throws AdbcException

Description copied from interface: AdbcConnection

Set the current catalog.

Specified by:

setCurrentCatalog in interface AdbcConnection

Throws:

AdbcException

getCurrentDbSchema

public String getCurrentDbSchema()
                          throws AdbcException

Description copied from interface: AdbcConnection

Get the current schema.

Specified by:

getCurrentDbSchema in interface AdbcConnection

Throws:

AdbcException

setCurrentDbSchema

public void setCurrentDbSchema(String dbSchema)
                        throws AdbcException

Description copied from interface: AdbcConnection

Set the current schema.

Specified by:

setCurrentDbSchema in interface AdbcConnection

Throws:

AdbcException

getReadOnly

public boolean getReadOnly()
                    throws AdbcException

Description copied from interface: AdbcConnection

Get whether the connection is read-only.

Connections are not read-only by default.

Specified by:

getReadOnly in interface AdbcConnection

Throws:

AdbcException

setReadOnly

public void setReadOnly(boolean isReadOnly)
                 throws AdbcException

Description copied from interface: AdbcConnection

Toggle whether the connection is read-only.

Specified by:

setReadOnly in interface AdbcConnection

Throws:

AdbcException

getIsolationLevel

public IsolationLevel getIsolationLevel()
                                 throws AdbcException

Description copied from interface: AdbcConnection

Get the isolation level used by transactions.

Specified by:

getIsolationLevel in interface AdbcConnection

Throws:

AdbcException

setIsolationLevel

public void setIsolationLevel(IsolationLevel level)
                       throws AdbcException

Description copied from interface: AdbcConnection

Change the isolation level used by transactions.

Specified by:

setIsolationLevel in interface AdbcConnection

Throws:

AdbcException

close

public void close()
           throws Exception

Specified by:

close in interface AutoCloseable

Throws:

Exception

toString

public String toString()

Overrides:

toString in class Object