This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new a43d084 docs: add status page/feature matrix (#412)
a43d084 is described below
commit a43d084766b696acb7b4474b2dcd182067a765ce
Author: David Li <[email protected]>
AuthorDate: Mon Feb 6 09:23:58 2023 -0500
docs: add status page/feature matrix (#412)
Fixes #408.
---------
Co-authored-by: Sutou Kouhei <[email protected]>
---
docs/source/driver/cpp/index.rst | 3 -
.../driver/{cpp/features.rst => go/index.rst} | 40 ++--
docs/source/driver/status.rst | 214 +++++++++++++++++++++
docs/source/format/specification.rst | 2 +
docs/source/index.rst | 2 +
5 files changed, 230 insertions(+), 31 deletions(-)
diff --git a/docs/source/driver/cpp/index.rst b/docs/source/driver/cpp/index.rst
index 6a049a8..0c411a0 100644
--- a/docs/source/driver/cpp/index.rst
+++ b/docs/source/driver/cpp/index.rst
@@ -23,12 +23,9 @@ C/C++/Python
:maxdepth: 1
:caption: Drivers
- flight_sql
postgresql
sqlite
- features
-
The ADBC project ships some drivers. Others may (eventually) be
available from database vendors or third parties. The drivers here
implement the C API standard and are directly usable in C/C++. They
diff --git a/docs/source/driver/cpp/features.rst
b/docs/source/driver/go/index.rst
similarity index 54%
rename from docs/source/driver/cpp/features.rst
rename to docs/source/driver/go/index.rst
index 51406fe..76578a7 100644
--- a/docs/source/driver/cpp/features.rst
+++ b/docs/source/driver/go/index.rst
@@ -15,34 +15,18 @@
.. specific language governing permissions and limitations
.. under the License.
-======================
-Feature Support Matrix
-======================
+==
+Go
+==
-.. list-table:: ADBC Feature Support
- :header-rows: 1
+.. toctree::
+ :maxdepth: 1
+ :caption: Drivers
- * - Driver
- - Bulk Ingestion
- - Metadata
- - Partitioned Result Sets
- - Prepared Statements
- - Transactions
+ flight_sql
- * - SQLite
- - Yes
- - Yes
- - No
- - Yes
- - Yes
-
-Bulk Ingestion
- Creating or appending to a database table from an Arrow table.
-
-Metadata
- Functions like :cpp:func:`AdbcConnectionGetObjects` that get
- metadata about the database catalog, etc.
-
-Partitioned Result Sets
- Being able to read individual chunks of a (generally distributed)
- result set (:cpp:func:`AdbcStatementExecutePartitions`).
+The ADBC project ships some drivers. Others may (eventually) be
+available from database vendors or third parties. The drivers here
+implement the Go API standard and are directly usable in Go. They
+also provide bindings that let them be used through the C API
+standard, as well as Python bindings on top of that.
diff --git a/docs/source/driver/status.rst b/docs/source/driver/status.rst
new file mode 100644
index 0000000..58fbd57
--- /dev/null
+++ b/docs/source/driver/status.rst
@@ -0,0 +1,214 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing,
+.. software distributed under the License is distributed on an
+.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+.. KIND, either express or implied. See the License for the
+.. specific language governing permissions and limitations
+.. under the License.
+
+============================================
+Driver Feature Support/Implementation Status
+============================================
+
+Implementation Status
+=====================
+
+**Experimental** drivers are not feature-complete and the implementation is
still progressing.
+**Beta** drivers are (mostly) feature-complete but have only been available
for a short time.
+**Stable** drivers are feature-complete (as much as possible for the
underlying database) and have been available/tested for a while.
+
+.. list-table::
+ :header-rows: 1
+
+ * - Driver
+ - Supported Languages [#supported-languages]_
+ - Implementation Language
+ - Status
+
+ * - Flight SQL (Go)
+ - C, Go
+ - Go
+ - Beta
+
+ * - Flight SQL (Java)
+ - Java
+ - Java
+ - Experimental
+
+ * - JDBC
+ - Java
+ - Java
+ - Experimental
+
+ * - PostgreSQL
+ - C
+ - C++
+ - Experimental
+
+ * - SQLite
+ - C
+ - C
+ - Beta
+
+.. [#supported-languages] C drivers are usable from Go, Python, and Ruby as
well.
+
+Feature Support
+===============
+
+N/A indicates that it is not possible to support this feature in the
underlying database.
+
+See individual driver documentation pages for full details.
+
+Bulk Ingestion
+ Does the driver support :ref:`bulk ingestion of data
<specification-bulk-ingestion>` (creating or appending to a database table from
an Arrow table)?
+
+Database Metadata
+ Does the driver support functions like
:cpp:func:`AdbcConnectionGetObjects` that get metadata about the database
catalog, etc.?
+
+Parameterized Queries
+ Does the driver support binding query parameters?
+
+Partitioned Data
+ Being able to read individual chunks of a (generally distributed)
+ result set (:cpp:func:`AdbcStatementExecutePartitions`).
+
+Prepared Statements
+ Does the driver support binding query parameters?
+
+Full Type Support
+ Does the driver map all database types to/from equivalent Arrow types, as
much as is possible?
+
+Select Queries
+ Does the driver support queries returning result sets?
+
+SQL
+ Does the driver support submitting SQL queries?
+
+Transactions
+ Does the driver support explicit transactions (the default is to assume
auto-commit)?
+
+Substrait
+ Does the driver support submitting Substrait plans?
+
+Update Queries
+ Does the driver support queries not returning result sets?
+
+.. list-table:: General features
+ :header-rows: 1
+
+ * - Driver
+ - Full Type Support
+ - SQL
+ - Substrait
+
+ * - Flight SQL (Go)
+ - Y
+ - Y
+ - N
+
+ * - Flight SQL (Java)
+ - Y
+ - Y
+ - N
+
+ * - JDBC
+ - N
+ - Y
+ - N/A
+
+ * - PostgreSQL
+ - N
+ - Y
+ - N/A
+
+ * - SQLite
+ - Y
+ - Y
+ - N/A
+
+.. list-table:: Statement/query-level features
+ :header-rows: 1
+
+ * - Driver
+ - Partitioned Data
+ - Parameterized Queries
+ - Prepared Statements
+ - Select Queries
+ - Update Queries
+
+ * - Flight SQL (Go)
+ - Y
+ - Y
+ - Y
+ - Y
+ - Y
+
+ * - Flight SQL (Java)
+ - Y
+ - Y
+ - Y
+ - Y
+ - Y
+
+ * - JDBC
+ - N/A
+ - Y
+ - Y
+ - Y
+ - Y
+
+ * - PostgreSQL
+ - Y
+ - Y
+ - Y
+ - N/A
+ - Y
+
+ * - SQLite
+ - N/A
+ - Y
+ - Y
+ - Y
+ - Y
+
+.. list-table:: Connection/database-level features
+ :header-rows: 1
+
+ * - Driver
+ - Bulk Ingestion
+ - Database Metadata (catalogs, etc.)
+ - Transactions
+
+ * - Flight SQL (Go)
+ - N
+ - Y
+ - N
+
+ * - Flight SQL (Java)
+ - Y
+ - Y
+ - N
+
+ * - JDBC
+ - Y
+ - Y
+ - N
+
+ * - PostgreSQL
+ - Y
+ - Y
+ - N
+
+ * - SQLite
+ - Y
+ - Y
+ - Y
diff --git a/docs/source/format/specification.rst
b/docs/source/format/specification.rst
index c0054b1..606ba69 100644
--- a/docs/source/format/specification.rst
+++ b/docs/source/format/specification.rst
@@ -69,6 +69,8 @@ doing so will invalidate prior result sets from that
statement. (See
- Go: ``Statement``
- Java: ``org.apache.arrow.adbc.core.AdbcStatement``
+.. _specification-bulk-ingestion:
+
Bulk Ingestion
--------------
diff --git a/docs/source/index.rst b/docs/source/index.rst
index c044ed6..bc696c1 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -46,7 +46,9 @@ Arrow-native database protocols.
:caption: Drivers
driver/installation
+ driver/status
driver/cpp/index
+ driver/go/index
driver/java/index
.. toctree::
