Functions
AdbcStatusCode	AdbcConnectionGetInfo (struct AdbcConnection connection, const uint32_t info_codes, size_t info_codes_length, struct ArrowArrayStream out, struct AdbcError error)
	Get metadata about the database/driver.

AdbcStatusCode	AdbcConnectionGetObjects (struct AdbcConnection connection, int depth, const char catalog, const char db_schema, const char table_name, const char *table_type, const char column_name, struct ArrowArrayStream out, struct AdbcError error)
	Get a hierarchical view of all catalogs, database schemas, tables, and columns.

AdbcStatusCode	AdbcConnectionGetOption (struct AdbcConnection connection, const char key, char value, size_t length, struct AdbcError *error)
	Get a string option of the connection.

AdbcStatusCode	AdbcConnectionGetOptionBytes (struct AdbcConnection connection, const char key, uint8_t value, size_t length, struct AdbcError *error)
	Get a bytestring option of the connection.

AdbcStatusCode	AdbcConnectionGetOptionInt (struct AdbcConnection connection, const char key, int64_t value, struct AdbcError error)
	Get an integer option of the connection.

AdbcStatusCode	AdbcConnectionGetOptionDouble (struct AdbcConnection connection, const char key, double value, struct AdbcError error)
	Get a double option of the connection.

AdbcStatusCode	AdbcConnectionGetStatistics (struct AdbcConnection connection, const char catalog, const char db_schema, const char table_name, char approximate, struct ArrowArrayStream out, struct AdbcError error)
	Get statistics about the data distribution of table(s).

AdbcStatusCode	AdbcConnectionGetStatisticNames (struct AdbcConnection connection, struct ArrowArrayStream out, struct AdbcError *error)
	Get the names of statistics specific to this driver.

AdbcStatusCode	AdbcConnectionGetTableSchema (struct AdbcConnection connection, const char catalog, const char db_schema, const char table_name, struct ArrowSchema schema, struct AdbcError error)
	Get the Arrow schema of a table.

AdbcStatusCode	AdbcConnectionGetTableTypes (struct AdbcConnection connection, struct ArrowArrayStream out, struct AdbcError *error)
	Get a list of table types in the database.

Detailed Description

Functions for retrieving metadata about the database.

Generally, these functions return an ArrowArrayStream that can be consumed to get the metadata as Arrow data. The returned metadata has an expected schema given in the function docstring. Schema fields are nullable unless otherwise marked. While no AdbcStatement is used in these functions, the result set may count as an active statement to the driver for the purposes of concurrency management (e.g. if the driver has a limit on concurrent active statements and it must execute a SQL query internally in order to implement the metadata function).

This AdbcConnection must outlive the returned ArrowArrayStream.

Some functions accept "search pattern" arguments, which are strings that can contain the special character "%" to match zero or more characters, or "_" to match exactly one character. (See the documentation of DatabaseMetaData in JDBC or "Pattern Value Arguments" in the ODBC documentation.) Escaping is not currently supported.

Function Documentation

◆ AdbcConnectionGetInfo()

AdbcStatusCode AdbcConnectionGetInfo	(	struct AdbcConnection *	connection,
		const uint32_t *	info_codes,
		size_t	info_codes_length,
		struct ArrowArrayStream *	out,
		struct AdbcError *	error )

Get metadata about the database/driver.

The result is an Arrow dataset with the following schema:

Field Name	Field Type
info_name	uint32 not null
info_value	INFO_SCHEMA

INFO_SCHEMA is a dense union with members:

Field Name (Type Code)	Field Type
string_value (0)	utf8
bool_value (1)	bool
int64_value (2)	int64
int32_bitmask (3)	int32
string_list (4)	list<utf8>
int32_to_int32_list_map (5)	map<int32, list<int32>>

Each metadatum is identified by an integer code. The recognized codes are defined as constants. Codes [0, 10_000) are reserved for ADBC usage. Drivers/vendors will ignore requests for unrecognized codes (the row will be omitted from the result).

