feat(csharp): Initial changes for ADBC 1.1 in C# implementation (apac…

…he#1821)

This adds all the basic elements defined since the initial ADBC 1.0
specification. There's still a bunch of cleanup likely to be required,
including support for exporting an ADBC 1.1 driver. There's also no test
coverage (boo! hiss!) as the DuckDB driver does not yet implement any
1.1 features and some ci infrastructure work is probably needed to
support other drivers.

Closes apache#1215

csharp/README.md

@@ -20,9 +20,3 @@
 # Apache Arrow ADBC
 
 An implementation of Arrow ADBC targeting .NET Standard 2.0 and .NET 6 or later.
-
-# Arrow Submodule
-
-This library uses the Arrow C Data API that is published in the [Arrow repo](https://github.com/apache/arrow/).
-
-This change has not been published to NuGet, so a submodule is currently used to obtain the Arrow project. Be sure to download the submodule so the solution loads and correctly.

csharp/src/Apache.Arrow.Adbc/AdbcConnection.cs

@@ -47,17 +47,26 @@ public virtual void Commit()
         /// <summary>
         /// Create a new statement to bulk insert into a table.
         /// </summary>
-        /// <param name="targetTableName">
-        /// The table name
-        /// </param>
-        /// <param name="mode">
-        /// The ingest mode
-        /// </param>
+        /// <param name="targetTableName">The table name</param>
+        /// <param name="mode">The ingest mode</param>
         public virtual AdbcStatement BulkIngest(string targetTableName, BulkIngestMode mode)
         {
             throw AdbcException.NotImplemented("Connection does not support BulkIngest");
         }
 
+        /// <summary>
+        /// Create a new statement to bulk insert into a table.
+        /// </summary>
+        /// <param name="targetCatalog">The catalog name, or null to use the current catalog</param>
+        /// <param name="targetDbSchema">The schema name, or null to use the current schema</param>
+        /// <param name="targetTableName">The table name</param>
+        /// <param name="mode">The ingest mode</param>
+        /// <param name="isTemporary">True for a temporary table. Catalog and Schema must be null when true.</param>
+        public virtual AdbcStatement BulkIngest(string? targetCatalog, string? targetDbSchema, string targetTableName, BulkIngestMode mode, bool isTemporary)
+        {
+            throw AdbcException.NotImplemented("Connection does not support BulkIngest");
+        }
+
         public virtual void Dispose()
         {
         }
@@ -220,5 +229,41 @@ public virtual IsolationLevel IsolationLevel
             get => _isolationLevel;
             set => throw AdbcException.NotImplemented("Connection does not support setting isolation level");
         }
+
+        /// <summary>
+        /// Attempts to cancel an in-progress operation on a connection.
+        /// </summary>
+        /// <remarks>
+        /// This can be called during a method like GetObjects or while consuming an ArrowArrayStream
+        /// returned from such. Calling this function should make the other function throw a cancellation exception.
+        ///
+        /// This must always be thread-safe.
+        /// </remarks>
+        public virtual void Cancel()
+        {
+            throw AdbcException.NotImplemented("Connection does not support cancellation");
+        }
+
+        /// <summary>
+        /// Gets the names of statistics specific to this driver.
+        /// </summary>
+        /// <returns></returns>
+        public virtual IArrowArrayStream GetStatisticsNames()
+        {
+            throw AdbcException.NotImplemented("Connection does not support statistics");
+        }
+
+        /// <summary>
+        /// Gets statistics about the data distribution of table(s)
+        /// </summary>
+        /// <param name="catalogPattern">The catalog or null. May be a search pattern.</param>
+        /// <param name="schemaPattern">The schema or null. May be a search pattern.</param>
+        /// <param name="tableName">The table name or null. May be a search pattern.</param>
+        /// <param name="approximate">If false, consumer desires exact statistics regardless of cost</param>
+        /// <returns>A result describing the statistics for the table(s)</returns>
+        public virtual IArrowArrayStream GetStatistics(string? catalogPattern, string? schemaPattern, string tableNamePattern, bool approximate)
+        {
+            throw AdbcException.NotImplemented("Connection does not support statistics");
+        }
     }
 }

