You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by li...@apache.org on 2023/06/08 14:25:46 UTC
[arrow-adbc] branch main updated: docs: add basic state diagram for AdbcStatement (#739)
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 7f2bf797 docs: add basic state diagram for AdbcStatement (#739)
7f2bf797 is described below
commit 7f2bf79734d66f4993e5a0572b70a3168a0aea37
Author: David Li <li...@gmail.com>
AuthorDate: Thu Jun 8 10:25:40 2023 -0400
docs: add basic state diagram for AdbcStatement (#739)
Fixes #737.
---
ci/conda_env_docs.txt | 2 +
dev/release/rat_exclude_files.txt | 2 +
docs/source/_static/css/custom.css | 6 +
docs/source/conf.py | 5 +
docs/source/driver/go/index.rst | 1 +
docs/source/driver/go/snowflake.rst | 7 +-
docs/source/format/AdbcStatement.drawio | 173 +++++++++++++++++++++
docs/source/format/AdbcStatement.svg | 4 +
docs/source/format/AdbcStatementBasicUsage.mmd | 32 ++++
docs/source/format/AdbcStatementBulkIngest.mmd | 26 ++++
.../format/AdbcStatementConsumeResultSet.mmd | 27 ++++
docs/source/format/AdbcStatementPartitioned.mmd | 44 ++++++
docs/source/format/AdbcStatementUpdate.mmd | 31 ++++
docs/source/format/specification.rst | 39 +++++
14 files changed, 396 insertions(+), 3 deletions(-)
diff --git a/ci/conda_env_docs.txt b/ci/conda_env_docs.txt
index 04ee3a5a..2443ff8f 100644
--- a/ci/conda_env_docs.txt
+++ b/ci/conda_env_docs.txt
@@ -21,5 +21,7 @@ furo
make
numpydoc
sphinx>=5.0
+sphinx-autobuild
sphinx-copybutton
sphinx-design
+sphinxcontrib-mermaid
diff --git a/dev/release/rat_exclude_files.txt b/dev/release/rat_exclude_files.txt
index f5e56d86..3088f925 100644
--- a/dev/release/rat_exclude_files.txt
+++ b/dev/release/rat_exclude_files.txt
@@ -4,6 +4,8 @@ ci/conda/.gitattributes
ci/linux-packages/changelog
ci/linux-packages/*.install
dev/release/rat_exclude_files.txt
+docs/source/format/*.drawio
+docs/source/format/*.svg
filtered_rat.txt
go/adbc/drivermgr/adbc.h
go/adbc/drivermgr/adbc_driver_manager.cc
diff --git a/docs/source/_static/css/custom.css b/docs/source/_static/css/custom.css
index 543a9562..e463f97f 100644
--- a/docs/source/_static/css/custom.css
+++ b/docs/source/_static/css/custom.css
@@ -18,3 +18,9 @@
p.admonition-title {
font-weight: bold;
}
+
+/* Center Mermaid diagrams */
+.mermaid svg {
+ display: block;
+ margin: 0 auto;
+}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 6b269369..d0d7ff9f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -37,6 +37,7 @@ extensions = [
"sphinx.ext.intersphinx",
"sphinx_copybutton",
"sphinx_design",
+ "sphinxcontrib.mermaid",
]
templates_path = ["_templates"]
@@ -101,6 +102,10 @@ intersphinx_mapping = {
"arrow": ("https://arrow.apache.org/docs/", None),
}
+# -- Options for mermaid -----------------------------------------------------
+
+mermaid_d3_zoom = True
+
# -- Options for numpydoc ----------------------------------------------------
numpydoc_class_members_toctree = False
diff --git a/docs/source/driver/go/index.rst b/docs/source/driver/go/index.rst
index 76578a78..687c88a6 100644
--- a/docs/source/driver/go/index.rst
+++ b/docs/source/driver/go/index.rst
@@ -24,6 +24,7 @@ Go
:caption: Drivers
flight_sql
+ snowflake
The ADBC project ships some drivers. Others may (eventually) be
available from database vendors or third parties. The drivers here
diff --git a/docs/source/driver/go/snowflake.rst b/docs/source/driver/go/snowflake.rst
index 3a233b56..37514561 100644
--- a/docs/source/driver/go/snowflake.rst
+++ b/docs/source/driver/go/snowflake.rst
@@ -121,8 +121,9 @@ these are not set, the ``CREATE TEMPORARY STAGE`` command executed by the driver
can fail with the following error:
.. code-block::
- CREATE TEMPORARY STAGE SYSTEM$BIND file_format=(type=csv field_optionally_enclosed_by='"')
- CANNOT perform CREATE STAGE. This session does not have a current schema. Call 'USE SCHEMA' or use a qualified name.
+
+ CREATE TEMPORARY STAGE SYSTEM$BIND file_format=(type=csv field_optionally_enclosed_by='"')
+ CANNOT perform CREATE STAGE. This session does not have a current schema. Call 'USE SCHEMA' or use a qualified name.
In addition, results are potentially fetched in parallel from multiple endpoints.
A limited number of batches are queued per endpoint, though data is always
@@ -256,7 +257,7 @@ These options map 1:1 with the Snowflake `Config object <https://pkg.go.dev/gith
Metadata
--------
-When calling :cpp:`AdbcConnectionGetTableSchema`, the returned Arrow Schema
+When calling :cpp:func:`AdbcConnectionGetTableSchema`, the returned Arrow Schema
will contain metadata on each field:
``DATA_TYPE``
diff --git a/docs/source/format/AdbcStatement.drawio b/docs/source/format/AdbcStatement.drawio
new file mode 100644
index 00000000..83025b67
--- /dev/null
+++ b/docs/source/format/AdbcStatement.drawio
@@ -0,0 +1,173 @@
+<mxfile host="app.diagrams.net" modified="2023-06-07T16:32:34.078Z" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/113.0" etag="h3xegZ3pFjHo4aq3h5ot" version="21.3.7" type="device">
+ <diagram name="Page-1" id="TWkG7nH6AqZWR0qMdS5p">
+ <mxGraphModel dx="1381" dy="797" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="300" pageHeight="300" math="0" shadow="0">
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-4" target="vLVt9S_m-FuegXCIFqmu-6">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-9" value="<div>AdbcStatementNew</div>" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-8">
+ <mxGeometry x="-0.3878" y="-1" relative="1" as="geometry">
+ <mxPoint x="1" y="9" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-4" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#000000;" vertex="1" parent="1">
+ <mxGeometry x="290" y="70" width="20" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-38" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-6" target="vLVt9S_m-FuegXCIFqmu-37">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-39" value="AdbcStatementRelease" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-38">
+ <mxGeometry x="0.1837" y="-1" relative="1" as="geometry">
+ <mxPoint x="1" y="-1" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-6" value="" style="whiteSpace=wrap;html=1;fillColor=none;" vertex="1" parent="1">
+ <mxGeometry x="60" y="160" width="480" height="280" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-10" value="<div><b>AdbcStatement</b></div>" style="text;html=1;align=center;verticalAlign=middle;resizable=0;points=[];autosize=1;strokeColor=none;fillColor=none;" vertex="1" parent="1">
+ <mxGeometry x="100" y="160" width="110" height="30" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-19" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0.5;entryY=0;entryDx=0;entryDy=0;curved=1;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-12" target="vLVt9S_m-FuegXCIFqmu-15">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-24" value="SetOption" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-19">
+ <mxGeometry x="0.3506" y="-14" relative="1" as="geometry">
+ <mxPoint x="14" y="21" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-20" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;curved=1;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-12" target="vLVt9S_m-FuegXCIFqmu-13">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-23" value="SetSqlQuery" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-20">
+ <mxGeometry x="-0.2498" y="26" relative="1" as="geometry">
+ <mxPoint x="-28" y="34" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-12" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#000000;" vertex="1" parent="1">
+ <mxGeometry x="290" y="170" width="20" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-21" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=0.5;exitY=1;exitDx=0;exitDy=0;curved=1;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-13" target="vLVt9S_m-FuegXCIFqmu-16">
+ <mxGeometry relative="1" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-57" value="ExecuteQuery" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-21">
+ <mxGeometry x="-0.1482" y="8" relative="1" as="geometry">
+ <mxPoint x="32" y="-12" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-34" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;curved=1;entryX=0;entryY=0.5;entryDx=0;entryDy=0;exitX=-0.033;exitY=0.583;exitDx=0;exitDy=0;exitPerimeter=0;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-13" target="vLVt9S_m-FuegXCIFqmu-13">
+ <mxGeometry relative="1" as="geometry">
+ <mxPoint x="130" y="290" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="130" y="302" />
+ <mxPoint x="130" y="310" />
+ <mxPoint x="120" y="310" />
+ <mxPoint x="120" y="290" />
+ <mxPoint x="130" y="290" />
+ <mxPoint x="130" y="300" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-36" value="Bind" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-34">
+ <mxGeometry x="0.0343" relative="1" as="geometry">
+ <mxPoint x="-20" y="3" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-13" value="Query" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+ <mxGeometry x="140" y="290" width="80" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-49" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;curved=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-15" target="vLVt9S_m-FuegXCIFqmu-15">
+ <mxGeometry relative="1" as="geometry">
+ <mxPoint x="420" y="360" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="420" y="320" />
+ <mxPoint x="430" y="320" />
+ <mxPoint x="430" y="340" />
+ <mxPoint x="410" y="340" />
+ <mxPoint x="410" y="320" />
+ <mxPoint x="420" y="320" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-50" value="ExecuteUpdate" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-49">
+ <mxGeometry x="-0.073" relative="1" as="geometry">
+ <mxPoint x="-54" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-15" value="Ingest" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+ <mxGeometry x="380" y="290" width="80" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-53" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;curved=1;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-16">
+ <mxGeometry relative="1" as="geometry">
+ <mxPoint x="180" y="310" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="150" y="420" />
+ <mxPoint x="150" y="310" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-54" value="(consume stream)" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-53">
+ <mxGeometry x="-0.1377" y="-1" relative="1" as="geometry">
+ <mxPoint x="-31" y="-41" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-16" value="ArrowArrayStream" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+ <mxGeometry x="240" y="410" width="120" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-27" value="" style="endArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;edgeStyle=orthogonalEdgeStyle;curved=1;entryX=1;entryY=0.5;entryDx=0;entryDy=0;" edge="1" parent="1">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="460" y="300" as="sourcePoint" />
+ <mxPoint x="460" y="300" as="targetPoint" />
+ <Array as="points">
+ <mxPoint x="470" y="300" />
+ <mxPoint x="470" y="290" />
+ <mxPoint x="480" y="290" />
+ <mxPoint x="480" y="310" />
+ <mxPoint x="470" y="310" />
+ <mxPoint x="470" y="300" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-28" value="Bind" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-27">
+ <mxGeometry x="-0.0778" relative="1" as="geometry">
+ <mxPoint x="10" y="3" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-37" value="" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#e1d5e7;strokeColor=#000000;" vertex="1" parent="1">
+ <mxGeometry x="290" y="510" width="20" height="20" as="geometry" />
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-43" value="" style="endArrow=classic;startArrow=classic;html=1;rounded=0;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=-0.03;entryY=0.492;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" source="vLVt9S_m-FuegXCIFqmu-13" target="vLVt9S_m-FuegXCIFqmu-15">
+ <mxGeometry width="50" height="50" relative="1" as="geometry">
+ <mxPoint x="250" y="300" as="sourcePoint" />
+ <mxPoint x="300" y="250" as="targetPoint" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-44" value="SetSqlQuery<br>SetOption" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-43">
+ <mxGeometry x="0.073" relative="1" as="geometry">
+ <mxPoint x="-4" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-55" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;curved=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;" edge="1" parent="1">
+ <mxGeometry relative="1" as="geometry">
+ <mxPoint x="200" y="310" as="targetPoint" />
+ <mxPoint x="200" y="310" as="sourcePoint" />
+ <Array as="points">
+ <mxPoint x="200" y="320" />
+ <mxPoint x="210" y="320" />
+ <mxPoint x="210" y="340" />
+ <mxPoint x="190" y="340" />
+ <mxPoint x="190" y="320" />
+ <mxPoint x="200" y="320" />
+ </Array>
+ </mxGeometry>
+ </mxCell>
+ <mxCell id="vLVt9S_m-FuegXCIFqmu-56" value="ExecuteUpdate" style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="vLVt9S_m-FuegXCIFqmu-55">
+ <mxGeometry x="-0.073" relative="1" as="geometry">
+ <mxPoint x="46" y="-10" as="offset" />
+ </mxGeometry>
+ </mxCell>
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
diff --git a/docs/source/format/AdbcStatement.svg b/docs/source/format/AdbcStatement.svg
new file mode 100644
index 00000000..0a55f01a
--- /dev/null
+++ b/docs/source/format/AdbcStatement.svg
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than draw.io -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="482px" height="462px" viewBox="-0.5 -0.5 482 462" content="<mxfile host="app.diagrams.net" modified="2023-06-07T16:19:09.711Z" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/113.0" etag="_InTI2ZhffU8aoDexE-3" version="21.3.7" type="device">< [...]
diff --git a/docs/source/format/AdbcStatementBasicUsage.mmd b/docs/source/format/AdbcStatementBasicUsage.mmd
new file mode 100644
index 00000000..eb29fd76
--- /dev/null
+++ b/docs/source/format/AdbcStatementBasicUsage.mmd
@@ -0,0 +1,32 @@
+%% 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.
+
+sequenceDiagram
+ actor App
+ participant Driver as AdbcStatement
+ App ->> Driver: New
+ App ->> Driver: SetSqlQuery
+ App -->> Driver: Prepare
+ loop As many times as desired
+ App -->> Driver: GetParameterSchema
+ App -->> Driver: Bind
+ App ->> Driver: ExecuteQuery
+ Driver ->> App: ArrowArrayStream
+ App -> App: consume result set
+ end
+ Note over App, Driver: SetSqlQuery and repeat (if desired)
+ App ->> Driver: Release
diff --git a/docs/source/format/AdbcStatementBulkIngest.mmd b/docs/source/format/AdbcStatementBulkIngest.mmd
new file mode 100644
index 00000000..557c0123
--- /dev/null
+++ b/docs/source/format/AdbcStatementBulkIngest.mmd
@@ -0,0 +1,26 @@
+%% 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.
+
+sequenceDiagram
+ actor App
+ participant Driver as AdbcStatement
+ App ->> Driver: New
+ App ->> Driver: SetOption(ADBC_INGEST_OPTION_TARGET_TABLE)
+ App ->> Driver: GetParameterSchema
+ App ->> Driver: Bind
+ App ->> Driver: ExecuteUpdate
+ App ->> Driver: Release
diff --git a/docs/source/format/AdbcStatementConsumeResultSet.mmd b/docs/source/format/AdbcStatementConsumeResultSet.mmd
new file mode 100644
index 00000000..dfbac823
--- /dev/null
+++ b/docs/source/format/AdbcStatementConsumeResultSet.mmd
@@ -0,0 +1,27 @@
+%% 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.
+
+sequenceDiagram
+ actor App
+ participant Stream as ArrowArrayStream
+ App ->> Stream: get_schema
+ Stream ->> App: ArrowSchema
+ loop Until stream exhausted
+ App ->> Stream: get_next
+ Stream ->> App: ArrowArray
+ end
+ App ->> Stream: release
diff --git a/docs/source/format/AdbcStatementPartitioned.mmd b/docs/source/format/AdbcStatementPartitioned.mmd
new file mode 100644
index 00000000..cfa4e5c1
--- /dev/null
+++ b/docs/source/format/AdbcStatementPartitioned.mmd
@@ -0,0 +1,44 @@
+%% 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.
+
+sequenceDiagram
+ actor App
+ participant Driver as AdbcStatement
+ participant S1 as Server 1
+ participant S2 as Server 2
+
+ App ->> Driver: New
+ App ->> Driver: SetSqlQuery
+ App -->> Driver: Prepare
+ loop As many times as desired
+ App -->> Driver: GetParameterSchema
+ App -->> Driver: Bind
+ App ->> Driver: ExecutePartitions
+ Driver ->> App: AdbcPartitions
+ Note over App, S2: Consume the distributed result set
+ par Read from server 1
+ App ->> S1: ReadPartition
+ S1 ->> App: ArrowArrayStream
+ App -> App: consume result set
+ and Read from server 2
+ App ->> S2: ReadPartition
+ S2 ->> App: ArrowArrayStream
+ App -> App: consume result set
+ end
+ end
+ Note over App, Driver: SetSqlQuery and repeat (if desired)
+ App ->> Driver: Release
diff --git a/docs/source/format/AdbcStatementUpdate.mmd b/docs/source/format/AdbcStatementUpdate.mmd
new file mode 100644
index 00000000..700a63bf
--- /dev/null
+++ b/docs/source/format/AdbcStatementUpdate.mmd
@@ -0,0 +1,31 @@
+%% 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.
+
+sequenceDiagram
+ actor App
+ participant Driver as AdbcStatement
+ App ->> Driver: New
+ App ->> Driver: SetSqlQuery
+ App -->> Driver: Prepare
+ loop As many times as desired
+ App -->> Driver: GetParameterSchema
+ App -->> Driver: Bind
+ App ->> Driver: ExecuteUpdate
+ Driver ->> App: affected rows
+ end
+ Note over App, Driver: SetSqlQuery and repeat (if desired)
+ App ->> Driver: Release
diff --git a/docs/source/format/specification.rst b/docs/source/format/specification.rst
index 606ba69e..e7a44a41 100644
--- a/docs/source/format/specification.rst
+++ b/docs/source/format/specification.rst
@@ -96,3 +96,42 @@ machines.
- C/C++: :cpp:func:`AdbcStatementExecutePartitions`
- Go: ``Statement.ExecutePartitions``
- Java: ``org.apache.arrow.adbc.core.AdbcStatement#executePartitioned()``
+
+Lifecycle & Usage
+-----------------
+
+.. image:: AdbcStatement.svg
+ :alt: The lifecycle of a statement.
+ :width: 100%
+
+Basic Usage
+~~~~~~~~~~~
+
+.. mermaid:: AdbcStatementBasicUsage.mmd
+ :caption: Preparing the statement and binding parameters are optional.
+
+Consuming Result Sets
+~~~~~~~~~~~~~~~~~~~~~
+
+.. mermaid:: AdbcStatementConsumeResultSet.mmd
+ :caption: This is equivalent to reading from what many Arrow
+ libraries call a RecordBatchReader.
+
+Bulk Data Ingestion
+~~~~~~~~~~~~~~~~~~~
+
+.. mermaid:: AdbcStatementBulkIngest.mmd
+ :caption: There is no need to prepare the statement.
+
+Update-only Queries (No Result Set)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mermaid:: AdbcStatementUpdate.mmd
+ :caption: Preparing the statement and binding parameters are optional.
+
+Partitioned Execution
+~~~~~~~~~~~~~~~~~~~~~
+
+.. mermaid:: AdbcStatementPartitioned.mmd
+ :caption: This is similar to fetching data in Arrow Flight RPC (by
+ design). See :doc:`"Downloading Data" <arrow:format/Flight>`.