| <!DOCTYPE HTML> |
| <html lang="en-US"> |
| <head> |
| <meta charset="UTF-8"> |
| <title>Background</title> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="generator" content="Jekyll v4.2.2"> |
| <link rel="stylesheet" href="//fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900"> |
| <link rel="stylesheet" href="/avatica/css/screen.css"> |
| <link rel="icon" type="image/x-icon" href="/avatica/favicon.ico"> |
| </head> |
| |
| |
| <body class="wrap"> |
| <header role="banner"> |
| <nav class="mobile-nav show-on-mobiles"> |
| <ul> |
| <li class=""> |
| <a href="/avatica/">Home</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/downloads/">Download</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/community/">Community</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/develop/">Develop</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/news/">News</a> |
| </li> |
| <li class="current"> |
| <a href="/avatica/docs/">Docs</a> |
| </li> |
| </ul> |
| |
| </nav> |
| <div class="grid"> |
| <div class="unit one-third center-on-mobiles"> |
| <h1> |
| <a href="/avatica/"> |
| <span class="sr-only">Apache Calcite Avatica</span> |
| <img src="/avatica/img/logo.png" width="226" height="140" alt="Calcite Logo"> |
| </a> |
| </h1> |
| </div> |
| <nav class="main-nav unit two-thirds hide-on-mobiles"> |
| <ul> |
| <li class=""> |
| <a href="/avatica/">Home</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/downloads/">Download</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/community/">Community</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/develop/">Develop</a> |
| </li> |
| <li class=""> |
| <a href="/avatica/news/">News</a> |
| </li> |
| <li class="current"> |
| <a href="/avatica/docs/">Docs</a> |
| </li> |
| </ul> |
| |
| </nav> |
| </div> |
| </header> |
| |
| |
| <section class="docs"> |
| <div class="grid"> |
| |
| <div class="docs-nav-mobile unit whole show-on-mobiles"> |
| <select onchange="if (this.value) window.location.href=this.value"> |
| <option value="">Navigate the docs…</option> |
| |
| <optgroup label="Overview"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </optgroup> |
| |
| <optgroup label="Avatica Reference"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </optgroup> |
| |
| <optgroup label="Avatica Go Client Reference"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </optgroup> |
| |
| <optgroup label="Avatica Meta"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </optgroup> |
| |
| <optgroup label="Avatica Go Client Meta"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </optgroup> |
| |
| </select> |
| </div> |
| |
| |
| <div class="unit four-fifths"> |
| <article> |
| <h1>Background</h1> |
| <!-- |
| |
| --> |
| |
| <p>Avatica is a framework for building JDBC and ODBC drivers for databases, |
| and an RPC wire protocol.</p> |
| |
| <p><img src="https://raw.githubusercontent.com/julianhyde/share/main/slides/avatica-architecture.png" alt="Avatica Architecture" /></p> |
| |
| <p>Avatica’s Java binding has very few dependencies. |
| Even though it is part of Apache Calcite it does not depend on other parts of |
| Calcite. It depends only on JDK 8+ and Jackson.</p> |
| |
| <p>Avatica’s wire protocols are JSON or Protocol Buffers over HTTP. The |
| Java implementation of the JSON protocol uses |
| <a href="https://github.com/FasterXML/jackson">Jackson</a> to convert |
| request/response command objects to/from JSON.</p> |
| |
| <p>Avatica-Server is a Java implementation of Avatica RPC.</p> |
| |
| <p>Core concepts:</p> |
| |
| <ul> |
| <li><a href="/avatica/javadocAggregate/org/apache/calcite/avatica/Meta.html">Meta</a> |
| is a local API sufficient to implement any Avatica provider</li> |
| <li><a href="/avatica/javadocAggregate/org/apache/calcite/avatica/AvaticaFactory.html">AvaticaFactory</a> |
| creates implementations of the JDBC classes on top of a <code class="language-plaintext highlighter-rouge">Meta</code></li> |
| <li><a href="/avatica/javadocAggregate/org/apache/calcite/avatica/remote/Service.html">Service</a> |
| is an interface that implements the functions of <code class="language-plaintext highlighter-rouge">Meta</code> in terms |
| of request and response command objects</li> |
| </ul> |
| |
| <h2 id="jdbc">JDBC</h2> |
| |
| <p>Avatica implements JDBC by means of |
| <a href="/avatica/javadocAggregate/org/apache/calcite/avatica/AvaticaFactory.html">AvaticaFactory</a>. |
| An implementation of <code class="language-plaintext highlighter-rouge">AvaticaFactory</code> creates implementations of the |
| JDBC classes (<a href="https://docs.oracle.com/javase/8/docs/api//java/sql/Driver.html">Driver</a>, |
| <a href="https://docs.oracle.com/javase/8/docs/api//java/sql/Connection.html">Connection</a>, |
| <a href="https://docs.oracle.com/javase/8/docs/api//java/sql/Statement.html">Statement</a>, |
| <a href="https://docs.oracle.com/javase/8/docs/api//java/sql/ResultSet.html">ResultSet</a>) |
| on top of a <code class="language-plaintext highlighter-rouge">Meta</code>.</p> |
| |
| <h2 id="odbc">ODBC</h2> |
| |
| <p>Work has not started on Avatica ODBC.</p> |
| |
| <p>Avatica ODBC would use the same wire protocol and could use the same server |
| implementation in Java. The ODBC client would be written in C or C++.</p> |
| |
| <p>Since the Avatica protocol abstracts many of the differences between providers, |
| the same ODBC client could be used for different databases.</p> |
| |
| <p>Although the Avatica project does not include an ODBC driver, there |
| are ODBC drivers written on top of the Avatica protocol, for example |
| <a href="http://hortonworks.com/hadoop-tutorial/bi-apache-phoenix-odbc/">an ODBC driver for Apache Phoenix</a>.</p> |
| |
| <h2 id="http-server">HTTP Server</h2> |
| |
| <p>Avatica-server embeds the Jetty HTTP server, providing a class |
| <a href="/avatica/javadocAggregate/org/apache/calcite/avatica/server/HttpServer.html">HttpServer</a> |
| that implements the Avatica RPC protocol |
| and can be run as a standalone Java application.</p> |
| |
| <p>Connectors in HTTP server can be configured if needed by extending |
| <code class="language-plaintext highlighter-rouge">HttpServer</code> class and overriding its <code class="language-plaintext highlighter-rouge">configureConnector()</code> method. |
| For example, user can set <code class="language-plaintext highlighter-rouge">requestHeaderSize</code> to 64K bytes as follows:</p> |
| |
| <figure class="highlight"><pre><code class="language-java" data-lang="java"><span class="nc">HttpServer</span> <span class="n">server</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">HttpServer</span><span class="o">(</span><span class="n">handler</span><span class="o">)</span> <span class="o">{</span> |
| <span class="nd">@Override</span> |
| <span class="kd">protected</span> <span class="nc">ServerConnector</span> <span class="nf">configureConnector</span><span class="o">(</span> |
| <span class="nc">ServerConnector</span> <span class="n">connector</span><span class="o">,</span> <span class="kt">int</span> <span class="n">port</span><span class="o">)</span> <span class="o">{</span> |
| <span class="nc">HttpConnectionFactory</span> <span class="n">factory</span> <span class="o">=</span> <span class="o">(</span><span class="nc">HttpConnectionFactory</span><span class="o">)</span> |
| <span class="n">connector</span><span class="o">.</span><span class="na">getDefaultConnectionFactory</span><span class="o">();</span> |
| <span class="n">factory</span><span class="o">.</span><span class="na">getHttpConfiguration</span><span class="o">().</span><span class="na">setRequestHeaderSize</span><span class="o">(</span><span class="mi">64</span> <span class="o"><<</span> <span class="mi">10</span><span class="o">);</span> |
| <span class="k">return</span> <span class="kd">super</span><span class="o">.</span><span class="na">configureConnector</span><span class="o">(</span><span class="n">connector</span><span class="o">,</span> <span class="n">port</span><span class="o">);</span> |
| <span class="o">}</span> |
| <span class="o">};</span> |
| <span class="n">server</span><span class="o">.</span><span class="na">start</span><span class="o">();</span></code></pre></figure> |
| |
| <h2 id="project-structure">Project structure</h2> |
| |
| <p>We know that it is important that client libraries have minimal dependencies.</p> |
| |
| <p>Avatica is a sub-project of <a href="https://calcite.apache.org">Apache Calcite</a>, |
| maintained in a separate repository. |
| It does not depend upon any other part of Calcite.</p> |
| |
| <p>Packages:</p> |
| |
| <ul> |
| <li><a href="/avatica/javadocAggregate/org/apache/calcite/avatica/package-summary.html">org.apache.calcite.avatica</a> Core framework</li> |
| <li><a href="/avatica/javadocAggregate/org/apache/calcite/avatica/remote/package-summary.html">org.apache.calcite.avatica.remote</a> JDBC driver that uses remote procedure calls</li> |
| <li><a href="/avatica/javadocAggregate/org/apache/calcite/avatica/server/package-summary.html">org.apache.calcite.avatica.server</a> HTTP server</li> |
| <li><a href="/avatica/javadocAggregate/org/apache/calcite/avatica/util/package-summary.html">org.apache.calcite.avatica.util</a> Utilities</li> |
| </ul> |
| |
| <h2 id="status">Status</h2> |
| |
| <h3 id="implemented">Implemented</h3> |
| |
| <ul> |
| <li>Create connection, create statement, metadata, prepare, bind, execute, fetch</li> |
| <li>RPC using JSON over HTTP</li> |
| <li>Local implementation</li> |
| <li>Implementation over an existing JDBC driver</li> |
| <li>Composite RPCs (combining several requests into one round trip) |
| <ul> |
| <li>Execute-Fetch</li> |
| <li>Metadata-Fetch (metadata calls such as getTables return all rows)</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <h3 id="not-implemented">Not implemented</h3> |
| |
| <ul> |
| <li>ODBC</li> |
| <li>RPCs |
| <ul> |
| <li>CloseStatement</li> |
| <li>CloseConnection</li> |
| </ul> |
| </li> |
| <li>Composite RPCs |
| <ul> |
| <li>CreateStatement-Prepare</li> |
| <li>CloseStatement-CloseConnection</li> |
| <li>Prepare-Execute-Fetch (Statement.executeQuery should fetch first N rows)</li> |
| </ul> |
| </li> |
| <li>Remove statements from statement table</li> |
| <li>DML (INSERT, UPDATE, DELETE)</li> |
| <li>Statement.execute applied to SELECT statement</li> |
| </ul> |
| |
| <h2 id="clients">Clients</h2> |
| |
| <p>The following is a list of available Avatica clients. Several describe |
| themselves as adapters for |
| <a href="http://phoenix.apache.org">Apache Phoenix</a> but also work with other |
| Avatica back-ends. Contributions for clients in other languages are |
| highly welcomed!</p> |
| |
| <h3 id="microsoft-net-driver-for-apache-phoenix-query-server">Microsoft .NET driver for Apache Phoenix Query Server</h3> |
| <ul> |
| <li><a href="https://github.com/Azure/hdinsight-phoenix-sharp">Home page</a></li> |
| <li>Language: C#</li> |
| <li><em>License</em>: <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0</a></li> |
| <li>Avatica version 1.2.0 onwards</li> |
| <li><em>Maintainer</em>: Microsoft Azure</li> |
| </ul> |
| |
| <h3 id="apache-phoenixavatica-sql-driver">Apache Phoenix/Avatica SQL Driver</h3> |
| <ul> |
| <li><a href="https://github.com/apache/calcite-avatica-go">Home page</a></li> |
| <li><em>Language</em>: Go</li> |
| <li><em>License</em>: <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0</a></li> |
| <li>Avatica version 1.8.0 onwards</li> |
| <li><em>Maintainer</em>: Boostport and the Apache Calcite community</li> |
| </ul> |
| |
| <h3 id="avatica-thin-client">Avatica thin client</h3> |
| <ul> |
| <li><a href="https://calcite.apache.org/avatica">Home page</a></li> |
| <li><em>Language</em>: Java</li> |
| <li><em>License</em>: <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0</a></li> |
| <li>Any Avatica version</li> |
| <li><em>Maintainer</em>: Apache Calcite community</li> |
| </ul> |
| |
| <h3 id="apache-phoenix-database-adapter-for-python">Apache Phoenix database adapter for Python</h3> |
| <ul> |
| <li><a href="https://phoenix.apache.org/python.html">Home page</a></li> |
| <li>Language: Python</li> |
| <li><em>License</em>: <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache 2.0</a></li> |
| <li>Avatica version 1.2.0 onwards</li> |
| <li><em>Maintainer</em>: Apache Phoenix community</li> |
| </ul> |
| |
| <h3 id="javascript-binding-to-calcite-avatica-server">JavaScript binding to Calcite Avatica Server</h3> |
| <ul> |
| <li><a href="https://github.com/waylayio/avatica-js">Home page</a></li> |
| <li>Language: JavaScript</li> |
| <li><em>License</em>: <a href="https://opensource.org/licenses/MIT">MIT</a></li> |
| <li>Any Avatica version</li> |
| <li><em>Maintainer</em>: Waylay.io</li> |
| </ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <div class="section-nav"> |
| <div class="left align-right"> |
| |
| <span class="prev disabled">Previous</span> |
| |
| </div> |
| <div class="right align-left"> |
| |
| |
| |
| |
| |
| <a href="/avatica/docs/roadmap.html" class="next">Next</a> |
| |
| </div> |
| </div> |
| <div class="clear"></div> |
| |
| |
| </article> |
| </div> |
| |
| <div class="unit one-fifth hide-on-mobiles"> |
| <aside> |
| |
| <h4>Overview</h4> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="current"><a href="/avatica/docs/index.html">Background</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/roadmap.html">Roadmap</a></li> |
| |
| |
| </ul> |
| |
| |
| <h4>Avatica Reference</h4> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/client_reference.html">Client Reference</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/json_reference.html">JSON Reference</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/protobuf_reference.html">Protobuf Reference</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/howto.html">HOWTO</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/security.html">Security</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/compatibility.html">Compatibility</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/custom_client_artifacts.html">Custom Client Artifacts</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/docker.html">Docker Images</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/protocol_testing.html">Protocol Testing</a></li> |
| |
| |
| </ul> |
| |
| |
| <h4>Avatica Go Client Reference</h4> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/go_client_reference.html">Go Client Reference</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/go_howto.html">HOWTO</a></li> |
| |
| |
| </ul> |
| |
| |
| <h4>Avatica Meta</h4> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/history.html">History</a></li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/api/">API</a></li> |
| |
| |
| </ul> |
| |
| |
| <h4>Avatica Go Client Meta</h4> |
| |
| |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class=""><a href="/avatica/docs/go_history.html">Go Client History</a></li> |
| |
| |
| </ul> |
| |
| |
| </aside> |
| </div> |
| |
| |
| <div class="clear"></div> |
| |
| </div> |
| </section> |
| |
| |
| <footer role="contentinfo"> |
| <div id="poweredby"> |
| <a href="http://www.apache.org/"> |
| <span class="sr-only">Apache</span> |
| <img src="/avatica/img/feather.png" width="190" height="77" alt="Apache Logo"></a> |
| </div> |
| <div id="copyright"> |
| <p>The contents of this website are © 2023 |
| <a href="https://www.apache.org/">Apache Software Foundation</a> |
| under the terms of |
| the <a href="https://www.apache.org/licenses/LICENSE-2.0.html"> |
| Apache License v2</a>. Apache Calcite and its logo are |
| trademarks of the Apache Software Foundation. |
| </p> |
| <p> |
| <a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy Policy</a> |
| </p> |
| </div> |
| </footer> |
| |
| <script> |
| var anchorForId = function (id) { |
| var anchor = document.createElement("a"); |
| anchor.className = "header-link"; |
| anchor.href = "#" + id; |
| anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>"; |
| anchor.title = "Permalink"; |
| return anchor; |
| }; |
| |
| var linkifyAnchors = function (level, containingElement) { |
| var headers = containingElement.getElementsByTagName("h" + level); |
| for (var h = 0; h < headers.length; h++) { |
| var header = headers[h]; |
| |
| if (typeof header.id !== "undefined" && header.id !== "") { |
| header.appendChild(anchorForId(header.id)); |
| } |
| } |
| }; |
| |
| document.onreadystatechange = function () { |
| if (this.readyState === "complete") { |
| var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0]; |
| if (!contentBlock) { |
| return; |
| } |
| for (var level = 1; level <= 6; level++) { |
| linkifyAnchors(level, contentBlock); |
| } |
| } |
| }; |
| </script> |
| |
| |
| </body> |
| </html> |