amoeba commented on code in PR #4694:
URL: https://github.com/apache/arrow-adbc/pull/4694#discussion_r3896048512
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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.
Review Comment:
Kind of burying the lede here. Do you think it would be helpful if this was
right at the top of the defgroup doc? And maybe this PR could add a comment on
AdbcConnectionGetObjects about the potential future for deprecation.
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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.
Review Comment:
Is the pattern driver specific?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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
Review Comment:
Hrm. The current doc comment on AdbcStatementRequestSchema says,
> column reordering or changing the number of returned columns
> is not a goal of this feature.
Could this be confusing?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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"
Review Comment:
Typo:
```suggestion
#define ADBC_METADATA_FILTER_PATTERN_DB_SCHEMA
"adbc.metadata.filter_pattern.schema"
```
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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
Review Comment:
```suggestion
/// All drivers that implement this API must implement a collection called
"meta" (which is aliased to
```
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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.
Review Comment:
To add: What should I do if I'm starting a new diver project? Implement both
GetObjects _and_ this? I'd think that's what we want so we could say it clearly
here.
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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 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<arrow.schema_json> | |
+/// | collection_filters | list<FILTER_SCHEMA> | |
+///
+/// FILTER_SCHEMA is a Struct with fields:
+///
+/// | Field Name | Field Type | Comments |
+/// |--------------------------|------------------------------|----------|
+/// | filter_description | utf8 | |
+/// | required | bool not null | |
Review Comment:
How can the client act on `collection_filters` given this schema?
Say I query the meta collection and see it has a tables member and
collection_filters is non-zero. Now I know I can list tables with a filter but
how does collection_filters help me filter?
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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.
Review Comment:
This was hard to understand for me as written. Does this option let me
filter to tables that are referenced by a table whose name I provide?
My confusion goes for this and the other options related to foreign keys.
Maybe we mean something more like,
> Filter the collection on the literal catalog name of the referencing table.
NB: I didn't catch this on my first read through but gpt-5.6-sol flagged it
and I found I wasn't able to explain it one way or the other.
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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 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 | |
Review Comment:
Minor: As a driver author, I'm not sure I'd know what to put in here.
##########
c/include/arrow-adbc/adbc.h:
##########
@@ -1087,6 +1093,582 @@ 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). 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 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
+/// 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.
Review Comment:
I'm not sure this is right but:
```suggestion
/// \brief Filter the collection on the literal schema name of the foreign
/// key.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
