From 0df5841317b7079999f02ce7cf1158f0dcf6049e Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 7 Feb 2024 12:58:25 -0500 Subject: [PATCH] docs: expand glossary (#1524) Fixes #1429. --- docs/source/faq.rst | 4 +--- docs/source/glossary.rst | 33 +++++++++++++++++++++++---------- 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 43bc889b96..9e315be0c6 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -155,9 +155,7 @@ result set as Arrow data. In that respect, it's like JDBC. (ODBC has a "standard" SQL dialect it defines; ADBC does not do this.) For a project that does try to tackle the problem of defining a -vendor-independent query language, see Substrait_. - -.. _Substrait: https://substrait.io/ +vendor-independent query language, see :term:`Substrait`. When is the next release? ========================= diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index f54c63b290..158dc38aa8 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -21,17 +21,21 @@ Glossary .. glossary:: + Arrow Flight SQL + A :term:`wire protocol` for data systems that uses Apache Arrow. + See the :external:doc:`specification `. + client API The API that an application uses to interact with a database. May abstract over the underlying :term:`wire protocol` and other details. For example, ADBC, JDBC, ODBC. driver - A library that implements a :term:`client API` using a :term:`wire - protocol`. For example, the ADBC PostgreSQL driver exposes the ADBC - client API and interacts with a PostgreSQL database via the PostgreSQL - wire protocol. The JDBC PostgreSQL driver uses the same wire protocol, - but exposes the JDBC client API instead. + Loosely speaking, a library that implements a :term:`client API` using a + :term:`wire protocol`. For example, the ADBC PostgreSQL driver exposes + the ADBC client API and interacts with a PostgreSQL database via the + PostgreSQL wire protocol. The JDBC PostgreSQL driver uses the same wire + protocol, but exposes the JDBC client API instead. driver manager A library that helps manage multiple drivers for a given client API. @@ -44,12 +48,21 @@ Glossary would collide otherwise.) In Python, it loads drivers and provides Python bindings on top. + Substrait + `Substrait`_ describes itself as a "cross-language serialization for + relational algebra". It operates in a similar space as SQL, but is + lower-level. You're unlikely to write a Substrait query by hand, but may + use tools that opt to generate Substrait instead of SQL for more + predictable semantics. + wire protocol - The protocol that a database driver uses to interact with a database. - For example, :external:doc:`format/FlightSql`, the `PostgreSQL wire - protocol`_, or `Tabular Data Stream`_ (Microsoft SQL Server). Generally - not directly used by an application. + The actual way a database driver connects to a database, issues commands, + gets results, and so forth. For example, :term:`Arrow Flight SQL`, the + `PostgreSQL wire protocol`_, or `Tabular Data Stream`_ (Microsoft SQL + Server). Generally, an application is not going to implement and use this + directly, but instead use something higher-level, like an ADBC, JDBC, or + ODBC driver. -.. _Arrow Flight SQL: https://arrow.apache.org/docs/format/FlightSql.html .. _PostgreSQL wire protocol: https://www.postgresql.org/docs/current/protocol.html +.. _Substrait: https://substrait.io/ .. _Tabular Data Stream: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-tds/b46a581a-39de-4745-b076-ec4dbb7d13ec