From 2d08fe1996e7e22db9c8197ef8ccd8233d3f916f Mon Sep 17 00:00:00 2001
From: David Li
Date: Mon, 20 Jul 2026 15:48:53 +0900
Subject: [PATCH 1/6] feat(format): add generic metadata API
Closes #4400.
---
c/include/arrow-adbc/adbc.h | 609 ++++++++++++++++++++++++++++
go/adbc/drivermgr/arrow-adbc/adbc.h | 609 ++++++++++++++++++++++++++++
2 files changed, 1218 insertions(+)
diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
index 82f05564a73..70cca524f02 100644
--- a/c/include/arrow-adbc/adbc.h
+++ b/c/include/arrow-adbc/adbc.h
@@ -607,6 +607,12 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \see AdbcConnectionGetObjects
#define ADBC_INFO_FEATURE_TABLE_TYPES 222
+/// \brief Whether the driver supports getting metadata collections (type: bool).
+/// \since ADBC API revision 1.2.0
+/// \see AdbcConnectionGetInfo
+/// \see ADBC_METADATA_COLLECTION
+#define ADBC_INFO_FEATURE_METADATA_COLLECTION 223
+
/// \brief Whether the driver supports transactions (true), or if autocommit
/// is always enabled (false) (type: bool).
/// \since ADBC API revision 1.2.0
@@ -1087,6 +1093,609 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// @}
+/// \defgroup adbc-statement-metadata-collection Metadata Collections
+///
+/// Fetch (catalog) metadata from the database. On a statement, set
+/// ADBC_METADATA_COLLECTION to one of the collection names below, and set any
+/// filters via the options defined below. (There are driver/vendor-specific
+/// collections and filters as well.) Then call AdbcStatementExecuteQuery or
+/// AdbcStatementExecuteSchema. The result is an Arrow dataset with a schema
+/// defined by the collection. For example, a client may request a list of
+/// tables in the database, or a list of supported data types.
+///
+/// All drivers must implement a collection called "meta" (which is aliased to
+/// NULL and blank string) that defines the available collections. See
+/// ADBC_METADATA_COLLECTION_META.
+///
+/// Drivers may also implement AdbcStatementRequestSchema to (1) request
+/// different data types and (2) drop fields from the result. Drivers are not
+/// required to support this, and are not required to support other changes
+/// like reordering collection fields. Drivers are encouraged to use this to
+/// give applications flexibility over output type and shape (e.g. reducing
+/// memory pressure by run-end-encoding or dictionary-encoding primary key
+/// columns; optimizing queries by using simpler queries and eliminating joins
+/// if the application drops certain columns).
+///
+/// Drivers may add more fields at the end of standard schemas to reflect
+/// vendor-specific metadata. Applications must access these using an offset
+/// from the end of the schema and cannot assume that the index of the field
+/// will remain stable. Drivers must add the fields at the end and must
+/// prefix field names with the vendor/driver name to differentiate them
+/// (e.g. 'POSTGRESQL:owner', not just 'owner').
+///
+/// Similarly, future standard revisions may add more fields to existing
+/// standard schemas. Applications must not assume the number of fields is
+/// fixed.
+///
+/// Drivers may implement collections beyond those defined by ADBC, but must
+/// use a vendor-specific prefix (e.g. `postgresql.`) to avoid conflicts with
+/// future standardized collections. Drivers must not use the `adbc.` prefix.
+///
+/// Drivers may not necessarily accept filter options or other options before
+/// the collection name option is set.
+///
+/// This is intended to replace AdbcConnectionGetObjects, but both APIs will
+/// be supported for the time being. AdbcConnectionGetObjects may be
+/// deprecated in a future revision.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// @{
+
+/// \brief Prepare to fetch a metadata collection.
+///
+/// The type is char*.
+#define ADBC_METADATA_COLLECTION "adbc.metadata.collection"
+
+/// \brief Filter the collection on the literal catalog name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_CATALOG "adbc.metadata.filter.catalog"
+
+/// \brief Filter the collection on the catalog name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_CATALOG are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_CATALOG "adbc.metadata.filter_pattern.catalog"
+
+/// \brief Filter the collection on the literal schema name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.schema"
+
+/// \brief Filter the collection on the schema name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_DB_SCHEMA are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATERN_DB_SCHEMA "adbc.metadata.filter_pattern.schema"
+
+/// \brief Filter the collection on the literal table name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_TABLE "adbc.metadata.filter.table"
+
+/// \brief Filter the collection on the table name, matching a search pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_TABLE are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_TABLE "adbc.metadata.filter_pattern.table"
+
+/// \brief Filter the collection on the literal column name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_COLUMN "adbc.metadata.filter.column"
+
+/// \brief Filter the collection on the column name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_COLUMN are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_COLUMN "adbc.metadata.filter_pattern.column"
+
+/// \brief Filter the collection on the table types.
+///
+/// Separator: comma (',').
+/// The type is char*.
+#define ADBC_METADATA_FILTER_TABLE_TYPES "adbc.metadata.filter.table_types"
+
+/// \brief Filter the collection on the literal catalog name of the foreign
+/// key.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_FOREIGN_CATALOG "adbc.metadata.filter.foreign_catalog"
+
+/// \brief Filter the collection on the literal catalog name of the foreign
+/// key.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA "adbc.metadata.filter.foreign_schema"
+
+/// \brief Filter the collection on the literal catalog name of the foreign
+/// key.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_FOREIGN_TABLE "adbc.metadata.filter.foreign_table"
+
+/// \brief Filter the collection on the literal constraint name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_CONSTRAINT "adbc.metadata.filter.constraint"
+
+/// \brief Filter the collection on the constraint name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_CONSTRAINT are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_CONSTRAINT "adbc.metadata.filter_pattern.constraint"
+
+/// \brief Filter the collection on the constraint types.
+///
+/// Separator: comma (',').
+/// The type is char*.
+#define ADBC_METADATA_FILTER_CONSTRAINT_TYPES "adbc.metadata.filter.constraint_types"
+
+/// \brief Filter the collection on the literal routine name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_ROUTINE "adbc.metadata.filter.routine"
+
+/// \brief Filter the collection on the routine name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_ROUTINE are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_ROUTINE "adbc.metadata.filter_pattern.routine"
+
+/// \brief Filter the collection on the routine types.
+///
+/// Separator: comma (',').
+/// The type is char*.
+#define ADBC_METADATA_FILTER_ROUTINE_TYPES "adbc.metadata.filter.routine_types"
+
+/// \brief Only show namespaces in the given multi-part namespace.
+///
+/// Separator: ASCII unit separator (0x1F).
+/// The type is char*.
+#define ADBC_METADATA_FILTER_NAMESPACE "adbc.metadata.filter.namespace"
+
+/// \brief Only show namespaces with the given name. This filter only applies
+/// to the last namespace component.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_NAMESPACE_NAME "adbc.metadata.filter.namespace_name"
+
+/// \brief Get or set a pagination token.
+///
+/// Some drivers may support this to allow fetching a large metadata
+/// collection in multiple calls. If the pagination token could not be used,
+/// the driver should return an error.
+#define ADBC_METADATA_OPTION_PAGINATION_TOKEN "adbc.metadata.pagination_token"
+
+/// \brief The "meta" collection returns the available metadata collections.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | collection_name | utf8 not null | |
+/// | collection_description | utf8 | |
+/// | collection_schema | extension | |
+/// | collection_filters | list | |
+///
+/// FILTER_SCHEMA is a Struct with fields:
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | filter_description | utf8 | |
+/// | required | bool not null | |
+#define ADBC_METADATA_COLLECTION_META "meta"
+
+/// \brief The "catalogs" collection returns the catalogs defined in the
+/// database.
+///
+/// Some systems may not have the concept of catalogs, in which case this
+/// collection should contain a single entry with an empty, non-null name.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | catalog_remarks | utf8 | (1) |
+///
+/// (1) A description of the catalog.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+#define ADBC_METADATA_COLLECTION_CATALOGS "catalogs"
+
+/// \brief The "schemas" collection returns the schemas defined in the
+/// database.
+///
+/// Some systems may not have the concept of schemas, in which case this
+/// collection should contain a single entry per catalog with an empty,
+/// non-null name.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | db_schema_name | utf8 | |
+/// | db_schema_remarks | utf8 | (1) |
+///
+/// (1) A description of the schema.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+#define ADBC_METADATA_COLLECTION_SCHEMAS "schemas"
+
+/// \brief The "tables" collection returns the tables defined in the
+/// database.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | db_schema_name | utf8 | |
+/// | table_name | utf8 not null | |
+/// | table_type | utf8 not null | |
+/// | table_definition | utf8 | (1) |
+/// | table_remarks | utf8 | (2) |
+/// | table_schema | extension | (3) |
+///
+/// (1) The table or view definition (e.g. the SQL DDL statement).
+/// (2) A description of the table.
+/// (3) The Arrow schema of the table, equivalent to
+/// AdbcConnectionGetTableSchema.
+///
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_TABLE_TYPES
+#define ADBC_METADATA_COLLECTION_TABLES "tables"
+
+/// \brief The "columns" collection returns table columns.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | db_schema_name | utf8 | |
+/// | table_name | utf8 not null | |
+/// | 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) |
+/// | xdbc_source_data_type | bool | (3) |
+///
+/// 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.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_TABLE_TYPES
+/// - ADBC_METADATA_FILTER_COLUMN
+/// - ADBC_METADATA_FILTER_PATTERN_COLUMN
+#define ADBC_METADATA_COLLECTION_COLUMNS "columns"
+
+/// \brief The "imported_keys" collection, given a table, describes the
+/// primary key(s) referenced by the given table's foreign key(s).
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | pk_catalog_name | utf8 | |
+/// | pk_schema_name | utf8 | |
+/// | pk_table_name | utf8 not null | |
+/// | pk_column_name | utf8 not null | |
+/// | pk_name | utf8 | |
+/// | fk_catalog_name | utf8 | |
+/// | fk_schema_name | utf8 | |
+/// | fk_table_name | utf8 not null | |
+/// | fk_column_name | utf8 not null | |
+/// | fk_name | utf8 | |
+/// | key_seq | int16 | (1) |
+/// | constraint_update_rule | int16 | (2) |
+/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_enforced | bool | (3) |
+/// | constraint_deferrability | int16 | (4) |
+/// | constraint_match_type | int16 | (5) |
+///
+/// 1. The 1-based index of the column pair within the foreign key (1 => first
+/// column of the foreign key, 2 => second column of the foreign key, ...).
+/// 2. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 3. Whether the constraint is currently enabled.
+/// 4. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 5. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Filters:
+/// - ADBC_METADATA_FILTER_CATALOG (applies to fk_catalog_name)
+/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to fk_schema_name)
+/// - ADBC_METADATA_FILTER_TABLE (required; applies to fk_table_name)
+#define ADBC_METADATA_COLLECTION_IMPORTED_KEYS "imported_keys"
+
+/// \brief The "exported_keys" collection, given a table, describes the
+/// foreign key(s) referencing the given table's primary key(s).
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | pk_catalog_name | utf8 | |
+/// | pk_schema_name | utf8 | |
+/// | pk_table_name | utf8 not null | |
+/// | pk_column_name | utf8 not null | |
+/// | pk_name | utf8 | |
+/// | fk_catalog_name | utf8 | |
+/// | fk_schema_name | utf8 | |
+/// | fk_table_name | utf8 not null | |
+/// | fk_column_name | utf8 not null | |
+/// | fk_name | utf8 | |
+/// | key_seq | int16 | (1) |
+/// | constraint_update_rule | int16 | (2) |
+/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_enforced | bool | (3) |
+/// | constraint_deferrability | int16 | (4) |
+/// | constraint_match_type | int16 | (5) |
+///
+/// 1. The 1-based index of the column pair within the foreign key (1 => first
+/// column of the foreign key, 2 => second column of the foreign key, ...).
+/// 2. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 3. Whether the constraint is currently enabled.
+/// 4. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 5. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Filters:
+/// - ADBC_METADATA_FILTER_CATALOG (applies to pk_catalog_name)
+/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to pk_schema_name)
+/// - ADBC_METADATA_FILTER_TABLE (required; applies to pk_table_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_CATALOG (applies to fk_catalog_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA (applies to fk_schema_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_TABLE (required; applies to fk_table_name)
+#define ADBC_METADATA_COLLECTION_EXPORTED_KEYS "exported_keys"
+
+/// \brief The "cross_reference" collection, given a "parent" table and a
+/// "foreign" table, describes the foreign key(s) in the "foreign" table
+/// referencing the "parent" table's primary key(s) or unique columns.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | pk_catalog_name | utf8 | |
+/// | pk_schema_name | utf8 | |
+/// | pk_table_name | utf8 not null | |
+/// | pk_column_name | utf8 not null | |
+/// | pk_name | utf8 | |
+/// | fk_catalog_name | utf8 | |
+/// | fk_schema_name | utf8 | |
+/// | fk_table_name | utf8 not null | |
+/// | fk_column_name | utf8 not null | |
+/// | fk_name | utf8 | |
+/// | key_seq | int16 | (1) |
+/// | constraint_update_rule | int16 | (2) |
+/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_enforced | bool | (3) |
+/// | constraint_deferrability | int16 | (4) |
+/// | constraint_match_type | int16 | (5) |
+///
+/// 1. The 1-based index of the column pair within the foreign key (1 => first
+/// column of the foreign key, 2 => second column of the foreign key, ...).
+/// 2. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 3. Whether the constraint is currently enabled.
+/// 4. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 5. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Filters:
+/// 1. The catalog of the parent table; required but may be NULL.
+/// 2. The schema of the parent table; required but may be NULL.
+/// 3. The name of the parent table; required.
+/// 4. The catalog of the foreign table; required but may be NULL.
+/// 5. The schema of the foreign table; required but may be NULL.
+/// 6. The name of the foreign table; required.
+#define ADBC_METADATA_COLLECTION_CROSS_REFERENCE "cross_reference"
+
+/// \brief The "constraints" collection describes constraints on the selected
+/// tables: primary keys, foreign keys, unique columns, and check
+/// constraints.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | schema_name | utf8 | |
+/// | table_name | utf8 not null | |
+/// | constraint_name | utf8 | |
+/// | constraint_type | utf8 not null | (1) |
+/// | constraint_column_names | list not null | (2) |
+/// | constraint_expression | utf8 | (3) |
+/// | constraint_update_rule | int16 | (4) |
+/// | constraint_delete_rule | int16 | (4) |
+/// | constraint_enforced | bool | (5) |
+/// | constraint_deferrability | int16 | (6) |
+/// | constraint_match_type | int16 | (7) |
+///
+/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE', or a
+/// vendor-specific type.
+/// 2. The columns on the current table that are constrained, in
+/// order.
+/// 3. The vendor-specific definition of the constraint (e.g. the SQL
+/// expression to be checked).
+/// 4. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 5. Whether the constraint is currently enabled.
+/// 6. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 7. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_CONSTRAINT
+/// - ADBC_METADATA_FILTER_PATTERN_CONSTRAINT
+/// - ADBC_METADATA_FILTER_CONSTRAINT_TYPES
+#define ADBC_METADATA_COLLECTION_CONSTRAINTS "constraints"
+
+/// \brief The "routines" collection returns functions and procedures.
+///
+/// | Field Name | Field Type | Comments |
+/// |-----------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | schema_name | utf8 | |
+/// | routine_name | utf8 not null | |
+/// | routine_type | utf8 not null | (1) |
+/// | routine_specific_name | utf8 | (2) |
+/// | routine_remarks | utf8 | (3) |
+/// | routine_examples | list | (3) |
+/// | routine_definition | utf8 | (4) |
+/// | routine_definition_language | utf8 | (4) |
+/// | routine_parameter_schema | extension | (5) |
+/// | routine_result_schema | extension | (5) |
+///
+/// 1. 'FUNCTION', 'PROCEDURE', or a vendor-specific name (e.g. 'TABLE
+/// FUNCTION').
+/// 2. A name that uniquely identifies the routine, to disambiguate
+/// overloads.
+/// 3. Vendor-specific description or help text, along with examples of the
+/// syntax.
+/// 4. The definition (e.g. SQL text used to create a procedure) and the
+/// language of the definition (e.g. SQL, Python)
+/// 5. Metadata about the accepted parameters and return values as an Arrow
+/// schema.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_ROUTINE
+/// - ADBC_METADATA_FILTER_PATTERN_ROUTINE
+/// - ADBC_METADATA_FILTER_ROUTINE_TYPES
+#define ADBC_METADATA_COLLECTION_ROUTINES "routines"
+
+/// \brief The "routine_columns" collection returns input/output columns and
+/// parameters of functions and procedures.
+///
+/// | Field Name | Field Type | Comments |
+/// |-----------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | schema_name | utf8 | |
+/// | routine_name | utf8 not null | |
+/// | routine_type | utf8 not null | |
+/// | routine_specific_name | utf8 | |
+/// | column_name | utf8 | |
+/// | ordinal_position | int32 | (1) |
+/// | column_remarks | utf8 | (2) |
+/// | column_type | utf8 | (3) |
+/// | xdbc_data_type | int16 | (4) |
+/// | xdbc_type_name | utf8 | (4) |
+/// | xdbc_precision | int32 | (4) |
+/// | xdbc_length | int32 | (4) |
+/// | xdbc_scale | int16 | (4) |
+/// | xdbc_radix | int16 | (4) |
+/// | xdbc_nullable | int16 | (4) |
+/// | xdbc_column_def | utf8 | (4) |
+/// | xdbc_sql_data_type | int16 | (4) |
+/// | xdbc_datetime_sub | int16 | (4) |
+/// | xdbc_char_octet_length | int32 | (4) |
+/// | xdbc_is_nullable | utf8 | (4) |
+///
+/// 1. The ordinal position of the parameter or return value (1-indexed).
+/// 2. Vendor-specific description of the parameter or return value.
+/// 3. The type of column or parameter; NULL if not known. Otherwise, 'IN',
+/// 'OUT', 'INOUT', 'RETURN', 'RESULT', or a vendor-specific name.
+/// 4. 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.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_ROUTINE
+/// - ADBC_METADATA_FILTER_PATTERN_ROUTINE
+/// - ADBC_METADATA_FILTER_ROUTINE_TYPES
+/// - ADBC_METADATA_FILTER_COLUMN
+/// - ADBC_METADATA_FILTER_PATTERN_COLUMN
+#define ADBC_METADATA_COLLECTION_ROUTINE_COLUMNS "routine_columns"
+
+/// \brief The "namespaces" collection returns a level of namespaces defined
+/// in the database.
+///
+/// This collection generally results in an "N+1" query pattern. This is
+/// intended for systems that do not follow the SQL catalog-schema-table
+/// hierarchy; for systems that do, collections like "catalogs", "schemas",
+/// and "tables" will be more efficient as they can return multiple levels at
+/// once.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | namespace_parent | list not null | |
+/// | namespace_name | utf8 not null | |
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_NAMESPACE
+/// - ADBC_METADATA_FILTER_NAMESPACE_NAME
+#define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces"
+
+/// @}
+
/// @}
/// \defgroup adbc-database Database Initialization
diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h b/go/adbc/drivermgr/arrow-adbc/adbc.h
index 82f05564a73..70cca524f02 100644
--- a/go/adbc/drivermgr/arrow-adbc/adbc.h
+++ b/go/adbc/drivermgr/arrow-adbc/adbc.h
@@ -607,6 +607,12 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \see AdbcConnectionGetObjects
#define ADBC_INFO_FEATURE_TABLE_TYPES 222
+/// \brief Whether the driver supports getting metadata collections (type: bool).
+/// \since ADBC API revision 1.2.0
+/// \see AdbcConnectionGetInfo
+/// \see ADBC_METADATA_COLLECTION
+#define ADBC_INFO_FEATURE_METADATA_COLLECTION 223
+
/// \brief Whether the driver supports transactions (true), or if autocommit
/// is always enabled (false) (type: bool).
/// \since ADBC API revision 1.2.0
@@ -1087,6 +1093,609 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// @}
+/// \defgroup adbc-statement-metadata-collection Metadata Collections
+///
+/// Fetch (catalog) metadata from the database. On a statement, set
+/// ADBC_METADATA_COLLECTION to one of the collection names below, and set any
+/// filters via the options defined below. (There are driver/vendor-specific
+/// collections and filters as well.) Then call AdbcStatementExecuteQuery or
+/// AdbcStatementExecuteSchema. The result is an Arrow dataset with a schema
+/// defined by the collection. For example, a client may request a list of
+/// tables in the database, or a list of supported data types.
+///
+/// All drivers must implement a collection called "meta" (which is aliased to
+/// NULL and blank string) that defines the available collections. See
+/// ADBC_METADATA_COLLECTION_META.
+///
+/// Drivers may also implement AdbcStatementRequestSchema to (1) request
+/// different data types and (2) drop fields from the result. Drivers are not
+/// required to support this, and are not required to support other changes
+/// like reordering collection fields. Drivers are encouraged to use this to
+/// give applications flexibility over output type and shape (e.g. reducing
+/// memory pressure by run-end-encoding or dictionary-encoding primary key
+/// columns; optimizing queries by using simpler queries and eliminating joins
+/// if the application drops certain columns).
+///
+/// Drivers may add more fields at the end of standard schemas to reflect
+/// vendor-specific metadata. Applications must access these using an offset
+/// from the end of the schema and cannot assume that the index of the field
+/// will remain stable. Drivers must add the fields at the end and must
+/// prefix field names with the vendor/driver name to differentiate them
+/// (e.g. 'POSTGRESQL:owner', not just 'owner').
+///
+/// Similarly, future standard revisions may add more fields to existing
+/// standard schemas. Applications must not assume the number of fields is
+/// fixed.
+///
+/// Drivers may implement collections beyond those defined by ADBC, but must
+/// use a vendor-specific prefix (e.g. `postgresql.`) to avoid conflicts with
+/// future standardized collections. Drivers must not use the `adbc.` prefix.
+///
+/// Drivers may not necessarily accept filter options or other options before
+/// the collection name option is set.
+///
+/// This is intended to replace AdbcConnectionGetObjects, but both APIs will
+/// be supported for the time being. AdbcConnectionGetObjects may be
+/// deprecated in a future revision.
+///
+/// \since ADBC API revision 1.2.0
+///
+/// @{
+
+/// \brief Prepare to fetch a metadata collection.
+///
+/// The type is char*.
+#define ADBC_METADATA_COLLECTION "adbc.metadata.collection"
+
+/// \brief Filter the collection on the literal catalog name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_CATALOG "adbc.metadata.filter.catalog"
+
+/// \brief Filter the collection on the catalog name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_CATALOG are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_CATALOG "adbc.metadata.filter_pattern.catalog"
+
+/// \brief Filter the collection on the literal schema name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.schema"
+
+/// \brief Filter the collection on the schema name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_DB_SCHEMA are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATERN_DB_SCHEMA "adbc.metadata.filter_pattern.schema"
+
+/// \brief Filter the collection on the literal table name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_TABLE "adbc.metadata.filter.table"
+
+/// \brief Filter the collection on the table name, matching a search pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_TABLE are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_TABLE "adbc.metadata.filter_pattern.table"
+
+/// \brief Filter the collection on the literal column name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_COLUMN "adbc.metadata.filter.column"
+
+/// \brief Filter the collection on the column name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_COLUMN are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_COLUMN "adbc.metadata.filter_pattern.column"
+
+/// \brief Filter the collection on the table types.
+///
+/// Separator: comma (',').
+/// The type is char*.
+#define ADBC_METADATA_FILTER_TABLE_TYPES "adbc.metadata.filter.table_types"
+
+/// \brief Filter the collection on the literal catalog name of the foreign
+/// key.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_FOREIGN_CATALOG "adbc.metadata.filter.foreign_catalog"
+
+/// \brief Filter the collection on the literal catalog name of the foreign
+/// key.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA "adbc.metadata.filter.foreign_schema"
+
+/// \brief Filter the collection on the literal catalog name of the foreign
+/// key.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_FOREIGN_TABLE "adbc.metadata.filter.foreign_table"
+
+/// \brief Filter the collection on the literal constraint name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_CONSTRAINT "adbc.metadata.filter.constraint"
+
+/// \brief Filter the collection on the constraint name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_CONSTRAINT are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_CONSTRAINT "adbc.metadata.filter_pattern.constraint"
+
+/// \brief Filter the collection on the constraint types.
+///
+/// Separator: comma (',').
+/// The type is char*.
+#define ADBC_METADATA_FILTER_CONSTRAINT_TYPES "adbc.metadata.filter.constraint_types"
+
+/// \brief Filter the collection on the literal routine name.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_ROUTINE "adbc.metadata.filter.routine"
+
+/// \brief Filter the collection on the routine name, matching a search
+/// pattern.
+///
+/// If both this and ADBC_METADATA_FILTER_ROUTINE are set, then the last set
+/// option wins.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_PATTERN_ROUTINE "adbc.metadata.filter_pattern.routine"
+
+/// \brief Filter the collection on the routine types.
+///
+/// Separator: comma (',').
+/// The type is char*.
+#define ADBC_METADATA_FILTER_ROUTINE_TYPES "adbc.metadata.filter.routine_types"
+
+/// \brief Only show namespaces in the given multi-part namespace.
+///
+/// Separator: ASCII unit separator (0x1F).
+/// The type is char*.
+#define ADBC_METADATA_FILTER_NAMESPACE "adbc.metadata.filter.namespace"
+
+/// \brief Only show namespaces with the given name. This filter only applies
+/// to the last namespace component.
+///
+/// The type is char*.
+#define ADBC_METADATA_FILTER_NAMESPACE_NAME "adbc.metadata.filter.namespace_name"
+
+/// \brief Get or set a pagination token.
+///
+/// Some drivers may support this to allow fetching a large metadata
+/// collection in multiple calls. If the pagination token could not be used,
+/// the driver should return an error.
+#define ADBC_METADATA_OPTION_PAGINATION_TOKEN "adbc.metadata.pagination_token"
+
+/// \brief The "meta" collection returns the available metadata collections.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | collection_name | utf8 not null | |
+/// | collection_description | utf8 | |
+/// | collection_schema | extension | |
+/// | collection_filters | list | |
+///
+/// FILTER_SCHEMA is a Struct with fields:
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | filter_description | utf8 | |
+/// | required | bool not null | |
+#define ADBC_METADATA_COLLECTION_META "meta"
+
+/// \brief The "catalogs" collection returns the catalogs defined in the
+/// database.
+///
+/// Some systems may not have the concept of catalogs, in which case this
+/// collection should contain a single entry with an empty, non-null name.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | catalog_remarks | utf8 | (1) |
+///
+/// (1) A description of the catalog.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+#define ADBC_METADATA_COLLECTION_CATALOGS "catalogs"
+
+/// \brief The "schemas" collection returns the schemas defined in the
+/// database.
+///
+/// Some systems may not have the concept of schemas, in which case this
+/// collection should contain a single entry per catalog with an empty,
+/// non-null name.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | db_schema_name | utf8 | |
+/// | db_schema_remarks | utf8 | (1) |
+///
+/// (1) A description of the schema.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+#define ADBC_METADATA_COLLECTION_SCHEMAS "schemas"
+
+/// \brief The "tables" collection returns the tables defined in the
+/// database.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | db_schema_name | utf8 | |
+/// | table_name | utf8 not null | |
+/// | table_type | utf8 not null | |
+/// | table_definition | utf8 | (1) |
+/// | table_remarks | utf8 | (2) |
+/// | table_schema | extension | (3) |
+///
+/// (1) The table or view definition (e.g. the SQL DDL statement).
+/// (2) A description of the table.
+/// (3) The Arrow schema of the table, equivalent to
+/// AdbcConnectionGetTableSchema.
+///
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_TABLE_TYPES
+#define ADBC_METADATA_COLLECTION_TABLES "tables"
+
+/// \brief The "columns" collection returns table columns.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | db_schema_name | utf8 | |
+/// | table_name | utf8 not null | |
+/// | 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) |
+/// | xdbc_source_data_type | bool | (3) |
+///
+/// 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.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_TABLE_TYPES
+/// - ADBC_METADATA_FILTER_COLUMN
+/// - ADBC_METADATA_FILTER_PATTERN_COLUMN
+#define ADBC_METADATA_COLLECTION_COLUMNS "columns"
+
+/// \brief The "imported_keys" collection, given a table, describes the
+/// primary key(s) referenced by the given table's foreign key(s).
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | pk_catalog_name | utf8 | |
+/// | pk_schema_name | utf8 | |
+/// | pk_table_name | utf8 not null | |
+/// | pk_column_name | utf8 not null | |
+/// | pk_name | utf8 | |
+/// | fk_catalog_name | utf8 | |
+/// | fk_schema_name | utf8 | |
+/// | fk_table_name | utf8 not null | |
+/// | fk_column_name | utf8 not null | |
+/// | fk_name | utf8 | |
+/// | key_seq | int16 | (1) |
+/// | constraint_update_rule | int16 | (2) |
+/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_enforced | bool | (3) |
+/// | constraint_deferrability | int16 | (4) |
+/// | constraint_match_type | int16 | (5) |
+///
+/// 1. The 1-based index of the column pair within the foreign key (1 => first
+/// column of the foreign key, 2 => second column of the foreign key, ...).
+/// 2. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 3. Whether the constraint is currently enabled.
+/// 4. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 5. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Filters:
+/// - ADBC_METADATA_FILTER_CATALOG (applies to fk_catalog_name)
+/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to fk_schema_name)
+/// - ADBC_METADATA_FILTER_TABLE (required; applies to fk_table_name)
+#define ADBC_METADATA_COLLECTION_IMPORTED_KEYS "imported_keys"
+
+/// \brief The "exported_keys" collection, given a table, describes the
+/// foreign key(s) referencing the given table's primary key(s).
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | pk_catalog_name | utf8 | |
+/// | pk_schema_name | utf8 | |
+/// | pk_table_name | utf8 not null | |
+/// | pk_column_name | utf8 not null | |
+/// | pk_name | utf8 | |
+/// | fk_catalog_name | utf8 | |
+/// | fk_schema_name | utf8 | |
+/// | fk_table_name | utf8 not null | |
+/// | fk_column_name | utf8 not null | |
+/// | fk_name | utf8 | |
+/// | key_seq | int16 | (1) |
+/// | constraint_update_rule | int16 | (2) |
+/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_enforced | bool | (3) |
+/// | constraint_deferrability | int16 | (4) |
+/// | constraint_match_type | int16 | (5) |
+///
+/// 1. The 1-based index of the column pair within the foreign key (1 => first
+/// column of the foreign key, 2 => second column of the foreign key, ...).
+/// 2. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 3. Whether the constraint is currently enabled.
+/// 4. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 5. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Filters:
+/// - ADBC_METADATA_FILTER_CATALOG (applies to pk_catalog_name)
+/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to pk_schema_name)
+/// - ADBC_METADATA_FILTER_TABLE (required; applies to pk_table_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_CATALOG (applies to fk_catalog_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA (applies to fk_schema_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_TABLE (required; applies to fk_table_name)
+#define ADBC_METADATA_COLLECTION_EXPORTED_KEYS "exported_keys"
+
+/// \brief The "cross_reference" collection, given a "parent" table and a
+/// "foreign" table, describes the foreign key(s) in the "foreign" table
+/// referencing the "parent" table's primary key(s) or unique columns.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | pk_catalog_name | utf8 | |
+/// | pk_schema_name | utf8 | |
+/// | pk_table_name | utf8 not null | |
+/// | pk_column_name | utf8 not null | |
+/// | pk_name | utf8 | |
+/// | fk_catalog_name | utf8 | |
+/// | fk_schema_name | utf8 | |
+/// | fk_table_name | utf8 not null | |
+/// | fk_column_name | utf8 not null | |
+/// | fk_name | utf8 | |
+/// | key_seq | int16 | (1) |
+/// | constraint_update_rule | int16 | (2) |
+/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_enforced | bool | (3) |
+/// | constraint_deferrability | int16 | (4) |
+/// | constraint_match_type | int16 | (5) |
+///
+/// 1. The 1-based index of the column pair within the foreign key (1 => first
+/// column of the foreign key, 2 => second column of the foreign key, ...).
+/// 2. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 3. Whether the constraint is currently enabled.
+/// 4. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 5. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Filters:
+/// 1. The catalog of the parent table; required but may be NULL.
+/// 2. The schema of the parent table; required but may be NULL.
+/// 3. The name of the parent table; required.
+/// 4. The catalog of the foreign table; required but may be NULL.
+/// 5. The schema of the foreign table; required but may be NULL.
+/// 6. The name of the foreign table; required.
+#define ADBC_METADATA_COLLECTION_CROSS_REFERENCE "cross_reference"
+
+/// \brief The "constraints" collection describes constraints on the selected
+/// tables: primary keys, foreign keys, unique columns, and check
+/// constraints.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|-------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | schema_name | utf8 | |
+/// | table_name | utf8 not null | |
+/// | constraint_name | utf8 | |
+/// | constraint_type | utf8 not null | (1) |
+/// | constraint_column_names | list not null | (2) |
+/// | constraint_expression | utf8 | (3) |
+/// | constraint_update_rule | int16 | (4) |
+/// | constraint_delete_rule | int16 | (4) |
+/// | constraint_enforced | bool | (5) |
+/// | constraint_deferrability | int16 | (6) |
+/// | constraint_match_type | int16 | (7) |
+///
+/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE', or a
+/// vendor-specific type.
+/// 2. The columns on the current table that are constrained, in
+/// order.
+/// 3. The vendor-specific definition of the constraint (e.g. the SQL
+/// expression to be checked).
+/// 4. If applicable, the action to be taken when the primary key is updated
+/// or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ constants.
+/// 5. Whether the constraint is currently enabled.
+/// 6. Whether the constraint can be deferred, and if so, whether it starts
+/// deferred. The value is one of the ADBC_CONSTRAINT_DEFERRABLE_
+/// constants or ADBC_CONSTRAINT_NOT_DEFERRABLE.
+/// 7. How the foreign key constraint should be matched. The value is one of
+/// the ADBC_CONSTRAINT_MATCH_ constants.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_CONSTRAINT
+/// - ADBC_METADATA_FILTER_PATTERN_CONSTRAINT
+/// - ADBC_METADATA_FILTER_CONSTRAINT_TYPES
+#define ADBC_METADATA_COLLECTION_CONSTRAINTS "constraints"
+
+/// \brief The "routines" collection returns functions and procedures.
+///
+/// | Field Name | Field Type | Comments |
+/// |-----------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | schema_name | utf8 | |
+/// | routine_name | utf8 not null | |
+/// | routine_type | utf8 not null | (1) |
+/// | routine_specific_name | utf8 | (2) |
+/// | routine_remarks | utf8 | (3) |
+/// | routine_examples | list | (3) |
+/// | routine_definition | utf8 | (4) |
+/// | routine_definition_language | utf8 | (4) |
+/// | routine_parameter_schema | extension | (5) |
+/// | routine_result_schema | extension | (5) |
+///
+/// 1. 'FUNCTION', 'PROCEDURE', or a vendor-specific name (e.g. 'TABLE
+/// FUNCTION').
+/// 2. A name that uniquely identifies the routine, to disambiguate
+/// overloads.
+/// 3. Vendor-specific description or help text, along with examples of the
+/// syntax.
+/// 4. The definition (e.g. SQL text used to create a procedure) and the
+/// language of the definition (e.g. SQL, Python)
+/// 5. Metadata about the accepted parameters and return values as an Arrow
+/// schema.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_ROUTINE
+/// - ADBC_METADATA_FILTER_PATTERN_ROUTINE
+/// - ADBC_METADATA_FILTER_ROUTINE_TYPES
+#define ADBC_METADATA_COLLECTION_ROUTINES "routines"
+
+/// \brief The "routine_columns" collection returns input/output columns and
+/// parameters of functions and procedures.
+///
+/// | Field Name | Field Type | Comments |
+/// |-----------------------------|------------------------------|----------|
+/// | catalog_name | utf8 | |
+/// | schema_name | utf8 | |
+/// | routine_name | utf8 not null | |
+/// | routine_type | utf8 not null | |
+/// | routine_specific_name | utf8 | |
+/// | column_name | utf8 | |
+/// | ordinal_position | int32 | (1) |
+/// | column_remarks | utf8 | (2) |
+/// | column_type | utf8 | (3) |
+/// | xdbc_data_type | int16 | (4) |
+/// | xdbc_type_name | utf8 | (4) |
+/// | xdbc_precision | int32 | (4) |
+/// | xdbc_length | int32 | (4) |
+/// | xdbc_scale | int16 | (4) |
+/// | xdbc_radix | int16 | (4) |
+/// | xdbc_nullable | int16 | (4) |
+/// | xdbc_column_def | utf8 | (4) |
+/// | xdbc_sql_data_type | int16 | (4) |
+/// | xdbc_datetime_sub | int16 | (4) |
+/// | xdbc_char_octet_length | int32 | (4) |
+/// | xdbc_is_nullable | utf8 | (4) |
+///
+/// 1. The ordinal position of the parameter or return value (1-indexed).
+/// 2. Vendor-specific description of the parameter or return value.
+/// 3. The type of column or parameter; NULL if not known. Otherwise, 'IN',
+/// 'OUT', 'INOUT', 'RETURN', 'RESULT', or a vendor-specific name.
+/// 4. 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.
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG
+/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
+/// - ADBC_METADATA_FILTER_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
+/// - ADBC_METADATA_FILTER_TABLE
+/// - ADBC_METADATA_FILTER_PATTERN_TABLE
+/// - ADBC_METADATA_FILTER_ROUTINE
+/// - ADBC_METADATA_FILTER_PATTERN_ROUTINE
+/// - ADBC_METADATA_FILTER_ROUTINE_TYPES
+/// - ADBC_METADATA_FILTER_COLUMN
+/// - ADBC_METADATA_FILTER_PATTERN_COLUMN
+#define ADBC_METADATA_COLLECTION_ROUTINE_COLUMNS "routine_columns"
+
+/// \brief The "namespaces" collection returns a level of namespaces defined
+/// in the database.
+///
+/// This collection generally results in an "N+1" query pattern. This is
+/// intended for systems that do not follow the SQL catalog-schema-table
+/// hierarchy; for systems that do, collections like "catalogs", "schemas",
+/// and "tables" will be more efficient as they can return multiple levels at
+/// once.
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | namespace_parent | list not null | |
+/// | namespace_name | utf8 not null | |
+///
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_NAMESPACE
+/// - ADBC_METADATA_FILTER_NAMESPACE_NAME
+#define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces"
+
+/// @}
+
/// @}
/// \defgroup adbc-database Database Initialization
From ed2c607af8500c3ff184c5a12f287da34c70bfc4 Mon Sep 17 00:00:00 2001
From: David Li
Date: Mon, 31 Aug 2026 17:06:10 +0900
Subject: [PATCH 2/6] clarifications
---
c/include/arrow-adbc/adbc.h | 47 ++++++++-----------------------------
1 file changed, 10 insertions(+), 37 deletions(-)
diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
index 70cca524f02..9e1c2bba4d6 100644
--- a/c/include/arrow-adbc/adbc.h
+++ b/c/include/arrow-adbc/adbc.h
@@ -1114,14 +1114,18 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// give applications flexibility over output type and shape (e.g. reducing
/// memory pressure by run-end-encoding or dictionary-encoding primary key
/// columns; optimizing queries by using simpler queries and eliminating joins
-/// if the application drops certain columns).
+/// if the application drops certain columns). Unless requested, however,
+/// drivers should return the type specified below and not substitute a
+/// logically equivalent type (e.g. utf8 below should be a string array by
+/// default, and not a utf8view or large string or other array).
///
/// Drivers may add more fields at the end of standard schemas to reflect
-/// vendor-specific metadata. Applications must access these using an offset
-/// from the end of the schema and cannot assume that the index of the field
-/// will remain stable. Drivers must add the fields at the end and must
-/// prefix field names with the vendor/driver name to differentiate them
-/// (e.g. 'POSTGRESQL:owner', not just 'owner').
+/// vendor-specific metadata. Applications must access these by name or using
+/// an offset from the end of the schema and cannot assume that the index of
+/// the field will remain stable. Hence, it is discouraged to access these
+/// fields by ordinal as this is brittle. Drivers must add the fields at the
+/// end and must prefix field names with the vendor/driver name to
+/// differentiate them (e.g. 'POSTGRESQL:owner', not just 'owner').
///
/// Similarly, future standard revisions may add more fields to existing
/// standard schemas. Applications must not assume the number of fields is
@@ -1266,18 +1270,6 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_FILTER_ROUTINE_TYPES "adbc.metadata.filter.routine_types"
-/// \brief Only show namespaces in the given multi-part namespace.
-///
-/// Separator: ASCII unit separator (0x1F).
-/// The type is char*.
-#define ADBC_METADATA_FILTER_NAMESPACE "adbc.metadata.filter.namespace"
-
-/// \brief Only show namespaces with the given name. This filter only applies
-/// to the last namespace component.
-///
-/// The type is char*.
-#define ADBC_METADATA_FILTER_NAMESPACE_NAME "adbc.metadata.filter.namespace_name"
-
/// \brief Get or set a pagination token.
///
/// Some drivers may support this to allow fetching a large metadata
@@ -1675,25 +1667,6 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// - ADBC_METADATA_FILTER_PATTERN_COLUMN
#define ADBC_METADATA_COLLECTION_ROUTINE_COLUMNS "routine_columns"
-/// \brief The "namespaces" collection returns a level of namespaces defined
-/// in the database.
-///
-/// This collection generally results in an "N+1" query pattern. This is
-/// intended for systems that do not follow the SQL catalog-schema-table
-/// hierarchy; for systems that do, collections like "catalogs", "schemas",
-/// and "tables" will be more efficient as they can return multiple levels at
-/// once.
-///
-/// | Field Name | Field Type | Comments |
-/// |--------------------------|------------------------------|----------|
-/// | namespace_parent | list not null | |
-/// | namespace_name | utf8 not null | |
-///
-/// Supported filters:
-/// - ADBC_METADATA_FILTER_NAMESPACE
-/// - ADBC_METADATA_FILTER_NAMESPACE_NAME
-#define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces"
-
/// @}
/// @}
From 076a2a56d6a4cdc7542753c00b2b060c2b1a157d Mon Sep 17 00:00:00 2001
From: David Li
Date: Mon, 7 Sep 2026 13:30:36 +0900
Subject: [PATCH 3/6] comments
---
c/include/arrow-adbc/adbc.h | 62 +++++++++++++++++++++----------------
1 file changed, 36 insertions(+), 26 deletions(-)
diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
index 9e1c2bba4d6..37a4eee9eab 100644
--- a/c/include/arrow-adbc/adbc.h
+++ b/c/include/arrow-adbc/adbc.h
@@ -35,7 +35,7 @@
/// but not concurrent access. Specific implementations may permit
/// multiple threads.
///
-/// \version 1.1.0
+/// \version 1.2.0
#pragma once
@@ -1138,8 +1138,9 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// Drivers may not necessarily accept filter options or other options before
/// the collection name option is set.
///
-/// This is intended to replace AdbcConnectionGetObjects, but both APIs will
-/// be supported for the time being. AdbcConnectionGetObjects may be
+/// This is intended to replace AdbcConnectionGetObjects, but both APIs
+/// will be supported for the time being. A driver that implements either
+/// API should implement both APIs. AdbcConnectionGetObjects may be
/// deprecated in a future revision.
///
/// \since ADBC API revision 1.2.0
@@ -1177,7 +1178,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// option wins.
///
/// The type is char*.
-#define ADBC_METADATA_FILTER_PATERN_DB_SCHEMA "adbc.metadata.filter_pattern.schema"
+#define ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA "adbc.metadata.filter_pattern.schema"
/// \brief Filter the collection on the literal table name.
///
@@ -1218,7 +1219,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_FILTER_FOREIGN_CATALOG "adbc.metadata.filter.foreign_catalog"
-/// \brief Filter the collection on the literal catalog name of the foreign
+/// \brief Filter the collection on the literal schema name of the foreign
/// key.
///
/// The type is char*.
@@ -1281,17 +1282,26 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
///
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
-/// | collection_name | utf8 not null | |
-/// | collection_description | utf8 | |
+/// | collection_name | utf8 not null | (1) |
+/// | collection_description | utf8 | (2) |
/// | collection_schema | extension | |
/// | collection_filters | list | |
///
+/// (1) The name used to retrieve the collection.
+/// (2) A description of the collection's contents. Not required for
+/// collections defined in this header.
+///
/// FILTER_SCHEMA is a Struct with fields:
///
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
-/// | filter_description | utf8 | |
+/// | filter_name | utf8 not null | (1) |
+/// | filter_type | int8 not null | (2) |
/// | required | bool not null | |
+/// | filter_documentation | utf8 | |
+///
+/// (1) The option key used to set the filter.
+/// (2) A bitfield of ADBC_OPTION_TYPE values.
#define ADBC_METADATA_COLLECTION_META "meta"
/// \brief The "catalogs" collection returns the catalogs defined in the
@@ -1442,7 +1452,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// 5. How the foreign key constraint should be matched. The value is one of
/// the ADBC_CONSTRAINT_MATCH_ constants.
///
-/// Filters:
+/// Supported filters:
/// - ADBC_METADATA_FILTER_CATALOG (applies to fk_catalog_name)
/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to fk_schema_name)
/// - ADBC_METADATA_FILTER_TABLE (required; applies to fk_table_name)
@@ -1481,13 +1491,10 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// 5. How the foreign key constraint should be matched. The value is one of
/// the ADBC_CONSTRAINT_MATCH_ constants.
///
-/// Filters:
+/// Supported filters:
/// - ADBC_METADATA_FILTER_CATALOG (applies to pk_catalog_name)
/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to pk_schema_name)
/// - ADBC_METADATA_FILTER_TABLE (required; applies to pk_table_name)
-/// - ADBC_METADATA_FILTER_FOREIGN_CATALOG (applies to fk_catalog_name)
-/// - ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA (applies to fk_schema_name)
-/// - ADBC_METADATA_FILTER_FOREIGN_TABLE (required; applies to fk_table_name)
#define ADBC_METADATA_COLLECTION_EXPORTED_KEYS "exported_keys"
/// \brief The "cross_reference" collection, given a "parent" table and a
@@ -1524,13 +1531,13 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// 5. How the foreign key constraint should be matched. The value is one of
/// the ADBC_CONSTRAINT_MATCH_ constants.
///
-/// Filters:
-/// 1. The catalog of the parent table; required but may be NULL.
-/// 2. The schema of the parent table; required but may be NULL.
-/// 3. The name of the parent table; required.
-/// 4. The catalog of the foreign table; required but may be NULL.
-/// 5. The schema of the foreign table; required but may be NULL.
-/// 6. The name of the foreign table; required.
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG (applies to pk_catalog_name)
+/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to pk_schema_name)
+/// - ADBC_METADATA_FILTER_TABLE (required; applies to pk_table_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_CATALOG (applies to fk_catalog_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA (applies to fk_schema_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_TABLE (required; applies to fk_table_name)
#define ADBC_METADATA_COLLECTION_CROSS_REFERENCE "cross_reference"
/// \brief The "constraints" collection describes constraints on the selected
@@ -2753,6 +2760,9 @@ AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection,
///
/// This AdbcConnection must outlive the returned ArrowArrayStream.
///
+/// This API may be deprecated in a future revision in favor of
+/// ADBC_METADATA_COLLECTION.
+///
/// \param[in] connection The database connection.
/// \param[in] depth The level of nesting to display. If 0, display
/// all levels. If 1, display only catalogs (i.e. catalog_schemas
@@ -3235,7 +3245,7 @@ AdbcStatusCode AdbcStatementExecuteSchema(struct AdbcStatement* statement,
struct ArrowSchema* schema,
struct AdbcError* error);
-/// \brief Request the schema of the next statement execution
+/// \brief Request the schema of the next statement execution.
///
/// Allows the caller to request a specific schema based on prior
/// information or user input. This may be used to ensure a
@@ -3243,16 +3253,16 @@ AdbcStatusCode AdbcStatementExecuteSchema(struct AdbcStatement* statement,
/// with row-based types (e.g., SQLite) or a database whose types
/// are implemented with row-based parameters where Arrow prefers
/// type-level parameters (e.g., NUMERIC for PostgreSQL). The
-/// schema request is intended to modify only the types or
-/// widen the nullability of types in the original schema;
-/// column reordering or changing the number of returned columns
-/// is not a goal of this feature.
+/// schema request is intended to modify only the types or widen
+/// the nullability of types in the original schema; column
+/// reordering or changing the number of returned columns of a
+/// result set in a query is not a goal of this feature.
///
/// The provided schema is a request and not a guarantee (i.e.,
/// callers must use the schema provided by the output stream to
/// interpret the result).
///
-/// Calling AdbcStatementRequestSchema() must not affect the result
+/// Calling AdbcStatementRequestSchema must not affect the result
/// of AdbcStatementExecuteSchema (which always infers its result
/// from the input query).
///
From a15d0367d9f42149d61be5ce74576aae94bc45dd Mon Sep 17 00:00:00 2001
From: David Li
Date: Mon, 7 Sep 2026 14:21:01 +0900
Subject: [PATCH 4/6] clarify schema/catalog behavior
---
c/include/arrow-adbc/adbc.h | 13 +++++++------
1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
index 37a4eee9eab..16470618641 100644
--- a/c/include/arrow-adbc/adbc.h
+++ b/c/include/arrow-adbc/adbc.h
@@ -1307,8 +1307,8 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \brief The "catalogs" collection returns the catalogs defined in the
/// database.
///
-/// Some systems may not have the concept of catalogs, in which case this
-/// collection should contain a single entry with an empty, non-null name.
+/// Some systems may not have the concept of catalogs, in which case it is
+/// recommended that this collection should contain no rows.
///
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
@@ -1325,14 +1325,15 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \brief The "schemas" collection returns the schemas defined in the
/// database.
///
-/// Some systems may not have the concept of schemas, in which case this
-/// collection should contain a single entry per catalog with an empty,
-/// non-null name.
+/// Some systems may not have the concept of catalogs or schemas. If
+/// catalogs are not supported, it is recommended to set catalog_name to
+/// NULL. If schemas are not supported, it is recommended that this
+/// collection should contain no rows.
///
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
/// | catalog_name | utf8 | |
-/// | db_schema_name | utf8 | |
+/// | db_schema_name | utf8 not null | |
/// | db_schema_remarks | utf8 | (1) |
///
/// (1) A description of the schema.
From dd686572546bb48703f200c7eb125440c2f95739 Mon Sep 17 00:00:00 2001
From: David Li
Date: Fri, 6 Nov 2026 11:48:16 +0900
Subject: [PATCH 5/6] tweak wording
---
c/include/arrow-adbc/adbc.h | 30 ++++++++++++++++++------------
1 file changed, 18 insertions(+), 12 deletions(-)
diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
index 16470618641..3eb8b043d81 100644
--- a/c/include/arrow-adbc/adbc.h
+++ b/c/include/arrow-adbc/adbc.h
@@ -1152,7 +1152,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_COLLECTION "adbc.metadata.collection"
-/// \brief Filter the collection on the literal catalog name.
+/// \brief Filter the collection on the exact catalog name.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_CATALOG "adbc.metadata.filter.catalog"
@@ -1166,7 +1166,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_FILTER_PATTERN_CATALOG "adbc.metadata.filter_pattern.catalog"
-/// \brief Filter the collection on the literal schema name.
+/// \brief Filter the collection on the exact schema name.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.schema"
@@ -1180,7 +1180,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA "adbc.metadata.filter_pattern.schema"
-/// \brief Filter the collection on the literal table name.
+/// \brief Filter the collection on the exact table name.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_TABLE "adbc.metadata.filter.table"
@@ -1193,7 +1193,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_FILTER_PATTERN_TABLE "adbc.metadata.filter_pattern.table"
-/// \brief Filter the collection on the literal column name.
+/// \brief Filter the collection on the exact column name.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_COLUMN "adbc.metadata.filter.column"
@@ -1213,25 +1213,25 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_FILTER_TABLE_TYPES "adbc.metadata.filter.table_types"
-/// \brief Filter the collection on the literal catalog name of the foreign
+/// \brief Filter the collection on the exact catalog name of the foreign
/// key.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_FOREIGN_CATALOG "adbc.metadata.filter.foreign_catalog"
-/// \brief Filter the collection on the literal schema name of the foreign
+/// \brief Filter the collection on the exact schema name of the foreign
/// key.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA "adbc.metadata.filter.foreign_schema"
-/// \brief Filter the collection on the literal catalog name of the foreign
+/// \brief Filter the collection on the exact catalog name of the foreign
/// key.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_FOREIGN_TABLE "adbc.metadata.filter.foreign_table"
-/// \brief Filter the collection on the literal constraint name.
+/// \brief Filter the collection on the exact constraint name.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_CONSTRAINT "adbc.metadata.filter.constraint"
@@ -1251,7 +1251,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// The type is char*.
#define ADBC_METADATA_FILTER_CONSTRAINT_TYPES "adbc.metadata.filter.constraint_types"
-/// \brief Filter the collection on the literal routine name.
+/// \brief Filter the collection on the exact routine name.
///
/// The type is char*.
#define ADBC_METADATA_FILTER_ROUTINE "adbc.metadata.filter.routine"
@@ -1283,7 +1283,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
/// | collection_name | utf8 not null | (1) |
-/// | collection_description | utf8 | (2) |
+/// | collection_remarks | utf8 | (2) |
/// | collection_schema | extension | |
/// | collection_filters | list | |
///
@@ -1297,11 +1297,17 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// |--------------------------|------------------------------|----------|
/// | filter_name | utf8 not null | (1) |
/// | filter_type | int8 not null | (2) |
-/// | required | bool not null | |
-/// | filter_documentation | utf8 | |
+/// | filter_required | bool not null | |
+/// | filter_remarks | utf8 | (3) |
///
/// (1) The option key used to set the filter.
/// (2) A bitfield of ADBC_OPTION_TYPE values.
+/// (3) Documentation for the filter.
+///
+/// Filters that support both exact and pattern matches should be listed
+/// twice (as they are different options), but it is suggested to omit
+/// the documentation on the pattern match (unless there are pattern-
+/// specific notes).
#define ADBC_METADATA_COLLECTION_META "meta"
/// \brief The "catalogs" collection returns the catalogs defined in the
From eb8161938ac6ec7cb837fccc0e1d4abc6a36001d Mon Sep 17 00:00:00 2001
From: David Li
Date: Mon, 16 Nov 2026 11:08:58 +0900
Subject: [PATCH 6/6] sync
---
c/include/arrow-adbc/adbc.h | 189 +++++++++---------
go/adbc/drivermgr/arrow-adbc/adbc.h | 289 ++++++++++++++--------------
2 files changed, 247 insertions(+), 231 deletions(-)
diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
index 3eb8b043d81..c63f96bf153 100644
--- a/c/include/arrow-adbc/adbc.h
+++ b/c/include/arrow-adbc/adbc.h
@@ -1095,17 +1095,56 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \defgroup adbc-statement-metadata-collection Metadata Collections
///
-/// Fetch (catalog) metadata from the database. On a statement, set
+/// Fetch (catalog) metadata from the database, without needing to know
+/// vendor-specific special tables. On a statement, set
/// ADBC_METADATA_COLLECTION to one of the collection names below, and set any
/// filters via the options defined below. (There are driver/vendor-specific
-/// collections and filters as well.) Then call AdbcStatementExecuteQuery or
-/// AdbcStatementExecuteSchema. The result is an Arrow dataset with a schema
-/// defined by the collection. For example, a client may request a list of
-/// tables in the database, or a list of supported data types.
-///
-/// All drivers must implement a collection called "meta" (which is aliased to
-/// NULL and blank string) that defines the available collections. See
-/// ADBC_METADATA_COLLECTION_META.
+/// collections and filters as well.) Then call:
+///
+/// - AdbcStatementExecuteQuery to fetch the metadata as an Arrow dataset.
+/// - AdbcStatementExecuteSchema to get the schema of the metadata collection
+/// without fetching.
+/// - AdbcStatementBind/AdbcStatementBindStream to set filters; see below for
+/// details.
+/// - AdbcStatementGetParameterSchema to get supported filters (if any); see
+/// below for details.
+/// - AdbcStatementExecutePartitions to fetch the metadata, potentially in a
+/// way that supports incremental/parallel fetching. Drivers that do not
+/// support this should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// For AdbcStatementExecuteQuery and AdbcStatementExecutePartitions, the
+/// result is an Arrow dataset with a schema defined by the collection. For
+/// example, a client may request a list of tables in the database, or a list
+/// of supported data types.
+///
+/// Clients may supply filters for the metadata collection by supplying bind
+/// parameters as if this were a regular query. Each field is a separate
+/// filter; all filters are ANDed together. If multiple rows of filters are
+/// bound, the driver returns the union of the results. Filters may be defined
+/// to support both exact and pattern matching (see "search pattern" in \ref
+/// adbc-connection-metadata); these are defined as separate filters, but it
+/// is an error to provide both for the same field in the same row.
+///
+/// The definition of filters may be inspected at runtime via
+/// AdbcStatementGetParameterSchema. Each field of the schema is a filter;
+/// nullable fields mean the filter can be omitted (and does not need to be
+/// bound; the field may be omitted from the bind schema), while not null
+/// fields mean the filter is required. The field name is the filter name, and
+/// if bound, the bind schema must use the same exact name. The field type is
+/// the filter type. Drivers may provide documentation in field metadata under
+/// the key `ADBC:metadata:filter:remarks`. Filters that support both exact
+/// and pattern matches should be listed twice by the driver (as they are
+/// different options), but it is suggested to omit the documentation on the
+/// pattern match (unless there are pattern- specific notes).
+///
+/// Filters should be either utf8, int64, float64, or binary, a list of one of
+/// the previous types, or a union of one or more of the previous types to
+/// indicate that more than one type is acceptable. When binding, the union
+/// type is not required (for example, it is acceptable to just provide a
+/// `string` filter for `union[string, int]`).
+///
+/// Drivers must implement a collection called "meta" that defines the
+/// available collections. See ADBC_METADATA_COLLECTION_META.
///
/// Drivers may also implement AdbcStatementRequestSchema to (1) request
/// different data types and (2) drop fields from the result. Drivers are not
@@ -1113,11 +1152,11 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// like reordering collection fields. Drivers are encouraged to use this to
/// give applications flexibility over output type and shape (e.g. reducing
/// memory pressure by run-end-encoding or dictionary-encoding primary key
-/// columns; optimizing queries by using simpler queries and eliminating joins
-/// if the application drops certain columns). Unless requested, however,
-/// drivers should return the type specified below and not substitute a
-/// logically equivalent type (e.g. utf8 below should be a string array by
-/// default, and not a utf8view or large string or other array).
+/// columns; using simpler queries and eliminating joins if the application
+/// drops certain columns). Unless requested, however, drivers should return
+/// the type specified below and not substitute a logically equivalent type
+/// (e.g. utf8 below should be a string array by default, and not a utf8view
+/// or large string or other type).
///
/// Drivers may add more fields at the end of standard schemas to reflect
/// vendor-specific metadata. Applications must access these by name or using
@@ -1138,10 +1177,10 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// Drivers may not necessarily accept filter options or other options before
/// the collection name option is set.
///
-/// This is intended to replace AdbcConnectionGetObjects, but both APIs
-/// will be supported for the time being. A driver that implements either
-/// API should implement both APIs. AdbcConnectionGetObjects may be
-/// deprecated in a future revision.
+/// This is intended to replace AdbcConnectionGetObjects and
+/// AdbcConnectionGetTableTypes, but both APIs will be supported for the time
+/// being. A driver that implements either API should implement both APIs.
+/// AdbcConnectionGetObjects may be deprecated in a future revision.
///
/// \since ADBC API revision 1.2.0
///
@@ -1149,12 +1188,14 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \brief Prepare to fetch a metadata collection.
///
-/// The type is char*.
+/// If not recognized, the driver returns ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The type is utf8.
#define ADBC_METADATA_COLLECTION "adbc.metadata.collection"
/// \brief Filter the collection on the exact catalog name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_CATALOG "adbc.metadata.filter.catalog"
/// \brief Filter the collection on the catalog name, matching a search
@@ -1163,112 +1204,94 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// If both this and ADBC_METADATA_FILTER_CATALOG are set, then the last set
/// option wins.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_CATALOG "adbc.metadata.filter_pattern.catalog"
/// \brief Filter the collection on the exact schema name.
///
-/// The type is char*.
-#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.schema"
+/// The type is utf8.
+#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.db_schema"
/// \brief Filter the collection on the schema name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_DB_SCHEMA are set, then the last set
-/// option wins.
-///
-/// The type is char*.
-#define ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA "adbc.metadata.filter_pattern.schema"
+/// The type is utf8.
+#define ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA "adbc.metadata.filter_pattern.db_schema"
/// \brief Filter the collection on the exact table name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_TABLE "adbc.metadata.filter.table"
/// \brief Filter the collection on the table name, matching a search pattern.
///
-/// If both this and ADBC_METADATA_FILTER_TABLE are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_TABLE "adbc.metadata.filter_pattern.table"
/// \brief Filter the collection on the exact column name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_COLUMN "adbc.metadata.filter.column"
/// \brief Filter the collection on the column name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_COLUMN are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_COLUMN "adbc.metadata.filter_pattern.column"
/// \brief Filter the collection on the table types.
///
-/// Separator: comma (',').
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_TABLE_TYPES "adbc.metadata.filter.table_types"
/// \brief Filter the collection on the exact catalog name of the foreign
-/// key.
+/// key-referencing table.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_FOREIGN_CATALOG "adbc.metadata.filter.foreign_catalog"
/// \brief Filter the collection on the exact schema name of the foreign
-/// key.
+/// key-referencing table.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA "adbc.metadata.filter.foreign_schema"
-/// \brief Filter the collection on the exact catalog name of the foreign
-/// key.
+/// \brief Filter the collection on the exact table name of the foreign
+/// key-referencing table.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_FOREIGN_TABLE "adbc.metadata.filter.foreign_table"
/// \brief Filter the collection on the exact constraint name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_CONSTRAINT "adbc.metadata.filter.constraint"
/// \brief Filter the collection on the constraint name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_CONSTRAINT are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_CONSTRAINT "adbc.metadata.filter_pattern.constraint"
/// \brief Filter the collection on the constraint types.
///
-/// Separator: comma (',').
-/// The type is char*.
+/// The type is list[utf8].
#define ADBC_METADATA_FILTER_CONSTRAINT_TYPES "adbc.metadata.filter.constraint_types"
/// \brief Filter the collection on the exact routine name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_ROUTINE "adbc.metadata.filter.routine"
/// \brief Filter the collection on the routine name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_ROUTINE are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_ROUTINE "adbc.metadata.filter_pattern.routine"
/// \brief Filter the collection on the routine types.
///
-/// Separator: comma (',').
-/// The type is char*.
+/// The type is list[utf8].
#define ADBC_METADATA_FILTER_ROUTINE_TYPES "adbc.metadata.filter.routine_types"
/// \brief Get or set a pagination token.
@@ -1276,6 +1299,8 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// Some drivers may support this to allow fetching a large metadata
/// collection in multiple calls. If the pagination token could not be used,
/// the driver should return an error.
+///
+/// The type is utf8.
#define ADBC_METADATA_OPTION_PAGINATION_TOKEN "adbc.metadata.pagination_token"
/// \brief The "meta" collection returns the available metadata collections.
@@ -1284,30 +1309,10 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// |--------------------------|------------------------------|----------|
/// | collection_name | utf8 not null | (1) |
/// | collection_remarks | utf8 | (2) |
-/// | collection_schema | extension | |
-/// | collection_filters | list | |
///
/// (1) The name used to retrieve the collection.
/// (2) A description of the collection's contents. Not required for
/// collections defined in this header.
-///
-/// FILTER_SCHEMA is a Struct with fields:
-///
-/// | Field Name | Field Type | Comments |
-/// |--------------------------|------------------------------|----------|
-/// | filter_name | utf8 not null | (1) |
-/// | filter_type | int8 not null | (2) |
-/// | filter_required | bool not null | |
-/// | filter_remarks | utf8 | (3) |
-///
-/// (1) The option key used to set the filter.
-/// (2) A bitfield of ADBC_OPTION_TYPE values.
-/// (3) Documentation for the filter.
-///
-/// Filters that support both exact and pattern matches should be listed
-/// twice (as they are different options), but it is suggested to omit
-/// the documentation on the pattern match (unless there are pattern-
-/// specific notes).
#define ADBC_METADATA_COLLECTION_META "meta"
/// \brief The "catalogs" collection returns the catalogs defined in the
@@ -1351,6 +1356,14 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
#define ADBC_METADATA_COLLECTION_SCHEMAS "schemas"
+/// \brief The "catalogs" collection returns the table types defined in the
+/// database.
+///
+/// | Field Name | Field Type |
+/// |--------------------------|------------------------------|
+/// | table_type | utf8 not null |
+#define ADBC_METADATA_COLLECTION_TABLE_TYPES "table_types"
+
/// \brief The "tables" collection returns the tables defined in the
/// database.
///
@@ -1389,7 +1402,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | table_name | utf8 not null | |
/// | column_name | utf8 not null | |
/// | ordinal_position | int32 | (1) |
-/// | remarks | utf8 | (2) |
+/// | column_remarks | utf8 | (2) |
/// | xdbc_data_type | int16 | (3) |
/// | xdbc_type_name | utf8 | (3) |
/// | xdbc_column_size | int32 | (3) |
@@ -1406,7 +1419,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | xdbc_scope_table | utf8 | (3) |
/// | xdbc_is_autoincrement | bool | (3) |
/// | xdbc_is_generatedcolumn | bool | (3) |
-/// | xdbc_source_data_type | bool | (3) |
+/// | xdbc_source_data_type | int16 | (3) |
///
/// 1. The column's ordinal position in the table (starting from 1).
/// 2. Database-specific description of the column.
@@ -1443,7 +1456,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | fk_name | utf8 | |
/// | key_seq | int16 | (1) |
/// | constraint_update_rule | int16 | (2) |
-/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_delete_rule | int16 | (2) |
/// | constraint_enforced | bool | (3) |
/// | constraint_deferrability | int16 | (4) |
/// | constraint_match_type | int16 | (5) |
@@ -1482,7 +1495,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | fk_name | utf8 | |
/// | key_seq | int16 | (1) |
/// | constraint_update_rule | int16 | (2) |
-/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_delete_rule | int16 | (2) |
/// | constraint_enforced | bool | (3) |
/// | constraint_deferrability | int16 | (4) |
/// | constraint_match_type | int16 | (5) |
@@ -1522,7 +1535,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | fk_name | utf8 | |
/// | key_seq | int16 | (1) |
/// | constraint_update_rule | int16 | (2) |
-/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_delete_rule | int16 | (2) |
/// | constraint_enforced | bool | (3) |
/// | constraint_deferrability | int16 | (4) |
/// | constraint_match_type | int16 | (5) |
@@ -1625,8 +1638,6 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
/// - ADBC_METADATA_FILTER_DB_SCHEMA
/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
-/// - ADBC_METADATA_FILTER_TABLE
-/// - ADBC_METADATA_FILTER_PATTERN_TABLE
/// - ADBC_METADATA_FILTER_ROUTINE
/// - ADBC_METADATA_FILTER_PATTERN_ROUTINE
/// - ADBC_METADATA_FILTER_ROUTINE_TYPES
@@ -1756,6 +1767,8 @@ struct ADBC_EXPORT AdbcConnection {
/// 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.
+///
+/// The statement state machine is as follows:
struct ADBC_EXPORT AdbcStatement {
/// \brief Opaque implementation-defined state.
/// This field is NULLPTR iff the connection is uninitialized/freed.
diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h b/go/adbc/drivermgr/arrow-adbc/adbc.h
index 70cca524f02..c63f96bf153 100644
--- a/go/adbc/drivermgr/arrow-adbc/adbc.h
+++ b/go/adbc/drivermgr/arrow-adbc/adbc.h
@@ -35,7 +35,7 @@
/// but not concurrent access. Specific implementations may permit
/// multiple threads.
///
-/// \version 1.1.0
+/// \version 1.2.0
#pragma once
@@ -1095,17 +1095,56 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \defgroup adbc-statement-metadata-collection Metadata Collections
///
-/// Fetch (catalog) metadata from the database. On a statement, set
+/// Fetch (catalog) metadata from the database, without needing to know
+/// vendor-specific special tables. On a statement, set
/// ADBC_METADATA_COLLECTION to one of the collection names below, and set any
/// filters via the options defined below. (There are driver/vendor-specific
-/// collections and filters as well.) Then call AdbcStatementExecuteQuery or
-/// AdbcStatementExecuteSchema. The result is an Arrow dataset with a schema
-/// defined by the collection. For example, a client may request a list of
-/// tables in the database, or a list of supported data types.
-///
-/// All drivers must implement a collection called "meta" (which is aliased to
-/// NULL and blank string) that defines the available collections. See
-/// ADBC_METADATA_COLLECTION_META.
+/// collections and filters as well.) Then call:
+///
+/// - AdbcStatementExecuteQuery to fetch the metadata as an Arrow dataset.
+/// - AdbcStatementExecuteSchema to get the schema of the metadata collection
+/// without fetching.
+/// - AdbcStatementBind/AdbcStatementBindStream to set filters; see below for
+/// details.
+/// - AdbcStatementGetParameterSchema to get supported filters (if any); see
+/// below for details.
+/// - AdbcStatementExecutePartitions to fetch the metadata, potentially in a
+/// way that supports incremental/parallel fetching. Drivers that do not
+/// support this should return ADBC_STATUS_NOT_IMPLEMENTED.
+///
+/// For AdbcStatementExecuteQuery and AdbcStatementExecutePartitions, the
+/// result is an Arrow dataset with a schema defined by the collection. For
+/// example, a client may request a list of tables in the database, or a list
+/// of supported data types.
+///
+/// Clients may supply filters for the metadata collection by supplying bind
+/// parameters as if this were a regular query. Each field is a separate
+/// filter; all filters are ANDed together. If multiple rows of filters are
+/// bound, the driver returns the union of the results. Filters may be defined
+/// to support both exact and pattern matching (see "search pattern" in \ref
+/// adbc-connection-metadata); these are defined as separate filters, but it
+/// is an error to provide both for the same field in the same row.
+///
+/// The definition of filters may be inspected at runtime via
+/// AdbcStatementGetParameterSchema. Each field of the schema is a filter;
+/// nullable fields mean the filter can be omitted (and does not need to be
+/// bound; the field may be omitted from the bind schema), while not null
+/// fields mean the filter is required. The field name is the filter name, and
+/// if bound, the bind schema must use the same exact name. The field type is
+/// the filter type. Drivers may provide documentation in field metadata under
+/// the key `ADBC:metadata:filter:remarks`. Filters that support both exact
+/// and pattern matches should be listed twice by the driver (as they are
+/// different options), but it is suggested to omit the documentation on the
+/// pattern match (unless there are pattern- specific notes).
+///
+/// Filters should be either utf8, int64, float64, or binary, a list of one of
+/// the previous types, or a union of one or more of the previous types to
+/// indicate that more than one type is acceptable. When binding, the union
+/// type is not required (for example, it is acceptable to just provide a
+/// `string` filter for `union[string, int]`).
+///
+/// Drivers must implement a collection called "meta" that defines the
+/// available collections. See ADBC_METADATA_COLLECTION_META.
///
/// Drivers may also implement AdbcStatementRequestSchema to (1) request
/// different data types and (2) drop fields from the result. Drivers are not
@@ -1113,15 +1152,19 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// like reordering collection fields. Drivers are encouraged to use this to
/// give applications flexibility over output type and shape (e.g. reducing
/// memory pressure by run-end-encoding or dictionary-encoding primary key
-/// columns; optimizing queries by using simpler queries and eliminating joins
-/// if the application drops certain columns).
+/// columns; using simpler queries and eliminating joins if the application
+/// drops certain columns). Unless requested, however, drivers should return
+/// the type specified below and not substitute a logically equivalent type
+/// (e.g. utf8 below should be a string array by default, and not a utf8view
+/// or large string or other type).
///
/// Drivers may add more fields at the end of standard schemas to reflect
-/// vendor-specific metadata. Applications must access these using an offset
-/// from the end of the schema and cannot assume that the index of the field
-/// will remain stable. Drivers must add the fields at the end and must
-/// prefix field names with the vendor/driver name to differentiate them
-/// (e.g. 'POSTGRESQL:owner', not just 'owner').
+/// vendor-specific metadata. Applications must access these by name or using
+/// an offset from the end of the schema and cannot assume that the index of
+/// the field will remain stable. Hence, it is discouraged to access these
+/// fields by ordinal as this is brittle. Drivers must add the fields at the
+/// end and must prefix field names with the vendor/driver name to
+/// differentiate them (e.g. 'POSTGRESQL:owner', not just 'owner').
///
/// Similarly, future standard revisions may add more fields to existing
/// standard schemas. Applications must not assume the number of fields is
@@ -1134,9 +1177,10 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// Drivers may not necessarily accept filter options or other options before
/// the collection name option is set.
///
-/// This is intended to replace AdbcConnectionGetObjects, but both APIs will
-/// be supported for the time being. AdbcConnectionGetObjects may be
-/// deprecated in a future revision.
+/// This is intended to replace AdbcConnectionGetObjects and
+/// AdbcConnectionGetTableTypes, but both APIs will be supported for the time
+/// being. A driver that implements either API should implement both APIs.
+/// AdbcConnectionGetObjects may be deprecated in a future revision.
///
/// \since ADBC API revision 1.2.0
///
@@ -1144,12 +1188,14 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \brief Prepare to fetch a metadata collection.
///
-/// The type is char*.
+/// If not recognized, the driver returns ADBC_STATUS_INVALID_ARGUMENT.
+///
+/// The type is utf8.
#define ADBC_METADATA_COLLECTION "adbc.metadata.collection"
-/// \brief Filter the collection on the literal catalog name.
+/// \brief Filter the collection on the exact catalog name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_CATALOG "adbc.metadata.filter.catalog"
/// \brief Filter the collection on the catalog name, matching a search
@@ -1158,155 +1204,122 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// If both this and ADBC_METADATA_FILTER_CATALOG are set, then the last set
/// option wins.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_CATALOG "adbc.metadata.filter_pattern.catalog"
-/// \brief Filter the collection on the literal schema name.
+/// \brief Filter the collection on the exact schema name.
///
-/// The type is char*.
-#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.schema"
+/// The type is utf8.
+#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.db_schema"
/// \brief Filter the collection on the schema name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_DB_SCHEMA are set, then the last set
-/// option wins.
-///
-/// The type is char*.
-#define ADBC_METADATA_FILTER_PATERN_DB_SCHEMA "adbc.metadata.filter_pattern.schema"
+/// The type is utf8.
+#define ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA "adbc.metadata.filter_pattern.db_schema"
-/// \brief Filter the collection on the literal table name.
+/// \brief Filter the collection on the exact table name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_TABLE "adbc.metadata.filter.table"
/// \brief Filter the collection on the table name, matching a search pattern.
///
-/// If both this and ADBC_METADATA_FILTER_TABLE are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_TABLE "adbc.metadata.filter_pattern.table"
-/// \brief Filter the collection on the literal column name.
+/// \brief Filter the collection on the exact column name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_COLUMN "adbc.metadata.filter.column"
/// \brief Filter the collection on the column name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_COLUMN are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_COLUMN "adbc.metadata.filter_pattern.column"
/// \brief Filter the collection on the table types.
///
-/// Separator: comma (',').
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_TABLE_TYPES "adbc.metadata.filter.table_types"
-/// \brief Filter the collection on the literal catalog name of the foreign
-/// key.
+/// \brief Filter the collection on the exact catalog name of the foreign
+/// key-referencing table.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_FOREIGN_CATALOG "adbc.metadata.filter.foreign_catalog"
-/// \brief Filter the collection on the literal catalog name of the foreign
-/// key.
+/// \brief Filter the collection on the exact schema name of the foreign
+/// key-referencing table.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA "adbc.metadata.filter.foreign_schema"
-/// \brief Filter the collection on the literal catalog name of the foreign
-/// key.
+/// \brief Filter the collection on the exact table name of the foreign
+/// key-referencing table.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_FOREIGN_TABLE "adbc.metadata.filter.foreign_table"
-/// \brief Filter the collection on the literal constraint name.
+/// \brief Filter the collection on the exact constraint name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_CONSTRAINT "adbc.metadata.filter.constraint"
/// \brief Filter the collection on the constraint name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_CONSTRAINT are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_CONSTRAINT "adbc.metadata.filter_pattern.constraint"
/// \brief Filter the collection on the constraint types.
///
-/// Separator: comma (',').
-/// The type is char*.
+/// The type is list[utf8].
#define ADBC_METADATA_FILTER_CONSTRAINT_TYPES "adbc.metadata.filter.constraint_types"
-/// \brief Filter the collection on the literal routine name.
+/// \brief Filter the collection on the exact routine name.
///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_ROUTINE "adbc.metadata.filter.routine"
/// \brief Filter the collection on the routine name, matching a search
/// pattern.
///
-/// If both this and ADBC_METADATA_FILTER_ROUTINE are set, then the last set
-/// option wins.
-///
-/// The type is char*.
+/// The type is utf8.
#define ADBC_METADATA_FILTER_PATTERN_ROUTINE "adbc.metadata.filter_pattern.routine"
/// \brief Filter the collection on the routine types.
///
-/// Separator: comma (',').
-/// The type is char*.
+/// The type is list[utf8].
#define ADBC_METADATA_FILTER_ROUTINE_TYPES "adbc.metadata.filter.routine_types"
-/// \brief Only show namespaces in the given multi-part namespace.
-///
-/// Separator: ASCII unit separator (0x1F).
-/// The type is char*.
-#define ADBC_METADATA_FILTER_NAMESPACE "adbc.metadata.filter.namespace"
-
-/// \brief Only show namespaces with the given name. This filter only applies
-/// to the last namespace component.
-///
-/// The type is char*.
-#define ADBC_METADATA_FILTER_NAMESPACE_NAME "adbc.metadata.filter.namespace_name"
-
/// \brief Get or set a pagination token.
///
/// Some drivers may support this to allow fetching a large metadata
/// collection in multiple calls. If the pagination token could not be used,
/// the driver should return an error.
+///
+/// The type is utf8.
#define ADBC_METADATA_OPTION_PAGINATION_TOKEN "adbc.metadata.pagination_token"
/// \brief The "meta" collection returns the available metadata collections.
///
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
-/// | collection_name | utf8 not null | |
-/// | collection_description | utf8 | |
-/// | collection_schema | extension | |
-/// | collection_filters | list | |
+/// | collection_name | utf8 not null | (1) |
+/// | collection_remarks | utf8 | (2) |
///
-/// FILTER_SCHEMA is a Struct with fields:
-///
-/// | Field Name | Field Type | Comments |
-/// |--------------------------|------------------------------|----------|
-/// | filter_description | utf8 | |
-/// | required | bool not null | |
+/// (1) The name used to retrieve the collection.
+/// (2) A description of the collection's contents. Not required for
+/// collections defined in this header.
#define ADBC_METADATA_COLLECTION_META "meta"
/// \brief The "catalogs" collection returns the catalogs defined in the
/// database.
///
-/// Some systems may not have the concept of catalogs, in which case this
-/// collection should contain a single entry with an empty, non-null name.
+/// Some systems may not have the concept of catalogs, in which case it is
+/// recommended that this collection should contain no rows.
///
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
@@ -1323,14 +1336,15 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// \brief The "schemas" collection returns the schemas defined in the
/// database.
///
-/// Some systems may not have the concept of schemas, in which case this
-/// collection should contain a single entry per catalog with an empty,
-/// non-null name.
+/// Some systems may not have the concept of catalogs or schemas. If
+/// catalogs are not supported, it is recommended to set catalog_name to
+/// NULL. If schemas are not supported, it is recommended that this
+/// collection should contain no rows.
///
/// | Field Name | Field Type | Comments |
/// |--------------------------|------------------------------|----------|
/// | catalog_name | utf8 | |
-/// | db_schema_name | utf8 | |
+/// | db_schema_name | utf8 not null | |
/// | db_schema_remarks | utf8 | (1) |
///
/// (1) A description of the schema.
@@ -1342,6 +1356,14 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
#define ADBC_METADATA_COLLECTION_SCHEMAS "schemas"
+/// \brief The "catalogs" collection returns the table types defined in the
+/// database.
+///
+/// | Field Name | Field Type |
+/// |--------------------------|------------------------------|
+/// | table_type | utf8 not null |
+#define ADBC_METADATA_COLLECTION_TABLE_TYPES "table_types"
+
/// \brief The "tables" collection returns the tables defined in the
/// database.
///
@@ -1380,7 +1402,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | table_name | utf8 not null | |
/// | column_name | utf8 not null | |
/// | ordinal_position | int32 | (1) |
-/// | remarks | utf8 | (2) |
+/// | column_remarks | utf8 | (2) |
/// | xdbc_data_type | int16 | (3) |
/// | xdbc_type_name | utf8 | (3) |
/// | xdbc_column_size | int32 | (3) |
@@ -1397,7 +1419,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | xdbc_scope_table | utf8 | (3) |
/// | xdbc_is_autoincrement | bool | (3) |
/// | xdbc_is_generatedcolumn | bool | (3) |
-/// | xdbc_source_data_type | bool | (3) |
+/// | xdbc_source_data_type | int16 | (3) |
///
/// 1. The column's ordinal position in the table (starting from 1).
/// 2. Database-specific description of the column.
@@ -1434,7 +1456,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | fk_name | utf8 | |
/// | key_seq | int16 | (1) |
/// | constraint_update_rule | int16 | (2) |
-/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_delete_rule | int16 | (2) |
/// | constraint_enforced | bool | (3) |
/// | constraint_deferrability | int16 | (4) |
/// | constraint_match_type | int16 | (5) |
@@ -1450,7 +1472,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// 5. How the foreign key constraint should be matched. The value is one of
/// the ADBC_CONSTRAINT_MATCH_ constants.
///
-/// Filters:
+/// Supported filters:
/// - ADBC_METADATA_FILTER_CATALOG (applies to fk_catalog_name)
/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to fk_schema_name)
/// - ADBC_METADATA_FILTER_TABLE (required; applies to fk_table_name)
@@ -1473,7 +1495,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | fk_name | utf8 | |
/// | key_seq | int16 | (1) |
/// | constraint_update_rule | int16 | (2) |
-/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_delete_rule | int16 | (2) |
/// | constraint_enforced | bool | (3) |
/// | constraint_deferrability | int16 | (4) |
/// | constraint_match_type | int16 | (5) |
@@ -1489,13 +1511,10 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// 5. How the foreign key constraint should be matched. The value is one of
/// the ADBC_CONSTRAINT_MATCH_ constants.
///
-/// Filters:
+/// Supported filters:
/// - ADBC_METADATA_FILTER_CATALOG (applies to pk_catalog_name)
/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to pk_schema_name)
/// - ADBC_METADATA_FILTER_TABLE (required; applies to pk_table_name)
-/// - ADBC_METADATA_FILTER_FOREIGN_CATALOG (applies to fk_catalog_name)
-/// - ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA (applies to fk_schema_name)
-/// - ADBC_METADATA_FILTER_FOREIGN_TABLE (required; applies to fk_table_name)
#define ADBC_METADATA_COLLECTION_EXPORTED_KEYS "exported_keys"
/// \brief The "cross_reference" collection, given a "parent" table and a
@@ -1516,7 +1535,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// | fk_name | utf8 | |
/// | key_seq | int16 | (1) |
/// | constraint_update_rule | int16 | (2) |
-/// | constraint_delete_rule | int16 | (3) |
+/// | constraint_delete_rule | int16 | (2) |
/// | constraint_enforced | bool | (3) |
/// | constraint_deferrability | int16 | (4) |
/// | constraint_match_type | int16 | (5) |
@@ -1532,13 +1551,13 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// 5. How the foreign key constraint should be matched. The value is one of
/// the ADBC_CONSTRAINT_MATCH_ constants.
///
-/// Filters:
-/// 1. The catalog of the parent table; required but may be NULL.
-/// 2. The schema of the parent table; required but may be NULL.
-/// 3. The name of the parent table; required.
-/// 4. The catalog of the foreign table; required but may be NULL.
-/// 5. The schema of the foreign table; required but may be NULL.
-/// 6. The name of the foreign table; required.
+/// Supported filters:
+/// - ADBC_METADATA_FILTER_CATALOG (applies to pk_catalog_name)
+/// - ADBC_METADATA_FILTER_DB_SCHEMA (applies to pk_schema_name)
+/// - ADBC_METADATA_FILTER_TABLE (required; applies to pk_table_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_CATALOG (applies to fk_catalog_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_DB_SCHEMA (applies to fk_schema_name)
+/// - ADBC_METADATA_FILTER_FOREIGN_TABLE (required; applies to fk_table_name)
#define ADBC_METADATA_COLLECTION_CROSS_REFERENCE "cross_reference"
/// \brief The "constraints" collection describes constraints on the selected
@@ -1619,8 +1638,6 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// - ADBC_METADATA_FILTER_PATTERN_CATALOG
/// - ADBC_METADATA_FILTER_DB_SCHEMA
/// - ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
-/// - ADBC_METADATA_FILTER_TABLE
-/// - ADBC_METADATA_FILTER_PATTERN_TABLE
/// - ADBC_METADATA_FILTER_ROUTINE
/// - ADBC_METADATA_FILTER_PATTERN_ROUTINE
/// - ADBC_METADATA_FILTER_ROUTINE_TYPES
@@ -1675,25 +1692,6 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream
/// - ADBC_METADATA_FILTER_PATTERN_COLUMN
#define ADBC_METADATA_COLLECTION_ROUTINE_COLUMNS "routine_columns"
-/// \brief The "namespaces" collection returns a level of namespaces defined
-/// in the database.
-///
-/// This collection generally results in an "N+1" query pattern. This is
-/// intended for systems that do not follow the SQL catalog-schema-table
-/// hierarchy; for systems that do, collections like "catalogs", "schemas",
-/// and "tables" will be more efficient as they can return multiple levels at
-/// once.
-///
-/// | Field Name | Field Type | Comments |
-/// |--------------------------|------------------------------|----------|
-/// | namespace_parent | list not null | |
-/// | namespace_name | utf8 not null | |
-///
-/// Supported filters:
-/// - ADBC_METADATA_FILTER_NAMESPACE
-/// - ADBC_METADATA_FILTER_NAMESPACE_NAME
-#define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces"
-
/// @}
/// @}
@@ -1769,6 +1767,8 @@ struct ADBC_EXPORT AdbcConnection {
/// 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.
+///
+/// The statement state machine is as follows:
struct ADBC_EXPORT AdbcStatement {
/// \brief Opaque implementation-defined state.
/// This field is NULLPTR iff the connection is uninitialized/freed.
@@ -2780,6 +2780,9 @@ AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection,
///
/// This AdbcConnection must outlive the returned ArrowArrayStream.
///
+/// This API may be deprecated in a future revision in favor of
+/// ADBC_METADATA_COLLECTION.
+///
/// \param[in] connection The database connection.
/// \param[in] depth The level of nesting to display. If 0, display
/// all levels. If 1, display only catalogs (i.e. catalog_schemas
@@ -3262,7 +3265,7 @@ AdbcStatusCode AdbcStatementExecuteSchema(struct AdbcStatement* statement,
struct ArrowSchema* schema,
struct AdbcError* error);
-/// \brief Request the schema of the next statement execution
+/// \brief Request the schema of the next statement execution.
///
/// Allows the caller to request a specific schema based on prior
/// information or user input. This may be used to ensure a
@@ -3270,16 +3273,16 @@ AdbcStatusCode AdbcStatementExecuteSchema(struct AdbcStatement* statement,
/// with row-based types (e.g., SQLite) or a database whose types
/// are implemented with row-based parameters where Arrow prefers
/// type-level parameters (e.g., NUMERIC for PostgreSQL). The
-/// schema request is intended to modify only the types or
-/// widen the nullability of types in the original schema;
-/// column reordering or changing the number of returned columns
-/// is not a goal of this feature.
+/// schema request is intended to modify only the types or widen
+/// the nullability of types in the original schema; column
+/// reordering or changing the number of returned columns of a
+/// result set in a query is not a goal of this feature.
///
/// The provided schema is a request and not a guarantee (i.e.,
/// callers must use the schema provided by the output stream to
/// interpret the result).
///
-/// Calling AdbcStatementRequestSchema() must not affect the result
+/// Calling AdbcStatementRequestSchema must not affect the result
/// of AdbcStatementExecuteSchema (which always infers its result
/// from the input query).
///