csharp/src/Apache.Arrow.Adbc/AdbcDatabase.cs

@@ -40,6 +40,17 @@ public virtual void SetOption(string key, string value)
             throw AdbcException.NotImplemented("Connection does not support setting options");
         }
 
+        /// <summary>
+        /// Options are generally set before opening a database.  Some drivers may
+        /// support setting options after opening as well.
+        /// </summary>
+        /// <param name="key">Option name</param>
+        /// <param name="value">Option value</param>
+        public virtual void SetOption(string key, object value)
+        {
+            throw AdbcException.NotImplemented("Connection does not support setting options");
+        }
+
         /// <summary>
         /// Create a new connection to the database.
         /// </summary>

csharp/src/Apache.Arrow.Adbc/AdbcDriver.cs

@@ -26,6 +26,8 @@ namespace Apache.Arrow.Adbc
     /// </summary>
     public abstract class AdbcDriver : IDisposable
     {
+        public virtual int DriverVersion => AdbcVersion.Version_1_0_0;
+
         /// <summary>
         /// Open a database via this driver.
         /// </summary>
@@ -34,6 +36,17 @@ public abstract class AdbcDriver : IDisposable
         /// </param>
         public abstract AdbcDatabase Open(IReadOnlyDictionary<string, string> parameters);
 
+        /// <summary>
+        /// Open a database via this driver.
+        /// </summary>
+        /// <param name="parameters">
+        /// Driver-specific parameters.
+        /// </param>
+        public virtual AdbcDatabase Open(IReadOnlyDictionary<string, object> parameters)
+        {
+            throw AdbcException.NotImplemented("Driver does not support non-string parameters");
+        }
+
         public virtual void Dispose()
         {
         }

csharp/src/Apache.Arrow.Adbc/AdbcInfoCode.cs

@@ -23,33 +23,63 @@ namespace Apache.Arrow.Adbc
     public enum AdbcInfoCode
     {
         /// <summary>
-        /// The database vendor/product name (e.g. the server name).
+        /// The database vendor/product name (e.g. the server name). Type: string.
         /// </summary>
         VendorName = 0,
 
         /// <summary>
-        /// The database vendor/product version
+        /// The database vendor/product version. Type: string.
         /// </summary>
         VendorVersion = 1,
 
         /// <summary>
-        /// The database vendor/product Arrow library version
+        /// The database vendor/product Arrow library version. Type: string.
         /// </summary>
         VendorArrowVersion = 2,
 
         /// <summary>
-        /// The driver name
+        /// Whether or not SQL queries are supported. Type: bool.
+        /// </summary>
+        VendorSql = 3,
+
+        /// <summary>
+        /// Whether or not Substrait queries are supported. Type: bool.
+        /// </summary>
+        VendorSubstrait = 4,
+
+        /// <summary>
+        /// The minimum supported Substrait version, or null if not supported. Type: string.
+        /// </summary>
+        VendorSubstraitMinVersion = 5,
+
+        /// <summary>
+        /// The maximum supported Substrait version, or null if not supported. Type: string.
+        /// </summary>
+        VendorSubstraitMaxVersion = 6,
+
+        /// <summary>
+        /// The driver name. Type: string.
         /// </summary>
         DriverName = 100,
 
         /// <summary>
-        /// The driver version
+        /// The driver version. Type: string.
         /// </summary>
         DriverVersion = 101,
 
         /// <summary>
-        /// The driver Arrow library version
+        /// The driver Arrow library version. Type: string.
+        /// </summary>
+        DriverArrowVersion = 102,
+
+        /// <summary>
+        /// The driver ADBC API version. Type: int64.
         /// </summary>
-        DriverArrowVersion = 102
+        /// <remarks>
+        /// The value should be one of the ADBC_VERSION...
+        ///
+        /// Added in ADBC 1.1.0.
+        /// </remarks>
+        DriverAdbcVersion = 103,
     }
 }