From 81fe935887ebfe70759eea6c1bd3d8f629c08781 Mon Sep 17 00:00:00 2001 From: David Li Date: Fri, 22 Mar 2024 11:30:36 -0400 Subject: [PATCH] docs: add glossary terms for statement/connection/database (#1654) Fixes #1652. --- docs/source/cpp/recipe/quickstart.cc | 10 +++++----- docs/source/glossary.rst | 14 ++++++++++++++ 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/docs/source/cpp/recipe/quickstart.cc b/docs/source/cpp/recipe/quickstart.cc index 555707a589..c1e68565ef 100644 --- a/docs/source/cpp/recipe/quickstart.cc +++ b/docs/source/cpp/recipe/quickstart.cc @@ -116,11 +116,11 @@ int main() { /// Creating a Connection /// --------------------- /// - /// ADBC distinguishes between "databases", "connections", and - /// "statements". A "database" holds shared state across multiple - /// connections. For example, in the SQLite driver, it holds the - /// actual instance of SQLite. A "connection" is one connection to - /// the database. + /// ADBC distinguishes between ":term:`databases `", + /// ":term:`connections `", and ":term:`statements + /// `". A "database" holds shared state across multiple + /// connections. For example, in the SQLite driver, it holds the actual + /// instance of SQLite. A "connection" is one connection to the database. AdbcConnection connection = {}; CHECK_ADBC(AdbcConnectionNew(&connection, &error)); diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst index 158dc38aa8..0f57675ef8 100644 --- a/docs/source/glossary.rst +++ b/docs/source/glossary.rst @@ -30,6 +30,14 @@ Glossary abstract over the underlying :term:`wire protocol` and other details. For example, ADBC, JDBC, ODBC. + connection + In ADBC, the connection object/struct represents a single connection to a + database. Multiple connections may be created from one :term:`database`. + + database + In ADBC, the database object/struct holds state that is shared across + connections. + driver Loosely speaking, a library that implements a :term:`client API` using a :term:`wire protocol`. For example, the ADBC PostgreSQL driver exposes @@ -48,6 +56,12 @@ Glossary would collide otherwise.) In Python, it loads drivers and provides Python bindings on top. + statement + In ADBC, the statement object/struct holds state for executing a single + query. The query itself, bind parameters, result sets, and so on are all + tied to the statement. Multiple statements may be created from one + :term:`connection` (though not all drivers will support this). + Substrait `Substrait`_ describes itself as a "cross-language serialization for relational algebra". It operates in a similar space as SQL, but is