blob: dd0c592acd6fc08c3575e954068d18e83eb96028 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en" data-content_root="" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>ADBC: Arrow Database Connectivity &#8212; Apache Arrow v17.0.0.dev52</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
</script>
<!-- Loaded before other Sphinx assets -->
<link href="../_static/styles/theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/styles/bootstrap.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/styles/pydata-sphinx-theme.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link href="../_static/vendor/fontawesome/6.5.1/css/all.min.css?digest=8d27b9dea8ad943066ae" rel="stylesheet" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-solid-900.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-brands-400.woff2" />
<link rel="preload" as="font" type="font/woff2" crossorigin href="../_static/vendor/fontawesome/6.5.1/webfonts/fa-regular-400.woff2" />
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" />
<link rel="stylesheet" type="text/css" href="../_static/theme_overrides.css" />
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae" />
<link rel="preload" as="script" href="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae" />
<script src="../_static/vendor/fontawesome/6.5.1/js/all.min.js?digest=8d27b9dea8ad943066ae"></script>
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/sphinx_highlight.js"></script>
<script src="../_static/clipboard.min.js"></script>
<script src="../_static/copybutton.js"></script>
<script src="../_static/design-tabs.js"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'format/ADBC';</script>
<script>
DOCUMENTATION_OPTIONS.theme_version = '0.15.2';
DOCUMENTATION_OPTIONS.theme_switcher_json_url = '/docs/_static/versions.json';
DOCUMENTATION_OPTIONS.theme_switcher_version_match = 'dev/';
DOCUMENTATION_OPTIONS.show_version_warning_banner = true;
</script>
<link rel="canonical" href="https://arrow.apache.org/docs/format/ADBC.html" />
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="ADBC C API Specification" href="ADBC/C.html" />
<link rel="prev" title="Arrow Flight SQL" href="FlightSql.html" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="docsearch:language" content="en"/>
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
/* We explicitly disable cookie tracking to avoid privacy issues */
_paq.push(['disableCookies']);
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="https://analytics.apache.org/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '20']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
<!-- End Matomo Code -->
</head>
<body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" data-default-mode="">
<a id="pst-skip-link" class="skip-link" href="#main-content">Skip to main content</a>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>
Back to top
</button>
<input type="checkbox"
class="sidebar-toggle"
name="__primary"
id="__primary"/>
<label class="overlay overlay-primary" for="__primary"></label>
<input type="checkbox"
class="sidebar-toggle"
name="__secondary"
id="__secondary"/>
<label class="overlay overlay-secondary" for="__secondary"></label>
<div class="search-button__wrapper">
<div class="search-button__overlay"></div>
<div class="search-button__search-container">
<form class="bd-search d-flex align-items-center"
action="../search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
id="search-input"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form></div>
</div>
<header class="bd-header navbar navbar-expand-lg bd-navbar">
<div class="bd-header__inner bd-page-width">
<label class="sidebar-toggle primary-toggle" for="__primary">
<span class="fa-solid fa-bars"></span>
</label>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="../index.html">
<img src="../_static/arrow.png" class="logo__image only-light" alt="Apache Arrow v17.0.0.dev52 - Home"/>
<script>document.write(`<img src="../_static/arrow-dark.png" class="logo__image only-dark" alt="Apache Arrow v17.0.0.dev52 - Home"/>`);</script>
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Specifications
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../developers/index.html">
Development
</a>
</li>
<li class="nav-item dropdown">
<button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links">
Implementations
</button>
<ul id="pst-nav-more-links" class="dropdown-menu">
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html">
C/GLib
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../cpp/index.html">
C++
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md">
C#
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17">
Go
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../java/index.html">
Java
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../js/index.html">
JavaScript
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/">
Julia
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md">
MATLAB
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/">
nanoarrow
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../python/index.html">
Python
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../r/index.html">
R
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md">
Ruby
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/">
Rust
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../status.html">
Implementation Status
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/">
C++ cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/">
Java cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/">
Python cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/">
R cookbook
</a>
</li>
</ul>
</li>
</ul>
</nav></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<div class="navbar-item">
<script>
document.write(`
<div class="version-switcher__container dropdown">
<button id="pst-version-switcher-button-2"
type="button"
class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle"
data-bs-toggle="dropdown"
aria-haspopup="listbox"
aria-controls="pst-version-switcher-list-2"
aria-label="Version switcher list"
>
Choose version <!-- this text may get changed later by javascript -->
<span class="caret"></span>
</button>
<div id="pst-version-switcher-list-2"
class="version-switcher__menu dropdown-menu list-group-flush py-0"
role="listbox" aria-labelledby="pst-version-switcher-button-2">
<!-- dropdown will be populated by javascript on page load -->
</div>
</div>
`);
</script></div>
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">X</span></a>
</li>
</ul></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<script>
document.write(`
<button class="btn navbar-btn search-button-field search-button__button" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
`);
</script>
</div>
<label class="sidebar-toggle secondary-toggle" for="__secondary" tabindex="0">
<span class="fa-solid fa-outdent"></span>
</label>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<div class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item">
<nav class="navbar-nav">
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item current active">
<a class="nav-link nav-internal" href="index.html">
Specifications
</a>
</li>
<li class="nav-item">
<a class="nav-link nav-internal" href="../developers/index.html">
Development
</a>
</li>
<li class="nav-item dropdown">
<button class="btn dropdown-toggle nav-item" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-controls="pst-nav-more-links-2">
Implementations
</button>
<ul id="pst-nav-more-links-2" class="dropdown-menu">
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../c_glib/index.html">
C/GLib
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../cpp/index.html">
C++
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/csharp/README.md">
C#
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://pkg.go.dev/github.com/apache/arrow/go/v17">
Go
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../java/index.html">
Java
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../js/index.html">
JavaScript
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/julia/">
Julia
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/matlab/README.md">
MATLAB
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/nanoarrow/">
nanoarrow
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../python/index.html">
Python
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../r/index.html">
R
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://github.com/apache/arrow/blob/main/ruby/README.md">
Ruby
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://docs.rs/crate/arrow/">
Rust
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-internal" href="../status.html">
Implementation Status
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/cpp/">
C++ cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/java/">
Java cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/py/">
Python cookbook
</a>
</li>
<li class="nav-item">
<a class="nav-link dropdown-item nav-external" href="https://arrow.apache.org/cookbook/r/">
R cookbook
</a>
</li>
</ul>
</li>
</ul>
</nav></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<script>
document.write(`
<div class="version-switcher__container dropdown">
<button id="pst-version-switcher-button-3"
type="button"
class="version-switcher__button btn btn-sm navbar-btn dropdown-toggle"
data-bs-toggle="dropdown"
aria-haspopup="listbox"
aria-controls="pst-version-switcher-list-3"
aria-label="Version switcher list"
>
Choose version <!-- this text may get changed later by javascript -->
<span class="caret"></span>
</button>
<div id="pst-version-switcher-list-3"
class="version-switcher__menu dropdown-menu list-group-flush py-0"
role="listbox" aria-labelledby="pst-version-switcher-button-3">
<!-- dropdown will be populated by javascript on page load -->
</div>
</div>
`);
</script></div>
<div class="navbar-item">
<script>
document.write(`
<button class="btn btn-sm navbar-btn theme-switch-button" title="light/dark" aria-label="light/dark" data-bs-placement="bottom" data-bs-toggle="tooltip">
<span class="theme-switch nav-link" data-mode="light"><i class="fa-solid fa-sun fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="dark"><i class="fa-solid fa-moon fa-lg"></i></span>
<span class="theme-switch nav-link" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg"></i></span>
</button>
`);
</script></div>
<div class="navbar-item"><ul class="navbar-icon-links navbar-nav"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/apache/arrow" title="GitHub" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/ApacheArrow" title="X" class="nav-link" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><span><i class="fa-brands fa-square-x-twitter fa-lg" aria-hidden="true"></i></span>
<span class="sr-only">X</span></a>
</li>
</ul></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"><ul class="current nav bd-sidenav">
<li class="toctree-l1"><a class="reference internal" href="Versioning.html">Format Versioning and Stability</a></li>
<li class="toctree-l1"><a class="reference internal" href="Columnar.html">Arrow Columnar Format</a></li>
<li class="toctree-l1"><a class="reference internal" href="CanonicalExtensions.html">Canonical Extension Types</a></li>
<li class="toctree-l1"><a class="reference internal" href="Other.html">Other Data Structures</a></li>
<li class="toctree-l1 has-children"><a class="reference internal" href="CDataInterface.html">The Arrow C data interface</a><input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-1"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="CDataInterface/PyCapsuleInterface.html">The Arrow PyCapsule Interface</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="CStreamInterface.html">The Arrow C stream interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="CDeviceDataInterface.html">The Arrow C Device data interface</a></li>
<li class="toctree-l1"><a class="reference internal" href="Flight.html">Arrow Flight RPC</a></li>
<li class="toctree-l1"><a class="reference internal" href="FlightSql.html">Arrow Flight SQL</a></li>
<li class="toctree-l1 current active has-children"><a class="current reference internal" href="#">ADBC: Arrow Database Connectivity</a><input checked="" class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/><label class="toctree-toggle" for="toctree-checkbox-2"><i class="fa-solid fa-chevron-down"></i></label><ul>
<li class="toctree-l2"><a class="reference internal" href="ADBC/C.html">ADBC C API Specification</a></li>
<li class="toctree-l2"><a class="reference internal" href="ADBC/Go.html">ADBC Go API Specification</a></li>
<li class="toctree-l2"><a class="reference internal" href="ADBC/Java.html">ADBC Java API Specification</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Changing.html">Changing the Apache Arrow Format Specification</a></li>
<li class="toctree-l1"><a class="reference internal" href="Integration.html">Integration Testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="Glossary.html">Glossary</a></li>
</ul>
</div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
</div>
<div id="rtd-footer-container"></div>
</div>
<main id="main-content" class="bd-main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="../index.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item"><a href="index.html" class="nav-link">Specifications</a></li>
<li class="breadcrumb-item active" aria-current="page">ADBC: Arrow...</li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="adbc-arrow-database-connectivity">
<h1>ADBC: Arrow Database Connectivity<a class="headerlink" href="#adbc-arrow-database-connectivity" title="Permalink to this heading">#</a></h1>
<p>Full Documentation on ADBC can be found at <a class="reference external" href="https://arrow.apache.org/adbc/">https://arrow.apache.org/adbc/</a>.</p>
<section id="rationale">
<h2>Rationale<a class="headerlink" href="#rationale" title="Permalink to this heading">#</a></h2>
<p>The Arrow ecosystem lacks standard database interfaces built around
Arrow data, especially for efficiently fetching large datasets
(i.e. with minimal or no serialization and copying). Without a common
API, the end result is a mix of custom protocols (e.g. BigQuery,
Snowflake) and adapters (e.g. <a class="reference external" href="https://turbodbc.readthedocs.io/en/latest/">Turbodbc</a>) scattered across languages.
Consumers must laboriously wrap individual systems (as <a class="reference external" href="https://r-dbi.github.io/dbi3/articles/dbi3.html">DBI is
contemplating</a> and <a class="reference external" href="https://trino.io/docs/current/connector.html">Trino does with connectors</a>).</p>
<p>ADBC aims to provide a minimal database client API standard, based on
Arrow, for C, Go, and Java (with bindings for other languages).
Applications code to this API standard (in much the same way as they
would with JDBC or ODBC), but fetch result sets in Arrow format
(e.g. via the <a class="reference internal" href="CDataInterface.html"><span class="doc">C Data Interface</span></a>). They then
link to an implementation of the standard: either directly to a
vendor-supplied driver for a particular database, or to a driver
manager that abstracts across multiple drivers. Drivers implement the
standard using a database-specific API, such as Flight SQL.</p>
<section id="goals">
<h3>Goals<a class="headerlink" href="#goals" title="Permalink to this heading">#</a></h3>
<ul class="simple">
<li><p>Provide a cross-language, Arrow-based API to standardize how clients
submit queries to and fetch Arrow data from databases.</p></li>
<li><p>Support both SQL dialects and the emergent <a class="reference external" href="https://substrait.io">Substrait</a> standard.</p></li>
<li><p>Support explicitly partitioned/distributed result sets to work
better with contemporary distributed systems.</p></li>
<li><p>Allow for a variety of implementations to maximize reach.</p></li>
</ul>
</section>
<section id="non-goals">
<h3>Non-goals<a class="headerlink" href="#non-goals" title="Permalink to this heading">#</a></h3>
<ul class="simple">
<li><p>Replacing JDBC/ODBC in all use cases, particularly <a class="reference external" href="https://en.wikipedia.org/wiki/Online_transaction_processing">OLTP</a> use
cases.</p></li>
<li><p>Requiring or enshrining a particular database protocol for the Arrow
ecosystem.</p></li>
</ul>
</section>
<section id="example-use-cases">
<h3>Example use cases<a class="headerlink" href="#example-use-cases" title="Permalink to this heading">#</a></h3>
<p>A C or C++ application wishes to retrieve bulk data from a Postgres
database for further analysis. The application is compiled against
the ADBC header, and executes queries via the ADBC APIs. The
application is linked against the ADBC libpq driver. At runtime, the
driver submits queries to the database via the Postgres client
libraries, and retrieves row-oriented results, which it then converts
to Arrow format before returning them to the application.</p>
<p>If the application wishes to retrieve data from a database supporting
Flight SQL instead, it would link against the ADBC Flight SQL driver.
At runtime, the driver would submit queries via Flight SQL and get
back Arrow data, which is then passed unchanged and uncopied to the
application. (The application may have to edit the SQL queries, as
ADBC does not translate between SQL dialects.)</p>
<p>If the application wishes to work with multiple databases, it would
link against the ADBC driver manager, and specify the desired driver
at runtime. The driver manager would pass on API calls to the correct
driver, which handles the request.</p>
</section>
</section>
<section id="adbc-api-standard-1-0-0">
<h2>ADBC API Standard 1.0.0<a class="headerlink" href="#adbc-api-standard-1-0-0" title="Permalink to this heading">#</a></h2>
<p>ADBC is a language-specific set of interface definitions that can be
implemented directly by a vendor-specific “driver” or a vendor-neutral
“driver manager”.</p>
<p>Version 1.0.0 of the standard corresponds to tag adbc-1.0.0 of the
repository <code class="docutils literal notranslate"><span class="pre">apache/arrow-adbc</span></code>, which is commit
<a class="reference external" href="https://github.com/apache/arrow-adbc/commit/f044edf5256abfb4c091b0ad2acc73afea2c93c0">f044edf5256abfb4c091b0ad2acc73afea2c93c0</a>. Note that is separate
from releases of the actual implementations.</p>
<p>See the language-specific pages for details:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="ADBC/C.html">ADBC C API Specification</a></li>
<li class="toctree-l1"><a class="reference internal" href="ADBC/Go.html">ADBC Go API Specification</a></li>
<li class="toctree-l1"><a class="reference internal" href="ADBC/Java.html">ADBC Java API Specification</a></li>
</ul>
</div>
</section>
<section id="updating-this-specification">
<h2>Updating this specification<a class="headerlink" href="#updating-this-specification" title="Permalink to this heading">#</a></h2>
<p>ADBC is versioned separately from the core Arrow project. The API
standard and components (driver manager, drivers) are also versioned
separately, but both follow semantic versioning.</p>
<p>For example: components may make backwards-compatible releases as
1.0.0, 1.0.1, 1.1.0, 1.2.0, etc. They may release
backwards-incompatible versions such as 2.0.0, but which still
implement the API standard version 1.0.0.</p>
<p>Similarly, this documentation describes the ADBC API standard version
1.0.0. If/when an ABI-compatible revision is made
(e.g. new standard options are defined), the next version would be
1.1.0. If incompatible changes are made (e.g. new API functions), the
next version would be 2.0.0.</p>
</section>
<section id="related-work">
<h2>Related work<a class="headerlink" href="#related-work" title="Permalink to this heading">#</a></h2>
<p>In the initial proposal, a survey of existing solutions and systems
was included, which is reproduced below for context, though note the
descriptions are only kept up-to-date on a best-effort basis.</p>
<section id="comparison-with-arrow-flight-sql">
<h3>Comparison with Arrow Flight SQL<a class="headerlink" href="#comparison-with-arrow-flight-sql" title="Permalink to this heading">#</a></h3>
<p>Flight SQL is a <strong>client-server protocol</strong> oriented at database
developers. By implementing Flight SQL, a database can support
clients that use ADBC, JDBC, and ODBC.</p>
<p>ADBC is an <strong>API specification</strong> oriented at database clients. By
coding to ADBC, an application can get Arrow data from a variety of
databases that use different client technologies underneath.</p>
<p>Hence, the two projects complement each other. While Flight SQL
provides a client that can be used directly, we expect applications
would prefer to use ADBC instead of tying themselves to a particular
database.</p>
</section>
<section id="comparison-with-jdbc-odbc">
<h3>Comparison with JDBC/ODBC<a class="headerlink" href="#comparison-with-jdbc-odbc" title="Permalink to this heading">#</a></h3>
<p>JDBC is a row-based API, so bridging JDBC to Arrow is hard to do
efficiently.</p>
<p>ODBC provides support for bulk data with <a class="reference external" href="https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/block-cursors?view=sql-server-ver15">block cursors</a>, and
<a class="reference external" href="https://turbodbc.readthedocs.io/en/latest/">Turbodbc</a> demonstrates that a performant Arrow-based API can be built
on top. However, it is still an awkward fit for Arrow:</p>
<ul class="simple">
<li><p>Nulls (‘indicator’ values) are <a class="reference external" href="https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/using-length-and-indicator-values?view=sql-server-ver15">represented as integers</a>, requiring
conversion.</p></li>
<li><p><a class="reference external" href="https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/allocating-and-freeing-buffers?view=sql-server-ver15">Result buffers are caller-allocated</a>. This can force unnecessarily
copying data. ADBC uses the C Data Interface instead, eliminating
copies when possible (e.g. if the driver uses Flight SQL).</p></li>
<li><p>Some data types are represented differently, and require
conversion. <a class="reference external" href="https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/transferring-data-in-its-binary-form?view=sql-server-ver15">SQL_C_BINARY</a> can sidestep this for drivers and
applications that cooperate, but then applications would have to
treat Arrow-based and non-Arrow-based data sources differently.</p>
<ul>
<li><p><a class="reference external" href="https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/character-data-and-c-strings?view=sql-server-ver15">Strings must be null-terminated</a>, which would require a copy
into an Arrow array, or require that the application handle null
terminated strings in an array.</p></li>
<li><p>It is implementation-defined whether strings may have embedded
nulls, but Arrow specifies UTF-8 strings for which 0x00 is a valid
byte.</p></li>
<li><p>Because buffers are caller-allocated, the driver and application
must cooperate to handle large strings; <a class="reference external" href="https://docs.microsoft.com/en-us/sql/odbc/reference/develop-app/data-length-buffer-length-and-truncation?view=sql-server-ver15">the driver must truncate
the value</a>, and the application can try to fetch the value again.</p></li>
<li><p>ODBC uses length buffers rather than offsets, requiring another
conversion to/from Arrow string arrays.</p></li>
<li><p><a class="reference external" href="https://docs.microsoft.com/en-us/sql/odbc/reference/appendixes/c-interval-structure?view=sql-server-ver15">Time intervals use different representations</a>.</p></li>
</ul>
</li>
</ul>
<p>Hence, we think just extending ODBC is insufficient to meet the goals
of ADBC. ODBC will always be valuable for wider database support, and
providing an Arrow-based API on top of ODBC is useful. ADBC would
allow implementing/optimizing this conversion in a common library,
provide a simpler interface for consumers, and would provide an API
that Arrow-native or otherwise columnar systems can implement to
bypass this wrapper.</p>
<figure class="align-default" id="id1">
<img alt="../_images/ADBCQuadrants.svg" src="../_images/ADBCQuadrants.svg" /><figcaption>
<p><span class="caption-text">ADBC, JDBC, and ODBC are database-agnostic. They define the
API that the application uses, but not how that API is implemented,
instead deferring to drivers to fulfill requests using the protocol
of their choice. JDBC and (generally) ODBC offer results in a
row-oriented format, while ADBC offers columnar Arrow data.</span><a class="headerlink" href="#id1" title="Permalink to this image">#</a></p>
<div class="legend">
<p>Protocols/libraries like libpq (Postgres) and TDS (SQL Server) are
database-specific and row-oriented. Multiple databases may
implement the same protocol to try to reuse each other’s work,
e.g. several databases implement the Postgres wire protocol to
benefit from its driver implementations. But the protocol itself
was not designed with multiple databases in mind, nor are the
protocols generally meant to be used directly by applications.</p>
<p>Some database-specific protocols are Arrow-native, like those of
BigQuery and ClickHouse. Flight SQL additionally is meant to be
database-agnostic, but it defines both the client-facing API and
the underlying protocol, so it’s hard for applications to use it as
the API for databases that don’t already implement Flight SQL.</p>
</div>
</figcaption>
</figure>
</section>
<section id="existing-database-client-apis">
<h3>Existing database client APIs<a class="headerlink" href="#existing-database-client-apis" title="Permalink to this heading">#</a></h3>
<dl class="simple">
<dt><a class="reference internal" href="FlightSql.html"><span class="doc">Arrow Flight SQL</span></a></dt><dd><p>A standard building on top of Arrow Flight, defining how to use
Flight to talk to databases, retrieve metadata, execute queries, and
so on. Provides a single client in C++ and Java language that talks
to any database servers implementing the protocol. Models its API
surface (though not API design) after JDBC and ODBC.</p>
</dd>
<dt><a class="reference external" href="https://www.r-dbi.org/">DBI for R</a></dt><dd><p>An R package/ecosystem of packages for database access. Provides a
single interface with “backends” for specific databases. While
row-oriented, <a class="reference external" href="https://r-dbi.github.io/dbi3/articles/dbi3.html#using-arrowparquet-as-an-exchange-format">integration with Arrow is under consideration</a>,
including a sketch of effectively the same idea as ADBC.</p>
</dd>
<dt><a class="reference external" href="https://jcp.org/en/jsr/detail?id=221">JDBC</a></dt><dd><p>A Java library for database access, providing row-based
APIs. Provides a single interface with drivers for specific
databases.</p>
</dd>
<dt><a class="reference external" href="https://github.com/microsoft/ODBC-Specification">ODBC</a></dt><dd><p>A language-agnostic standard from the ISO/IEC for database access,
associated with Microsoft. Feature-wise, it is similar to JDBC (and
indeed JDBC can wrap ODBC drivers), but it offers columnar data
support through fetching buffers of column values. (See above for
caveats.) Provides a single C interface with drivers for specific
databases.</p>
</dd>
<dt><a class="reference external" href="https://www.python.org/dev/peps/pep-0249/">PEP 249</a> (DBAPI 2.0)</dt><dd><p>A Python standard for database access providing row-based APIs. Not
a singular package, but rather a set of interfaces that packages
implement.</p>
</dd>
</dl>
</section>
<section id="existing-libraries">
<h3>Existing libraries<a class="headerlink" href="#existing-libraries" title="Permalink to this heading">#</a></h3>
<p>These are libraries which either 1) implement columnar data access for
a particular system; or 2) could be used to implement such access.</p>
<dl class="simple">
<dt><a class="reference internal" href="Flight.html"><span class="doc">Arrow Flight</span></a></dt><dd><p>An RPC framework optimized for transferring Arrow record batches,
with application-specific extension points but without any higher
level semantics.</p>
</dd>
<dt><a class="reference internal" href="../java/jdbc.html"><span class="doc">Arrow JDBC</span></a></dt><dd><p>A Java submodule, part of Arrow/Java, that uses the JDBC API to
produce Arrow data. Internally, it can read data only row-at-a-time.</p>
</dd>
<dt><a class="reference external" href="https://github.com/pacman82/arrow-odbc">arrow-odbc</a></dt><dd><p>A Rust community project that uses the ODBC API to produce Arrow
data, using ODBC’s buffer-based API to perform bulk copies. (See
also: Turbodbc.)</p>
</dd>
<dt><a class="reference external" href="https://github.com/jorgecarleitao/arrowdantic/">Arrowdantic</a></dt><dd><p>Python bindings for an implementation of ODBC&lt;&gt;Arrow in Rust.</p>
</dd>
<dt><a class="reference external" href="https://github.com/0x0L/pgeon">pgeon</a></dt><dd><p>A client that manually parses the Postgres wire format and produces
Arrow data, bypassing JDBC/ODBC. While it attempts to optimize this
case, the Postgres wire protocol is still row-oriented.</p>
</dd>
<dt><a class="reference external" href="https://turbodbc.readthedocs.io/en/latest/">Turbodbc</a></dt><dd><p>A set of Python ODBC bindings, implementing PEP 249, that also
provides APIs to fetch data as Arrow batches, optimizing the
conversion internally.</p>
</dd>
</dl>
</section>
<section id="papers">
<h3>Papers<a class="headerlink" href="#papers" title="Permalink to this heading">#</a></h3>
<p>Raasveldt, Mark, and Hannes Mühleisen. <a class="reference external" href="https://ir.cwi.nl/pub/26415">“Don’t Hold My Data Hostage -
A Case for Client Protocol Redesign”</a>. In <em>Proceedings of the VLDB
Endowment</em>, 1022–1033, 2017.</p>
</section>
</section>
</section>
</article>
<footer class="prev-next-footer">
<div class="prev-next-area">
<a class="left-prev"
href="FlightSql.html"
title="previous page">
<i class="fa-solid fa-angle-left"></i>
<div class="prev-next-info">
<p class="prev-next-subtitle">previous</p>
<p class="prev-next-title">Arrow Flight SQL</p>
</div>
</a>
<a class="right-next"
href="ADBC/C.html"
title="next page">
<div class="prev-next-info">
<p class="prev-next-subtitle">next</p>
<p class="prev-next-title">ADBC C API Specification</p>
</div>
<i class="fa-solid fa-angle-right"></i>
</a>
</div>
</footer>
</div>
<div class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">
<div class="sidebar-secondary-item">
<div
id="pst-page-navigation-heading-2"
class="page-toc tocsection onthispage">
<i class="fa-solid fa-list"></i> On this page
</div>
<nav class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#rationale">Rationale</a><ul class="visible nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#goals">Goals</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#non-goals">Non-goals</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#example-use-cases">Example use cases</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#adbc-api-standard-1-0-0">ADBC API Standard 1.0.0</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#updating-this-specification">Updating this specification</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#related-work">Related work</a><ul class="visible nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#comparison-with-arrow-flight-sql">Comparison with Arrow Flight SQL</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#comparison-with-jdbc-odbc">Comparison with JDBC/ODBC</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#existing-database-client-apis">Existing database client APIs</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#existing-libraries">Existing libraries</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#papers">Papers</a></li>
</ul>
</li>
</ul>
</nav></div>
<div class="sidebar-secondary-item">
<div class="tocsection editthispage">
<a href="https://github.com/apache/arrow/edit/main/docs/source/format/ADBC.rst">
<i class="fa-solid fa-pencil"></i>
Edit on GitHub
</a>
</div>
</div>
</div></div>
</div>
<footer class="bd-footer-content">
</footer>
</main>
</div>
</div>
<!-- Scripts loaded after <body> so the DOM is not blocked -->
<script src="../_static/scripts/bootstrap.js?digest=8d27b9dea8ad943066ae"></script>
<script src="../_static/scripts/pydata-sphinx-theme.js?digest=8d27b9dea8ad943066ae"></script>
<footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
<div class="footer-items__start">
<div class="footer-item">
<p class="copyright">
© Copyright 2016-2024 Apache Software Foundation.
Apache Arrow, Arrow, Apache, the Apache feather logo, and the Apache Arrow project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.
<br/>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 6.2.0.
<br/>
</p>
</div>
</div>
<div class="footer-items__end">
<div class="footer-item">
<p class="theme-version">
Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.15.2.
</p></div>
</div>
</div>
</footer>
</body>
</html>