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). ///