Clarify documentation on ADBC_GET_OBJECTS_DEPTH values

[paleolimbot]

What happened?

As discovered in OSGeo/gdal#11003 (comment) , the documentation for ADBC_OBJECT_DEPTH_DB_SCHEMAS suggests that using its value will result in table metadata; however, using ADBC_OBJECT_DEPTH_DB_TABLES is required to actually get a list of tables.

arrow-adbc/c/include/arrow-adbc/adbc.h

Lines 503 to 522 in cd24bc0

	/// \brief Return metadata on catalogs, schemas, tables, and columns.
	///
	/// \see AdbcConnectionGetObjects
	#define ADBC_OBJECT_DEPTH_ALL 0
	/// \brief Return metadata on catalogs only.
	///
	/// \see AdbcConnectionGetObjects
	#define ADBC_OBJECT_DEPTH_CATALOGS 1
	/// \brief Return metadata on catalogs and schemas.
	///
	/// \see AdbcConnectionGetObjects
	#define ADBC_OBJECT_DEPTH_DB_SCHEMAS 2
	/// \brief Return metadata on catalogs, schemas, and tables.
	///
	/// \see AdbcConnectionGetObjects
	#define ADBC_OBJECT_DEPTH_TABLES 3
	/// \brief Return metadata on catalogs, schemas, tables, and columns.
	///
	/// \see AdbcConnectionGetObjects
	#define ADBC_OBJECT_DEPTH_COLUMNS ADBC_OBJECT_DEPTH_ALL

library(adbcdrivermanager)

con <- adbc_database_init(adbcsqlite::adbcsqlite()) |> 
  adbc_connection_init()


mtcars |> 
  write_adbc(con, "some_table")

adbc_connection_get_objects(con, depth = 1L) |> 
  tibble::as_tibble() |> 
  tidyr::unnest_longer(catalog_db_schemas) |> 
  tidyr::unnest_wider(catalog_db_schemas) |> 
  tidyr::unnest_longer(db_schema_tables) |> 
  tidyr::unnest_wider(db_schema_tables) |> 
  dplyr::select(-table_constraints) |> 
  tidyr::unnest_longer(table_columns)
#> # A tibble: 0 × 5
#> # ℹ 5 variables: catalog_name <chr>, db_schema_name <chr>, table_name <chr>,
#> #   table_type <chr>, table_columns <df[,19]>

adbc_connection_get_objects(con, depth = 2L) |> 
  tibble::as_tibble() |> 
  tidyr::unnest_longer(catalog_db_schemas) |> 
  tidyr::unnest_wider(catalog_db_schemas) |> 
  tidyr::unnest_longer(db_schema_tables) |> 
  tidyr::unnest_wider(db_schema_tables) |> 
  dplyr::select(-table_constraints) |> 
  tidyr::unnest_longer(table_columns)
#> # A tibble: 1 × 5
#>   catalog_name db_schema_name table_name table_type table_columns$column_name
#>   <chr>        <chr>          <chr>      <chr>      <chr>                    
#> 1 main         ""             <NA>       <NA>       <NA>                     
#> # ℹ 18 more variables: table_columns$ordinal_position <int>, $remarks <chr>,
#> #   $xdbc_data_type <int>, $xdbc_type_name <chr>, $xdbc_column_size <int>,
#> #   $xdbc_decimal_digits <int>, $xdbc_num_prec_radix <int>,
#> #   $xdbc_nullable <int>, $xdbc_column_def <chr>, $xdbc_sql_data_type <int>,
#> #   $xdbc_datetime_sub <int>, $xdbc_char_octet_length <int>,
#> #   $xdbc_is_nullable <chr>, $xdbc_scope_catalog <chr>,
#> #   $xdbc_scope_schema <chr>, $xdbc_scope_table <chr>, …

adbc_connection_get_objects(con, depth = 3L) |> 
  tibble::as_tibble() |> 
  tidyr::unnest_longer(catalog_db_schemas) |> 
  tidyr::unnest_wider(catalog_db_schemas) |> 
  tidyr::unnest_longer(db_schema_tables) |> 
  tidyr::unnest_wider(db_schema_tables) |> 
  dplyr::select(-table_constraints) |> 
  tidyr::unnest_longer(table_columns)
#> # A tibble: 1 × 5
#>   catalog_name db_schema_name table_name table_type table_columns$column_name
#>   <chr>        <chr>          <chr>      <chr>      <chr>                    
#> 1 main         ""             some_table table      <NA>                     
#> # ℹ 18 more variables: table_columns$ordinal_position <int>, $remarks <chr>,
#> #   $xdbc_data_type <int>, $xdbc_type_name <chr>, $xdbc_column_size <int>,
#> #   $xdbc_decimal_digits <int>, $xdbc_num_prec_radix <int>,
#> #   $xdbc_nullable <int>, $xdbc_column_def <chr>, $xdbc_sql_data_type <int>,
#> #   $xdbc_datetime_sub <int>, $xdbc_char_octet_length <int>,
#> #   $xdbc_is_nullable <chr>, $xdbc_scope_catalog <chr>,
#> #   $xdbc_scope_schema <chr>, $xdbc_scope_table <chr>, …

adbc_connection_get_objects(con, depth = 0L) |> 
  tibble::as_tibble() |> 
  tidyr::unnest_longer(catalog_db_schemas) |> 
  tidyr::unnest_wider(catalog_db_schemas) |> 
  tidyr::unnest_longer(db_schema_tables) |> 
  tidyr::unnest_wider(db_schema_tables) |> 
  dplyr::select(-table_constraints) |> 
  tidyr::unnest_longer(table_columns)
#> # A tibble: 1 × 5
#>   catalog_name db_schema_name table_name table_type   table_columns
#>   <chr>        <chr>          <chr>      <chr>      <list<df[,19]>>
#> 1 main         ""             some_table table            [11 × 19]

^{Created on 2024-10-14 with reprex v2.1.1}

Stack Trace

No response

How can we reproduce the bug?

No response

Environment/Setup

No response

[paleolimbot]

Ooops, ignore me, it's just that the \brief is a little misleading here because it applies to the next one. It might not hurt to add a blank line between them to prevent this mistake from happening again!