Since ADBC 1.1.0: the range [500, 1_000) is reserved for "XDBC" information, which is the same metadata provided by the same info code range in the Arrow Flight SQL GetSqlInfo RPC.

Parameters

[in]	connection	The connection to query.
[in]	info_codes	A list of metadata codes to fetch, or NULL to fetch all.
[in]	info_codes_length	The length of the info_codes parameter. Ignored if info_codes is NULL.
[out]	out	The result set.
[out]	error	Error details, if an error occurs.

◆ AdbcConnectionGetObjects()

AdbcStatusCode AdbcConnectionGetObjects	(	struct AdbcConnection *	connection,
		int	depth,
		const char *	catalog,
		const char *	db_schema,
		const char *	table_name,
		const char **	table_type,
		const char *	column_name,
		struct ArrowArrayStream *	out,
		struct AdbcError *	error )

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

The result is an Arrow dataset with the following schema:

Field Name	Field Type
catalog_name	utf8
catalog_db_schemas	list<DB_SCHEMA_SCHEMA>

DB_SCHEMA_SCHEMA is a Struct with fields:

Field Name	Field Type
db_schema_name	utf8
db_schema_tables	list<TABLE_SCHEMA>

TABLE_SCHEMA is a Struct with fields:

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:

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)

The column's ordinal position in the table (starting from 1).
Database-specific description of the column.
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:

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

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

USAGE_SCHEMA is a Struct with fields:

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

This AdbcConnection must outlive the returned ArrowArrayStream.

Parameters

[in]	connection	The database connection.
[in]	depth	The level of nesting to display. If 0, display all levels. If 1, display only catalogs (i.e. catalog_schemas will be null). If 2, display only catalogs and schemas (i.e. db_schema_tables will be null), and so on.
[in]	catalog	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 section documentation).
[in]	db_schema	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 section documentation).
[in]	table_name	Only show tables with the given name. If NULL, do not filter by name. May be a search pattern (see section documentation).
[in]	table_type	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. Terminate the list with a NULL entry.
[in]	column_name	Only show columns with the given name. If NULL, do not filter by name. May be a search pattern (see section documentation).
[out]	out	The result set.
[out]	error	Error details, if an error occurs.

◆ AdbcConnectionGetOption()

AdbcStatusCode AdbcConnectionGetOption	(	struct AdbcConnection *	connection,
		const char *	key,
		char *	value,
		size_t *	length,
		struct AdbcError *	error )

Get a string option of the connection.

This must always be thread-safe (other operations are not), though given the semantics here, it is not recommended to call GetOption concurrently with itself.

length must be provided and must be the size of the buffer pointed to by value. If there is sufficient space, the driver will copy the option value (including the null terminator) to buffer and set length to the size of the actual value. If the buffer is too small, no data will be written and length will be set to the required length.

In other words:

If output length <= input length, value will contain a value with length bytes.
If output length > input length, nothing has been written to value.

Since: ADBC API revision 1.1.0

Parameters

[in]	connection	The database connection.
[in]	key	The option to get.
[out]	value	The option value.
[in,out]	length	The length of value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcConnectionGetOptionBytes()

AdbcStatusCode AdbcConnectionGetOptionBytes	(	struct AdbcConnection *	connection,
		const char *	key,
		uint8_t *	value,
		size_t *	length,
		struct AdbcError *	error )

Get a bytestring option of the connection.

This must always be thread-safe (other operations are not), though given the semantics here, it is not recommended to call GetOptionBytes concurrently with itself.

length must be provided and must be the size of the buffer pointed to by value. If there is sufficient space, the driver will copy the option value to buffer and set length to the size of the actual value. If the buffer is too small, no data will be written and length will be set to the required length.

In other words:

If output length <= input length, value will contain a value with length bytes.
If output length > input length, nothing has been written to value.

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since: ADBC API revision 1.1.0

Parameters

[in]	connection	The connection.
[in]	key	The option to get.
[out]	value	The option value.
[in,out]	length	The option value length.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcConnectionGetOptionDouble()

AdbcStatusCode AdbcConnectionGetOptionDouble	(	struct AdbcConnection *	connection,
		const char *	key,
		double *	value,
		struct AdbcError *	error )

