feat(glib): Add garrow_connection_get_statistics()

ci/conda_env_glib.txt

@@ -19,4 +19,5 @@ arrow-c-glib
 glib
 gobject-introspection
 meson
+postgresql
 ruby

glib/adbc-glib/connection.c

@@ -35,6 +35,35 @@
 #define BOOLEAN_TO_OPTION_VALUE(boolean) \
   ((boolean) ? ADBC_OPTION_VALUE_ENABLED : ADBC_OPTION_VALUE_DISABLED)
 
+/**
+ * gadbc_statistic_key_to_string:
+ * @key: A #GADBCStatisticsKey.
+ *
+ * Returns: The name of @key.
+ *
+ * Since: 1.0.0
+ */
+const gchar* gadbc_statistic_key_to_string(GADBCStatisticKey key) {
+  switch (key) {
+    case GADBC_STATISTIC_KEY_AVERAGE_BYTE_WIDTH:
+      return ADBC_STATISTIC_AVERAGE_BYTE_WIDTH_NAME;
+    case GADBC_STATISTIC_KEY_DISTINCT_COUNT:
+      return ADBC_STATISTIC_DISTINCT_COUNT_NAME;
+    case GADBC_STATISTIC_KEY_MAX_BYTE_WIDTH:
+      return ADBC_STATISTIC_MAX_BYTE_WIDTH_NAME;
+    case GADBC_STATISTIC_KEY_MAX_VALUE:
+      return ADBC_STATISTIC_MAX_VALUE_NAME;
+    case GADBC_STATISTIC_KEY_MIN_VALUE:
+      return ADBC_STATISTIC_MIN_VALUE_NAME;
+    case GADBC_STATISTIC_KEY_NULL_COUNT:
+      return ADBC_STATISTIC_NULL_COUNT_NAME;
+    case GADBC_STATISTIC_KEY_ROW_COUNT:
+      return ADBC_STATISTIC_ROW_COUNT_NAME;
+    default:
+      return "adbc.statistic.invalid";
+  }
+}
+
 /**
  * gadbc_isolation_level_to_string:
  * @level: A #GADBCIsolationLevel.
@@ -538,6 +567,93 @@ gpointer gadbc_connection_get_table_types(GADBCConnection* connection, GError**
   }
 }
 
+/**
+ * gadbc_connection_get_statistics:
+ * @connection: A #GADBCConnection.
+ * @catalog: (nullable): A catalog or %NULL if not applicable.
+ * @db_schema: (nullable): A database schema or %NULL if not applicable.
+ * @table_name: (nullable): A table name.
+ * @approximate: Whether approximate values are allowed or not. If
+ *   this is %TRUE, best-effort, approximate or cached values may be
+ *   returned. Otherwise, exact values are requested. Note that the
+ *   database may return approximate values regardless as indicated
+ *   in the result. Request exact values may be expensive or
+ *   unsupported.
+ * @error: (nullable): Return location for a #GError or %NULL.
+ *
+ * The result is an Arrow dataset with the following schema:
+ *
+ * | Field Name               | Field Type                       |
+ * |--------------------------|----------------------------------|
+ * | catalog_name             | utf8                             |
+ * | catalog_db_schemas       | list<DB_SCHEMA_SCHEMA> not null  |
+ *
+ * DB_SCHEMA_SCHEMA is a Struct with fields:
+ *
+ * | Field Name               | Field Type                       |
+ * |--------------------------|----------------------------------|
+ * | db_schema_name           | utf8                             |
+ * | db_schema_statistics     | list<STATISTICS_SCHEMA> not null |
+ *
+ * STATISTICS_SCHEMA is a Struct with fields:
+ *
+ * | Field Name               | Field Type                       | Comments |
+ * |--------------------------|----------------------------------| -------- |
+ * | table_name               | utf8 not null                    |          |
+ * | column_name              | utf8                             | (1)      |
+ * | statistic_key            | int16 not null                   | (2)      |
+ * | statistic_value          | VALUE_SCHEMA not null            |          |
+ * | statistic_is_approximate | bool not null                    | (3)      |
+ *
+ * 1. If null, then the statistic applies to the entire table.
+ * 2. A dictionary-encoded statistic name (although we do not use the Arrow
+ *    dictionary type). Values in [0, 1024) are reserved for ADBC.  Other
+ *    values are for implementation-specific statistics.  For the definitions
+ *    of predefined statistic types, see %GADBCStatistics. To get
+ *    driver-specific statistic names, use
+ *    gadbc_connection_get_statistic_names().
+ * 3. If true, then the value is approximate or best-effort.
+ *
+ * VALUE_SCHEMA is a dense union with members:
+ *
+ * | Field Name               | Field Type                       |
+ * |--------------------------|----------------------------------|
+ * | int64                    | int64                            |
+ * | uint64                   | uint64                           |
+ * | float64                  | float64                          |
+ * | binary                   | binary                           |
+ *
+ * Returns: The result set as `struct ArrowArrayStream *`. It should
+ *   be freed with the `ArrowArrayStream:release` callback then
+ *   g_free() when no longer needed.
+ *
+ *   This GADBCConnection must outlive the returned stream.
+ *
+ * Since: 1.0.0
+ */
+gpointer gadbc_connection_get_statistics(GADBCConnection* connection,
+                                         const gchar* catalog, const gchar* db_schema,
+                                         const gchar* table_name, gboolean approximate,
+                                         GError** error) {
+  const gchar* context = "[adbc][connection][get-statistics]";
+  struct AdbcConnection* adbc_connection =
+      gadbc_connection_get_raw(connection, context, error);
+  if (!adbc_connection) {
+    return NULL;
+  }
+  struct ArrowArrayStream* array_stream = g_new0(struct ArrowArrayStream, 1);
+  struct AdbcError adbc_error = {};
+  AdbcStatusCode status_code =
+      AdbcConnectionGetStatistics(adbc_connection, catalog, db_schema, table_name,
+                                  approximate, array_stream, &adbc_error);
+  if (gadbc_error_check(error, status_code, &adbc_error, context)) {
+    return array_stream;
+  } else {
+    g_free(array_stream);
+    return NULL;
+  }
+}
+
 /**
  * gadbc_connection_commit:
  * @connection: A #GADBCConnection.

glib/adbc-glib/connection.h

@@ -23,6 +23,24 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GADBC_VERSION_1_0_0:
+ *
+ * ADBC revision 1.0.0.
+ *
+ * Since: 1.0.0
+ */
+#define GADBC_VERSION_1_0_0 1000000
+
+/**
+ * GADBC_VERSION_1_1_0:
+ *
+ * ADBC revision 1.1.0.
+ *
+ * Since: 1.0.0
+ */
+#define GADBC_VERSION_1_1_0 1001000
+
 /**
  * GADBCInfo:
  * @GADBC_INFO_VENDOR_NAME: The database vendor/product name (e.g. the
@@ -35,6 +53,8 @@ G_BEGIN_DECLS
  * @GADBC_INFO_DRIVER_VERSION: The driver version (type: utf8).
  * @GADBC_INFO_DRIVER_ARROW_VERSION: The driver Arrow library version
  *   (type: utf8).
+ * @GADBC_INFO_DRIVER_ADBC_VERSION: The driver ADBC version
+ *   (type: int64).
  *
  * The information code that is used by gadbc_connection_get_info().
  *
@@ -49,6 +69,7 @@ typedef enum {
   GADBC_INFO_DRIVER_NAME = 100,
   GADBC_INFO_DRIVER_VERSION = 101,
   GADBC_INFO_DRIVER_ARROW_VERSION = 102,
+  GADBC_INFO_DRIVER_ADBC_VERSION = 103,
 } GADBCInfo;
 
 /**
@@ -76,6 +97,53 @@ typedef enum {
   GADBC_OBJECT_DEPTH_TABLES = 3,
 } GADBCObjectDepth;
 
+/**
+ * GADBCStatisticKey:
+ * @GADBC_STATISTICS_KEY_AVERAGE_BYTE_WIDTH: The average byte
+ *   width statistic. The average size in bytes of a row in the
+ *   column. Value type is float64.
+ *   For example, this is roughly the average length of a string for a
+ *   string column.Return metadata on catalogs, schemas, tables, and
+ *   columns.
+ * @GADBC_STATISTICS_KEY_DISTINCT_COUNT: The distinct value count
+ *   (NDV) statistic. The number of distinct values in the column.
+ *   Value type is int64 (when not approximate) or float64 (when
+ *   approximate).
+ * @GADBC_STATISTICS_KEY_MAX_BYTE_WIDTH: The max byte width statistic.
+ *   The maximum size in bytes of a row in the column. Value type is
+ *   int64 (when not approximate) or float64 (when approximate).
+ *   For example, this is the maximum length of a string for a string
+ *   column.
+ * @GADBC_STATISTICS_KEY_MAX_VALUE: The max value statistic. Value
+ *   type is column-dependent.
+ * @GADBC_STATISTICS_KEY_MIN_VALUE: The min value statistic. Value
+ *   type is column-dependent.
+ * @GADBC_STATISTICS_KEY_NULL_COUNT: The null count statistic. The
+ *   number of values that are null in the column. Value type is
+ *   int64 (when not approximate) or float64 (when approximate).
+ * @GADBC_STATISTICS_KEY_ROW_COUNT: The row count statistic. The
+ *   number of rows in the column or table.  Value type is int64 (when
+ *   not approximate) or float64 (when approximate).
+ *
+ * Standard statistic names for gadbc_connection_get_statistics().
+ *
+ * They are corresponding to `ADBC_STATISTIC_*_KEY` values in `adbc.h`.
+ *
+ * Since: 1.0.0
+ */
+typedef enum {
+  GADBC_STATISTIC_KEY_AVERAGE_BYTE_WIDTH = 0,
+  GADBC_STATISTIC_KEY_DISTINCT_COUNT = 1,
+  GADBC_STATISTIC_KEY_MAX_BYTE_WIDTH = 2,
+  GADBC_STATISTIC_KEY_MAX_VALUE = 3,
+  GADBC_STATISTIC_KEY_MIN_VALUE = 4,
+  GADBC_STATISTIC_KEY_NULL_COUNT = 5,
+  GADBC_STATISTIC_KEY_ROW_COUNT = 6,
+} GADBCStatisticKey;
+
+GADBC_AVAILABLE_IN_1_0
+const gchar* gadbc_statistic_key_to_string(GADBCStatisticKey key);
+
 /**
  * GADBCIsolationLevel:
  * @GADBC_ISOLATION_LEVEL_DEFAULT: Use database or driver default
@@ -179,6 +247,11 @@ gpointer gadbc_connection_get_table_schema(GADBCConnection* connection,
                                            const gchar* table_name, GError** error);
 GADBC_AVAILABLE_IN_0_4
 gpointer gadbc_connection_get_table_types(GADBCConnection* connection, GError** error);
+GADBC_AVAILABLE_IN_1_0
+gpointer gadbc_connection_get_statistics(GADBCConnection* connection,
+                                         const gchar* catalog, const gchar* db_schema,
+                                         const gchar* table_name, gboolean approximate,
+                                         GError** error);
 GADBC_AVAILABLE_IN_0_4
 gboolean gadbc_connection_commit(GADBCConnection* connection, GError** error);
 GADBC_AVAILABLE_IN_0_4

glib/adbc-glib/meson.build

@@ -31,6 +31,16 @@ definition_headers = files(
   'statement.h',
 )
 
+version_h_conf = configuration_data()
+version_h_conf.set('GADBC_VERSION', meson.project_version())
+version_h_conf.set('GADBC_VERSION_MAJOR', version_major)
+version_h_conf.set('GADBC_VERSION_MINOR', version_minor)
+version_h_conf.set('GADBC_VERSION_MICRO', version_micro)
+version_h = configure_file(input: 'version.h.in',
+                           output: 'version.h',
+                           configuration: version_h_conf)
+definition_headers += version_h
+
 headers = definition_headers
 headers += files(
   'adbc-glib-raw.h',
@@ -41,16 +51,6 @@ headers += files(
   'statement-raw.h',
 )
 
-version_h_conf = configuration_data()
-version_h_conf.set('GADBC_VERSION', meson.project_version())
-version_h_conf.set('GADBC_VERSION_MAJOR', version_major)
-version_h_conf.set('GADBC_VERSION_MINOR', version_minor)
-version_h_conf.set('GADBC_VERSION_MICRO', version_micro)
-version_h = configure_file(input: 'version.h.in',
-                           output: 'version.h',
-                           configuration: version_h_conf)
-headers += version_h
-
 enums = gnome.mkenums_simple('enum-types',
                              identifier_prefix: 'GADBC',
                              sources: definition_headers,

glib/adbc-glib/version.h.in

@@ -100,6 +100,15 @@
 #  define GADBC_UNAVAILABLE(major, minor) G_UNAVAILABLE(major, minor)
 #endif
 
+/**
+ * GADBC_VERSION_1_0:
+ *
+ * You can use this macro value for compile time API version check.
+ *
+ * Since: 1.0.0
+ */
+#define GADBC_VERSION_1_0 G_ENCODE_VERSION(1, 0)
+
 /**
  * GADBC_VERSION_0_10:
  *
@@ -174,6 +183,20 @@
 
 #define GADBC_AVAILABLE_IN_ALL
 
+#if GADBC_VERSION_MIN_REQUIRED >= GADBC_VERSION_1_0
+#  define GADBC_DEPRECATED_IN_1_0                GADBC_DEPRECATED
+#  define GADBC_DEPRECATED_IN_1_0_FOR(function)  GADBC_DEPRECATED_FOR(function)
+#else
+#  define GADBC_DEPRECATED_IN_1_0
+#  define GADBC_DEPRECATED_IN_1_0_FOR(function)
+#endif
+
+#if GADBC_VERSION_MAX_ALLOWED < GADBC_VERSION_1_0
+#  define GADBC_AVAILABLE_IN_1_0 GADBC_UNAVAILABLE(1, 0)
+#else
+#  define GADBC_AVAILABLE_IN_1_0
+#endif
+
 #if GADBC_VERSION_MIN_REQUIRED >= GADBC_VERSION_0_10
 #  define GADBC_DEPRECATED_IN_0_10                GADBC_DEPRECATED
 #  define GADBC_DEPRECATED_IN_0_10_FOR(function)  GADBC_DEPRECATED_FOR(function)

glib/test/helper.rb

@@ -28,18 +28,28 @@ def require_gi_bindings(major, minor, micro)
     omit(message)
   end
 
+  def import_array_stream(c_abi_array_stream)
+    begin
+      reader = Arrow::RecordBatchReader.import(c_abi_array_stream)
+      begin
+        yield(reader)
+      ensure
+        reader.unref
+      end
+    ensure
+      GLib.free(c_abi_array_stream)
+    end
+  end
+
   def execute_statement(statement, need_result: true)
     _, c_abi_array_stream, n_rows_affected = statement.execute(need_result)
-    begin
-      if need_result
-        reader = Arrow::RecordBatchReader.import(c_abi_array_stream)
+    if need_result
+      import_array_stream(c_abi_array_stream) do |reader|
         table = reader.read_all
         yield(table, n_rows_affected) if block_given?
-      else
-        yield(n_rows_affected) if block_given?
       end
-    ensure
-      GLib.free(c_abi_array_stream) if need_result
+    else
+      yield(n_rows_affected) if block_given?
     end
   end