kentkwu commented on code in PR #4694: URL: https://github.com/apache/arrow-adbc/pull/4694#discussion_r3962510989
########## 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 Review Comment: What's the value of mentioning offset-from-the-end here, as opposed to just specifying that field access must be by name? It seems only stable for a single driver at a single version, since you'd need to know how many fields that driver appends and in what order within its block. The paragraph also calls ordinal access brittle two sentences later, which seems to agree. Is there a scenario I'm missing? -- 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]