Get a double option of the connection.

This must always be thread-safe (other operations are not).

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since: ADBC API revision 1.1.0

Parameters

[in]	connection	The database connection.
[in]	key	The option to get.
[out]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcConnectionGetOptionInt()

AdbcStatusCode AdbcConnectionGetOptionInt	(	struct AdbcConnection *	connection,
		const char *	key,
		int64_t *	value,
		struct AdbcError *	error )

Get an integer option of the connection.

This must always be thread-safe (other operations are not).

For standard options, drivers must always support getting the option value (if they support getting option values at all) via the type specified in the option. (For example, an option set via SetOptionDouble must be retrievable via GetOptionDouble.) Drivers may also support getting a converted option value via other getters if needed. (For example, getting the string representation of a double option.)

Since: ADBC API revision 1.1.0

Parameters

[in]	connection	The database connection.
[in]	key	The option to get.
[out]	value	The option value.
[out]	error	An optional location to return an error message if necessary.

Returns: ADBC_STATUS_NOT_FOUND if the option is not recognized.

◆ AdbcConnectionGetStatisticNames()

AdbcStatusCode AdbcConnectionGetStatisticNames	(	struct AdbcConnection *	connection,
		struct ArrowArrayStream *	out,
		struct AdbcError *	error )

Get the names of statistics specific to this driver.

The result is an Arrow dataset with the following schema:

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

Since: ADBC API revision 1.1.0

Parameters

[in]	connection	The database connection.
[out]	out	The result set.
[out]	error	Error details, if an error occurs.

◆ AdbcConnectionGetStatistics()

AdbcStatusCode AdbcConnectionGetStatistics	(	struct AdbcConnection *	connection,
		const char *	catalog,
		const char *	db_schema,
		const char *	table_name,
		char	approximate,
		struct ArrowArrayStream *	out,
		struct AdbcError *	error )

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

The result is an Arrow dataset with the following 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:

Field Name	Field Type
db_schema_name	utf8
db_schema_statistics	list<STATISTICS_SCHEMA> not null

STATISTICS_SCHEMA is a Struct with fields:

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)

If null, then the statistic applies to the entire table.
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 ADBC Statistic Types. To get driver-specific statistic names, use AdbcConnectionGetStatisticNames.
If true, then the value is approximate or best-effort.

VALUE_SCHEMA is a dense union with members:

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

This AdbcConnection must outlive the returned ArrowArrayStream.

Since: ADBC API revision 1.1.0

Parameters

[in]	connection	The database connection.
[in]	catalog	The catalog (or nullptr). May be a search pattern (see section documentation).
[in]	db_schema	The database schema (or nullptr). May be a search pattern (see section documentation).
[in]	table_name	The table name (or nullptr). May be a search pattern (see section documentation).
[in]	approximate	If zero, 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.
[out]	out	The result set.
[out]	error	Error details, if an error occurs.

◆ AdbcConnectionGetTableSchema()

AdbcStatusCode AdbcConnectionGetTableSchema	(	struct AdbcConnection *	connection,
		const char *	catalog,
		const char *	db_schema,
		const char *	table_name,
		struct ArrowSchema *	schema,
		struct AdbcError *	error )

Get the Arrow schema of a table.

Parameters

[in]	connection	The database connection.
[in]	catalog	The catalog (or nullptr if not applicable).
[in]	db_schema	The database schema (or nullptr if not applicable).
[in]	table_name	The table name.
[out]	schema	The table schema.
[out]	error	Error details, if an error occurs.

◆ AdbcConnectionGetTableTypes()

AdbcStatusCode AdbcConnectionGetTableTypes	(	struct AdbcConnection *	connection,
		struct ArrowArrayStream *	out,
		struct AdbcError *	error )

Get a list of table types in the database.

The result is an Arrow dataset with the following schema:

Field Name	Field Type
table_type	utf8 not null

This AdbcConnection must outlive the returned ArrowArrayStream.

Parameters

[in]	connection	The database connection.
[out]	out	The result set.
[out]	error	Error details, if an error occurs.