From 1a391680fc9381da610f3f494121b93d434aecd3 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 | 444 +++++++++++++++++++++++++--- go/adbc/drivermgr/arrow-adbc/adbc.h | 444 +++++++++++++++++++++++++--- 2 files changed, 798 insertions(+), 90 deletions(-) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 82f05564a7..463d1e881a 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -1087,6 +1087,398 @@ 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. +/// +/// @{ + +/// \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 as appropriate. +/// +/// The type is char*. +#define ADBC_METADATA_FILTER_CATALOG "adbc.metadata.filter.catalog" + +/// \brief Filter the collection on the catalog name as appropriate, 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" + +/// The type is char*. +#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.schema" + +/// The type is char*. +#define ADBC_METADATA_FILTER_TABLE "adbc.metadata.filter.table" + +/// The type is char*. +#define ADBC_METADATA_FILTER_COLUMN "adbc.metadata.filter.column" + +/// Separator: comma (','). +/// The type is char*. +#define ADBC_METADATA_FILTER_TABLE_TYPES "adbc.metadata.filter.table_types" + +/// \brief Limit the collection to a specific multi-part namespace as +/// appropriate. +/// +/// Separator: ASCII unit separator (0x1F). +/// The type is char*. +#define ADBC_METADATA_FILTER_NAMESPACE "adbc.metadata.filter.namespace" + +/// \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. +/// +/// Filters: +/// 1. The catalog name to filter by. May be a search pattern. +/// 2. The schema name to filter by. May be a search pattern. +#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. +/// +/// Filters: +/// 1. The catalog name to filter by. May be a search pattern. +/// 2. The schema name to filter by. May be a search pattern. +/// 3. The table name to filter by. May be a search pattern. +/// 4. The remaining arguments are a list of table types to filter by. If +/// omitted, then tables of all types will be returned. +#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. +/// +/// Filters: +/// 1. The catalog name to filter by. May be a search pattern. +/// 2. The schema name to filter by. May be a search pattern. +/// 3. The table name to filter by. May be a search pattern. +/// 4. The remaining arguments are a list of table types to filter by. If +/// omitted, then tables of all types will be returned. +#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: +/// 1. The catalog of the foreign key table; required but may be NULL. +/// 2. The schema of the foreign key table; required but may be NULL. +/// 3. The name of the foreign key table; required. +#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: +/// 1. The catalog of the primary key table; required but may be NULL. +/// 2. The schema of the primary key table; required but may be NULL. +/// 3. The name of the primary key table; required. +#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. +#define ADBC_METADATA_COLLECTION_CONSTRAINTS "constraints" + +/// \brief The "namespaces" collection returns a level of namespaces defined +/// in the database. +/// +/// This API generally results in an "N+1" query pattern. This is intended for +/// systems that do not follow the SQL catalog-schema-table hierarchy. +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|------------------------------|----------| +/// | namespace_parent | list not null | | +/// | namespace_name | utf8 not null | | +/// +/// Filters: +/// 1. The namespace name to filter by. May be a search pattern. +/// 2. Variadic: the parent namespace(s) to filter by. If omitted, return all +/// top-level namespaces. +#define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces" + +/// @} + /// @} /// \defgroup adbc-database Database Initialization @@ -2116,58 +2508,20 @@ AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection, /// | constraint_type | utf8 not null | (1) | /// | constraint_column_names | list not null | (2) | /// | constraint_column_usage | list | (3) | -/// | constraint_expression | utf8 | (4) | -/// | constraint_update_rule | int16 | (5) | -/// | constraint_delete_rule | int16 | (5) | -/// | constraint_enforced | bool | (6) | -/// | constraint_deferrability | int16 | (7) | -/// | constraint_match_type | int16 | (8) | /// -/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE', or a -/// vendor-specific type. +/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE'. /// 2. The columns on the current table that are constrained, in /// order. /// 3. For FOREIGN KEY only, the referenced table and columns. -/// 4. [Since version 1.2.0] The vendor-specific definition of the constraint -/// (e.g. the SQL expression to be checked). This field is optional. -/// 5. [Since version 1.2.0] The action to be taken when the primary key is -/// updated or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ -/// constants. This field is optional. -/// 6. [Since version 1.2.0] Whether the constraint is currently enabled. -/// This field is optional. -/// 7. [Since version 1.2.0] 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. This field is optional. -/// 8. [Since version 1.2.0] How the foreign key constraint should be matched. -/// The value is one of the ADBC_CONSTRAINT_MATCH_ constants. This field -/// is optional. /// /// USAGE_SCHEMA is a Struct with fields: /// -/// | Field Name | Field Type | Comments | -/// |--------------------------|-------------------------|----------| -/// | fk_catalog | utf8 | | -/// | fk_db_schema | utf8 | | -/// | fk_table | utf8 not null | | -/// | fk_column_name | utf8 not null | | -/// | fk_key_seq | int32 | (1) | -/// | fk_pk_name | utf8 | (2) | -/// -/// 1. [Since version 1.2.0] The ordinal position of the column within the -/// foreign key. If present, the driver should sort the rows on this -/// column. This field is optional. -/// 2. [Since version 1.2.0] The name of the referenced primary key. This -/// field is optional. -/// -/// Starting in version 1.2.0, optional fields were introduced to the schema. -/// Optional fields may not be present in the returned schema/data and -/// applications should check for their presence before using them. Drivers -/// may choose to include optional fields (with null values) even if not -/// supported, but are not required to. If an optional field is present, all -/// optional fields defined before it in the schema must be present (but the -/// values may still be null if the driver does not actually support that -/// field). +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | fk_catalog | utf8 | +/// | fk_db_schema | utf8 | +/// | fk_table | utf8 not null | +/// | fk_column_name | utf8 not null | /// /// This AdbcConnection must outlive the returned ArrowArrayStream. /// diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h b/go/adbc/drivermgr/arrow-adbc/adbc.h index 82f05564a7..463d1e881a 100644 --- a/go/adbc/drivermgr/arrow-adbc/adbc.h +++ b/go/adbc/drivermgr/arrow-adbc/adbc.h @@ -1087,6 +1087,398 @@ 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. +/// +/// @{ + +/// \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 as appropriate. +/// +/// The type is char*. +#define ADBC_METADATA_FILTER_CATALOG "adbc.metadata.filter.catalog" + +/// \brief Filter the collection on the catalog name as appropriate, 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" + +/// The type is char*. +#define ADBC_METADATA_FILTER_DB_SCHEMA "adbc.metadata.filter.schema" + +/// The type is char*. +#define ADBC_METADATA_FILTER_TABLE "adbc.metadata.filter.table" + +/// The type is char*. +#define ADBC_METADATA_FILTER_COLUMN "adbc.metadata.filter.column" + +/// Separator: comma (','). +/// The type is char*. +#define ADBC_METADATA_FILTER_TABLE_TYPES "adbc.metadata.filter.table_types" + +/// \brief Limit the collection to a specific multi-part namespace as +/// appropriate. +/// +/// Separator: ASCII unit separator (0x1F). +/// The type is char*. +#define ADBC_METADATA_FILTER_NAMESPACE "adbc.metadata.filter.namespace" + +/// \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. +/// +/// Filters: +/// 1. The catalog name to filter by. May be a search pattern. +/// 2. The schema name to filter by. May be a search pattern. +#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. +/// +/// Filters: +/// 1. The catalog name to filter by. May be a search pattern. +/// 2. The schema name to filter by. May be a search pattern. +/// 3. The table name to filter by. May be a search pattern. +/// 4. The remaining arguments are a list of table types to filter by. If +/// omitted, then tables of all types will be returned. +#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. +/// +/// Filters: +/// 1. The catalog name to filter by. May be a search pattern. +/// 2. The schema name to filter by. May be a search pattern. +/// 3. The table name to filter by. May be a search pattern. +/// 4. The remaining arguments are a list of table types to filter by. If +/// omitted, then tables of all types will be returned. +#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: +/// 1. The catalog of the foreign key table; required but may be NULL. +/// 2. The schema of the foreign key table; required but may be NULL. +/// 3. The name of the foreign key table; required. +#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: +/// 1. The catalog of the primary key table; required but may be NULL. +/// 2. The schema of the primary key table; required but may be NULL. +/// 3. The name of the primary key table; required. +#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. +#define ADBC_METADATA_COLLECTION_CONSTRAINTS "constraints" + +/// \brief The "namespaces" collection returns a level of namespaces defined +/// in the database. +/// +/// This API generally results in an "N+1" query pattern. This is intended for +/// systems that do not follow the SQL catalog-schema-table hierarchy. +/// +/// | Field Name | Field Type | Comments | +/// |--------------------------|------------------------------|----------| +/// | namespace_parent | list not null | | +/// | namespace_name | utf8 not null | | +/// +/// Filters: +/// 1. The namespace name to filter by. May be a search pattern. +/// 2. Variadic: the parent namespace(s) to filter by. If omitted, return all +/// top-level namespaces. +#define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces" + +/// @} + /// @} /// \defgroup adbc-database Database Initialization @@ -2116,58 +2508,20 @@ AdbcStatusCode AdbcConnectionGetInfo(struct AdbcConnection* connection, /// | constraint_type | utf8 not null | (1) | /// | constraint_column_names | list not null | (2) | /// | constraint_column_usage | list | (3) | -/// | constraint_expression | utf8 | (4) | -/// | constraint_update_rule | int16 | (5) | -/// | constraint_delete_rule | int16 | (5) | -/// | constraint_enforced | bool | (6) | -/// | constraint_deferrability | int16 | (7) | -/// | constraint_match_type | int16 | (8) | /// -/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE', or a -/// vendor-specific type. +/// 1. One of 'CHECK', 'FOREIGN KEY', 'PRIMARY KEY', or 'UNIQUE'. /// 2. The columns on the current table that are constrained, in /// order. /// 3. For FOREIGN KEY only, the referenced table and columns. -/// 4. [Since version 1.2.0] The vendor-specific definition of the constraint -/// (e.g. the SQL expression to be checked). This field is optional. -/// 5. [Since version 1.2.0] The action to be taken when the primary key is -/// updated or deleted. The value is one of the ADBC_CONSTRAINT_ACTION_ -/// constants. This field is optional. -/// 6. [Since version 1.2.0] Whether the constraint is currently enabled. -/// This field is optional. -/// 7. [Since version 1.2.0] 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. This field is optional. -/// 8. [Since version 1.2.0] How the foreign key constraint should be matched. -/// The value is one of the ADBC_CONSTRAINT_MATCH_ constants. This field -/// is optional. /// /// USAGE_SCHEMA is a Struct with fields: /// -/// | Field Name | Field Type | Comments | -/// |--------------------------|-------------------------|----------| -/// | fk_catalog | utf8 | | -/// | fk_db_schema | utf8 | | -/// | fk_table | utf8 not null | | -/// | fk_column_name | utf8 not null | | -/// | fk_key_seq | int32 | (1) | -/// | fk_pk_name | utf8 | (2) | -/// -/// 1. [Since version 1.2.0] The ordinal position of the column within the -/// foreign key. If present, the driver should sort the rows on this -/// column. This field is optional. -/// 2. [Since version 1.2.0] The name of the referenced primary key. This -/// field is optional. -/// -/// Starting in version 1.2.0, optional fields were introduced to the schema. -/// Optional fields may not be present in the returned schema/data and -/// applications should check for their presence before using them. Drivers -/// may choose to include optional fields (with null values) even if not -/// supported, but are not required to. If an optional field is present, all -/// optional fields defined before it in the schema must be present (but the -/// values may still be null if the driver does not actually support that -/// field). +/// | Field Name | Field Type | +/// |--------------------------|-------------------------| +/// | fk_catalog | utf8 | +/// | fk_db_schema | utf8 | +/// | fk_table | utf8 not null | +/// | fk_column_name | utf8 not null | /// /// This AdbcConnection must outlive the returned ArrowArrayStream. /// From 282f02e4414a2f2e135cf6546fd9f8715abb4bdb Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 27 Aug 2026 13:16:49 +0900 Subject: [PATCH 2/6] add feature flag --- c/include/arrow-adbc/adbc.h | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 463d1e881a..1ccda4861f 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -598,15 +598,21 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// \brief Whether the driver supports getting table schemas (type: bool). /// \since ADBC API revision 1.2.0 /// \see AdbcConnectionGetInfo -/// \see AdbcConnectionGetObjects +/// \see AdbcConnectionGetTableSchema #define ADBC_INFO_FEATURE_TABLE_SCHEMA 221 /// \brief Whether the driver supports getting table types (type: bool). /// \since ADBC API revision 1.2.0 /// \see AdbcConnectionGetInfo -/// \see AdbcConnectionGetObjects +/// \see AdbcConnectionGetTableTypes #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_METDATA_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 From c55707bbe89aa5cfcbb70593e24f08197e85177f Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 27 Aug 2026 13:20:45 +0900 Subject: [PATCH 3/6] fix --- go/adbc/drivermgr/arrow-adbc/adbc.h | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h b/go/adbc/drivermgr/arrow-adbc/adbc.h index 463d1e881a..1ccda4861f 100644 --- a/go/adbc/drivermgr/arrow-adbc/adbc.h +++ b/go/adbc/drivermgr/arrow-adbc/adbc.h @@ -598,15 +598,21 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// \brief Whether the driver supports getting table schemas (type: bool). /// \since ADBC API revision 1.2.0 /// \see AdbcConnectionGetInfo -/// \see AdbcConnectionGetObjects +/// \see AdbcConnectionGetTableSchema #define ADBC_INFO_FEATURE_TABLE_SCHEMA 221 /// \brief Whether the driver supports getting table types (type: bool). /// \since ADBC API revision 1.2.0 /// \see AdbcConnectionGetInfo -/// \see AdbcConnectionGetObjects +/// \see AdbcConnectionGetTableTypes #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_METDATA_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 From 76fea9d864c72e196652e92402571ab8a0514197 Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 27 Aug 2026 13:21:25 +0900 Subject: [PATCH 4/6] fix some declarations --- c/include/arrow-adbc/adbc.h | 11 +++++++---- go/adbc/drivermgr/arrow-adbc/adbc.h | 11 +++++++---- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 1ccda4861f..66e8880afb 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -1901,7 +1901,10 @@ struct ADBC_EXPORT AdbcDriver { /// /// @{ - int (*AdbcErrorGetVendorCode)(const struct AdbcError*); + int (*ErrorGetVendorCode)(const struct AdbcError*); + + int (*DriverGetOptionsList)(uint32_t, struct ArrowArrayStream*, + const struct AdbcError*); AdbcStatusCode (*MultiResultSetNext)(struct AdbcMultiResultSet*, struct ArrowArrayStream*, int64_t*, @@ -1913,8 +1916,8 @@ struct ADBC_EXPORT AdbcDriver { AdbcStatusCode (*MultiResultSetRelease)(struct AdbcMultiResultSet*, struct AdbcError*); AdbcStatusCode (*ConnectionSetWarningHandler)(struct AdbcConnection*, - AdbcWarningHandler handler, - void* user_data, struct AdbcError*); + AdbcWarningHandler, void*, + struct AdbcError*); AdbcStatusCode (*StatementExecuteSchemaMulti)(struct AdbcStatement*, struct AdbcMultiResultSet*, @@ -1942,7 +1945,7 @@ struct ADBC_EXPORT AdbcDriver { /// ADBC_VERSION_1_1_0. /// /// \since ADBC API revision 1.1.0 -#define ADBC_DRIVER_1_1_0_SIZE (offsetof(struct AdbcDriver, StatementExecuteMulti)) +#define ADBC_DRIVER_1_1_0_SIZE (offsetof(struct AdbcDriver, ErrorGetVendorCode)) /// \brief The size of the AdbcDriver structure in ADBC 1.2.0. /// Drivers written for ADBC 1.2.0 and later should never touch more diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h b/go/adbc/drivermgr/arrow-adbc/adbc.h index 1ccda4861f..66e8880afb 100644 --- a/go/adbc/drivermgr/arrow-adbc/adbc.h +++ b/go/adbc/drivermgr/arrow-adbc/adbc.h @@ -1901,7 +1901,10 @@ struct ADBC_EXPORT AdbcDriver { /// /// @{ - int (*AdbcErrorGetVendorCode)(const struct AdbcError*); + int (*ErrorGetVendorCode)(const struct AdbcError*); + + int (*DriverGetOptionsList)(uint32_t, struct ArrowArrayStream*, + const struct AdbcError*); AdbcStatusCode (*MultiResultSetNext)(struct AdbcMultiResultSet*, struct ArrowArrayStream*, int64_t*, @@ -1913,8 +1916,8 @@ struct ADBC_EXPORT AdbcDriver { AdbcStatusCode (*MultiResultSetRelease)(struct AdbcMultiResultSet*, struct AdbcError*); AdbcStatusCode (*ConnectionSetWarningHandler)(struct AdbcConnection*, - AdbcWarningHandler handler, - void* user_data, struct AdbcError*); + AdbcWarningHandler, void*, + struct AdbcError*); AdbcStatusCode (*StatementExecuteSchemaMulti)(struct AdbcStatement*, struct AdbcMultiResultSet*, @@ -1942,7 +1945,7 @@ struct ADBC_EXPORT AdbcDriver { /// ADBC_VERSION_1_1_0. /// /// \since ADBC API revision 1.1.0 -#define ADBC_DRIVER_1_1_0_SIZE (offsetof(struct AdbcDriver, StatementExecuteMulti)) +#define ADBC_DRIVER_1_1_0_SIZE (offsetof(struct AdbcDriver, ErrorGetVendorCode)) /// \brief The size of the AdbcDriver structure in ADBC 1.2.0. /// Drivers written for ADBC 1.2.0 and later should never touch more From 6fd647b5fb6d9a21d354698e2f6d8beb05e2897c Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 27 Aug 2026 16:05:51 +0900 Subject: [PATCH 5/6] misc fixes; harmonize filters --- c/include/arrow-adbc/adbc.h | 293 ++++++++++++++++++++++++---- go/adbc/drivermgr/arrow-adbc/adbc.h | 45 ++++- 2 files changed, 295 insertions(+), 43 deletions(-) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 66e8880afb..2fe65a69b6 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -611,7 +611,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// \since ADBC API revision 1.2.0 /// \see AdbcConnectionGetInfo /// \see ADBC_METADATA_COLLECTION -#define ADBC_INFO_FEATURE_METDATA_COLLECTION 223 +#define ADBC_INFO_FEATURE_METADATA_COLLECTION 223 /// \brief Whether the driver supports transactions (true), or if autocommit /// is always enabled (false) (type: bool). @@ -1138,6 +1138,8 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// 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. @@ -1145,13 +1147,13 @@ 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 as appropriate. +/// \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 as appropriate, matching -/// a search pattern. +/// \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. @@ -1159,26 +1161,123 @@ 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. +/// /// 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 Limit the collection to a specific multi-part namespace as -/// appropriate. +/// \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 @@ -1217,9 +1316,8 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// (1) A description of the catalog. /// /// Supported filters: -/// -/// - ADBC_METADATA_FILTER_CATALOG, -/// - ADBC_METADATA_FILTER_PATTERN_CATALOG. +/// - 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 @@ -1237,9 +1335,11 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// /// (1) A description of the schema. /// -/// Filters: -/// 1. The catalog name to filter by. May be a search pattern. -/// 2. The schema name to filter by. May be a search pattern. +/// 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 @@ -1260,12 +1360,15 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// (3) The Arrow schema of the table, equivalent to /// AdbcConnectionGetTableSchema. /// -/// Filters: -/// 1. The catalog name to filter by. May be a search pattern. -/// 2. The schema name to filter by. May be a search pattern. -/// 3. The table name to filter by. May be a search pattern. -/// 4. The remaining arguments are a list of table types to filter by. If -/// omitted, then tables of all types will be returned. +/// +/// 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. @@ -1302,12 +1405,16 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// xdbc_ values are meant to provide JDBC/ODBC-compatible metadata /// in an agnostic manner. /// -/// Filters: -/// 1. The catalog name to filter by. May be a search pattern. -/// 2. The schema name to filter by. May be a search pattern. -/// 3. The table name to filter by. May be a search pattern. -/// 4. The remaining arguments are a list of table types to filter by. If -/// omitted, then tables of all types will be returned. +/// 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 @@ -1344,9 +1451,9 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// the ADBC_CONSTRAINT_MATCH_ constants. /// /// Filters: -/// 1. The catalog of the foreign key table; required but may be NULL. -/// 2. The schema of the foreign key table; required but may be NULL. -/// 3. The name of the foreign key table; required. +/// - 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 @@ -1383,9 +1490,12 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// the ADBC_CONSTRAINT_MATCH_ constants. /// /// Filters: -/// 1. The catalog of the primary key table; required but may be NULL. -/// 2. The schema of the primary key table; required but may be NULL. -/// 3. The name of the primary key table; required. +/// - 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 @@ -1464,23 +1574,124 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// 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 API generally results in an "N+1" query pattern. This is intended for -/// systems that do not follow the SQL catalog-schema-table hierarchy. +/// 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 | | /// -/// Filters: -/// 1. The namespace name to filter by. May be a search pattern. -/// 2. Variadic: the parent namespace(s) to filter by. If omitted, return all -/// top-level namespaces. +/// Supported filters: +/// - ADBC_METADATA_FILTER_NAMESPACE +/// - ADBC_METADATA_FILTER_NAMESPACE_NAME #define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces" /// @} @@ -1645,6 +1856,7 @@ struct ADBC_EXPORT AdbcMultiResultSet { /// \param[out] error An optional location to return an error message if necessary. /// /// \return ADBC_STATUS_OK on success or an appropriate error code. +ADBC_EXPORT AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set, struct AdbcError* error); @@ -1677,6 +1889,7 @@ AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set, /// /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results /// as partitions or ADBC_STATUS_OK (or an appropriate error code) otherwise. +ADBC_EXPORT AdbcStatusCode AdbcMultiResultSetNext(struct AdbcMultiResultSet* result_set, struct ArrowArrayStream* out, int64_t* rows_affected, struct AdbcError* error); @@ -1713,6 +1926,7 @@ AdbcStatusCode AdbcMultiResultSetNext(struct AdbcMultiResultSet* result_set, /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results /// as a stream, ADBC_STATUS_INVALID_STATE if called at an inappropriate time, and /// ADBC_STATUS_OK (or an appropriate error code) otherwise. +ADBC_EXPORT AdbcStatusCode AdbcMultiResultSetNextPartitions(struct AdbcMultiResultSet* result_set, struct ArrowSchema* schema, struct AdbcPartitions* partitions, @@ -1903,8 +2117,8 @@ struct ADBC_EXPORT AdbcDriver { int (*ErrorGetVendorCode)(const struct AdbcError*); - int (*DriverGetOptionsList)(uint32_t, struct ArrowArrayStream*, - const struct AdbcError*); + AdbcStatusCode (*DriverGetOptionsList)(uint32_t, struct ArrowArrayStream*, + struct AdbcError*); AdbcStatusCode (*MultiResultSetNext)(struct AdbcMultiResultSet*, struct ArrowArrayStream*, int64_t*, @@ -1971,7 +2185,8 @@ struct ADBC_EXPORT AdbcDriver { /// \see AdbcDriverGetOptionsList /// \since ADBC API revision 1.2.0 #define ADBC_OPTION_LEVEL_ALL \ - (ADBC_OPTION_LEVEL_DATABASE | ADBC_OPTION_CONNECTION | ADBC_OPTION_STATEMENT) + (ADBC_OPTION_LEVEL_DATABASE | ADBC_OPTION_LEVEL_CONNECTION | \ + ADBC_OPTION_LEVEL_STATEMENT) /// \brief A string-valued option. /// \see AdbcDriverGetOptionsList diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h b/go/adbc/drivermgr/arrow-adbc/adbc.h index 66e8880afb..effc0f578a 100644 --- a/go/adbc/drivermgr/arrow-adbc/adbc.h +++ b/go/adbc/drivermgr/arrow-adbc/adbc.h @@ -611,7 +611,7 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// \since ADBC API revision 1.2.0 /// \see AdbcConnectionGetInfo /// \see ADBC_METADATA_COLLECTION -#define ADBC_INFO_FEATURE_METDATA_COLLECTION 223 +#define ADBC_INFO_FEATURE_METADATA_COLLECTION 223 /// \brief Whether the driver supports transactions (true), or if autocommit /// is always enabled (false) (type: bool). @@ -1466,6 +1466,39 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// the ADBC_CONSTRAINT_MATCH_ constants. #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_specific_name | utf8 | (1) | +/// | routine_type | utf8 not null | (2) | +/// | routine_remarks | utf8 | (3) | +/// | routine_parameters | list | (4) | +/// | routine_result | list | (4) | +/// | routine_parameter_schema | binary | (5) | +/// | routine_result_schema | binary | (5) | +/// +/// 1. A name that uniquely identifies the routine, to disambiguate +/// overloads. +/// 2. 'FUNCTION', 'PROCEDURE', or a vendor-specific name (e.g. 'TABLE +/// FUNCTION'). +/// 3. Vendor-specific description of the routine. +/// 4. Metadata about the accepted parameters and return values as structured +/// Arrow data. Only populated if include_columns is set, otherwise null. +/// 5. Metadata about the accepted parameters and return values as an Arrow +/// schema, serialized as an IPC message containing a schema Flatbuffers +/// structure. Only populated if include_arrow_schema is set, otherwise +/// null. +/// +/// Supported filters: +/// +/// - ADBC_METADATA_FILTER_CATALOG, +/// - ADBC_METADATA_FILTER_PATTERN_CATALOG. +#define ADBC_METADATA_COLLECTION_ROUTINES "routines" + /// \brief The "namespaces" collection returns a level of namespaces defined /// in the database. /// @@ -1645,6 +1678,7 @@ struct ADBC_EXPORT AdbcMultiResultSet { /// \param[out] error An optional location to return an error message if necessary. /// /// \return ADBC_STATUS_OK on success or an appropriate error code. +ADBC_EXPORT AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set, struct AdbcError* error); @@ -1677,6 +1711,7 @@ AdbcStatusCode AdbcMultiResultSetRelease(struct AdbcMultiResultSet* result_set, /// /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results /// as partitions or ADBC_STATUS_OK (or an appropriate error code) otherwise. +ADBC_EXPORT AdbcStatusCode AdbcMultiResultSetNext(struct AdbcMultiResultSet* result_set, struct ArrowArrayStream* out, int64_t* rows_affected, struct AdbcError* error); @@ -1713,6 +1748,7 @@ AdbcStatusCode AdbcMultiResultSetNext(struct AdbcMultiResultSet* result_set, /// \return ADBC_STATUS_NOT_IMPLEMENTED if the driver only supports fetching results /// as a stream, ADBC_STATUS_INVALID_STATE if called at an inappropriate time, and /// ADBC_STATUS_OK (or an appropriate error code) otherwise. +ADBC_EXPORT AdbcStatusCode AdbcMultiResultSetNextPartitions(struct AdbcMultiResultSet* result_set, struct ArrowSchema* schema, struct AdbcPartitions* partitions, @@ -1903,8 +1939,8 @@ struct ADBC_EXPORT AdbcDriver { int (*ErrorGetVendorCode)(const struct AdbcError*); - int (*DriverGetOptionsList)(uint32_t, struct ArrowArrayStream*, - const struct AdbcError*); + AdbcStatusCode (*DriverGetOptionsList)(uint32_t, struct ArrowArrayStream*, + struct AdbcError*); AdbcStatusCode (*MultiResultSetNext)(struct AdbcMultiResultSet*, struct ArrowArrayStream*, int64_t*, @@ -1971,7 +2007,8 @@ struct ADBC_EXPORT AdbcDriver { /// \see AdbcDriverGetOptionsList /// \since ADBC API revision 1.2.0 #define ADBC_OPTION_LEVEL_ALL \ - (ADBC_OPTION_LEVEL_DATABASE | ADBC_OPTION_CONNECTION | ADBC_OPTION_STATEMENT) + (ADBC_OPTION_LEVEL_DATABASE | ADBC_OPTION_LEVEL_CONNECTION | \ + ADBC_OPTION_LEVEL_STATEMENT) /// \brief A string-valued option. /// \see AdbcDriverGetOptionsList From a7ce38927cfb07a3242b54d42abcc32e5035c506 Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 27 Aug 2026 16:13:14 +0900 Subject: [PATCH 6/6] lint --- c/include/arrow-adbc/adbc.h | 2 +- go/adbc/drivermgr/arrow-adbc/adbc.h | 300 ++++++++++++++++++++++------ 2 files changed, 240 insertions(+), 62 deletions(-) diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h index 2fe65a69b6..38ee7f5a53 100644 --- a/c/include/arrow-adbc/adbc.h +++ b/c/include/arrow-adbc/adbc.h @@ -2184,7 +2184,7 @@ struct ADBC_EXPORT AdbcDriver { /// \brief An option that can be set on a database, connection, or statement. /// \see AdbcDriverGetOptionsList /// \since ADBC API revision 1.2.0 -#define ADBC_OPTION_LEVEL_ALL \ +#define ADBC_OPTION_LEVEL_ALL \ (ADBC_OPTION_LEVEL_DATABASE | ADBC_OPTION_LEVEL_CONNECTION | \ ADBC_OPTION_LEVEL_STATEMENT) diff --git a/go/adbc/drivermgr/arrow-adbc/adbc.h b/go/adbc/drivermgr/arrow-adbc/adbc.h index effc0f578a..38ee7f5a53 100644 --- a/go/adbc/drivermgr/arrow-adbc/adbc.h +++ b/go/adbc/drivermgr/arrow-adbc/adbc.h @@ -1138,6 +1138,8 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// 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. @@ -1145,13 +1147,13 @@ 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 as appropriate. +/// \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 as appropriate, matching -/// a search pattern. +/// \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. @@ -1159,26 +1161,123 @@ 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. +/// /// 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 Limit the collection to a specific multi-part namespace as -/// appropriate. +/// \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 @@ -1217,9 +1316,8 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// (1) A description of the catalog. /// /// Supported filters: -/// -/// - ADBC_METADATA_FILTER_CATALOG, -/// - ADBC_METADATA_FILTER_PATTERN_CATALOG. +/// - 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 @@ -1237,9 +1335,11 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// /// (1) A description of the schema. /// -/// Filters: -/// 1. The catalog name to filter by. May be a search pattern. -/// 2. The schema name to filter by. May be a search pattern. +/// 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 @@ -1260,12 +1360,15 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// (3) The Arrow schema of the table, equivalent to /// AdbcConnectionGetTableSchema. /// -/// Filters: -/// 1. The catalog name to filter by. May be a search pattern. -/// 2. The schema name to filter by. May be a search pattern. -/// 3. The table name to filter by. May be a search pattern. -/// 4. The remaining arguments are a list of table types to filter by. If -/// omitted, then tables of all types will be returned. +/// +/// 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. @@ -1302,12 +1405,16 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// xdbc_ values are meant to provide JDBC/ODBC-compatible metadata /// in an agnostic manner. /// -/// Filters: -/// 1. The catalog name to filter by. May be a search pattern. -/// 2. The schema name to filter by. May be a search pattern. -/// 3. The table name to filter by. May be a search pattern. -/// 4. The remaining arguments are a list of table types to filter by. If -/// omitted, then tables of all types will be returned. +/// 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 @@ -1344,9 +1451,9 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// the ADBC_CONSTRAINT_MATCH_ constants. /// /// Filters: -/// 1. The catalog of the foreign key table; required but may be NULL. -/// 2. The schema of the foreign key table; required but may be NULL. -/// 3. The name of the foreign key table; required. +/// - 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 @@ -1383,9 +1490,12 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// the ADBC_CONSTRAINT_MATCH_ constants. /// /// Filters: -/// 1. The catalog of the primary key table; required but may be NULL. -/// 2. The schema of the primary key table; required but may be NULL. -/// 3. The name of the primary key table; required. +/// - 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 @@ -1464,56 +1574,124 @@ const struct AdbcError* AdbcErrorFromArrayStream(struct ArrowArrayStream* stream /// 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_specific_name | utf8 | (1) | -/// | routine_type | utf8 not null | (2) | -/// | routine_remarks | utf8 | (3) | -/// | routine_parameters | list | (4) | -/// | routine_result | list | (4) | -/// | routine_parameter_schema | binary | (5) | -/// | routine_result_schema | binary | (5) | -/// -/// 1. A name that uniquely identifies the routine, to disambiguate -/// overloads. -/// 2. 'FUNCTION', 'PROCEDURE', or a vendor-specific name (e.g. 'TABLE +/// | 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'). -/// 3. Vendor-specific description of the routine. -/// 4. Metadata about the accepted parameters and return values as structured -/// Arrow data. Only populated if include_columns is set, otherwise null. +/// 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, serialized as an IPC message containing a schema Flatbuffers -/// structure. Only populated if include_arrow_schema is set, otherwise -/// null. +/// schema. /// /// Supported filters: -/// -/// - ADBC_METADATA_FILTER_CATALOG, -/// - ADBC_METADATA_FILTER_PATTERN_CATALOG. +/// - 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 API generally results in an "N+1" query pattern. This is intended for -/// systems that do not follow the SQL catalog-schema-table hierarchy. +/// 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 | | /// -/// Filters: -/// 1. The namespace name to filter by. May be a search pattern. -/// 2. Variadic: the parent namespace(s) to filter by. If omitted, return all -/// top-level namespaces. +/// Supported filters: +/// - ADBC_METADATA_FILTER_NAMESPACE +/// - ADBC_METADATA_FILTER_NAMESPACE_NAME #define ADBC_METADATA_COLLECTION_NAMESPACES "namespaces" /// @} @@ -2006,7 +2184,7 @@ struct ADBC_EXPORT AdbcDriver { /// \brief An option that can be set on a database, connection, or statement. /// \see AdbcDriverGetOptionsList /// \since ADBC API revision 1.2.0 -#define ADBC_OPTION_LEVEL_ALL \ +#define ADBC_OPTION_LEVEL_ALL \ (ADBC_OPTION_LEVEL_DATABASE | ADBC_OPTION_LEVEL_CONNECTION | \ ADBC_OPTION_LEVEL_STATEMENT)