| <!doctype html> |
| <html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-api-reference/sql-jdbc"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta name="generator" content="Docusaurus v2.4.1"> |
| <title data-rh="true">SQL JDBC driver API | Apache® Druid</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://druid.apache.org/img/druid_nav.png"><meta data-rh="true" name="twitter:image" content="https://druid.apache.org/img/druid_nav.png"><meta data-rh="true" property="og:url" content="https://druid.apache.org/docs/latest/api-reference/sql-jdbc"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="SQL JDBC driver API | Apache® Druid"><meta data-rh="true" name="description" content="<!--"><meta data-rh="true" property="og:description" content="<!--"><link data-rh="true" rel="icon" href="/img/favicon.png"><link data-rh="true" rel="canonical" href="https://druid.apache.org/docs/latest/api-reference/sql-jdbc"><link data-rh="true" rel="alternate" href="https://druid.apache.org/docs/latest/api-reference/sql-jdbc" hreflang="en"><link data-rh="true" rel="alternate" href="https://druid.apache.org/docs/latest/api-reference/sql-jdbc" hreflang="x-default"><link rel="preconnect" href="https://www.google-analytics.com"> |
| <link rel="preconnect" href="https://www.googletagmanager.com"> |
| <script async src="https://www.googletagmanager.com/gtag/js?id=UA-131010415-1"></script> |
| <script>function gtag(){dataLayer.push(arguments)}window.dataLayer=window.dataLayer||[],gtag("js",new Date),gtag("config","UA-131010415-1",{})</script> |
| |
| |
| |
| |
| <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.7.2/css/all.css"> |
| <script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.4/clipboard.min.js"></script><link rel="stylesheet" href="/assets/css/styles.546f39eb.css"> |
| <link rel="preload" href="/assets/js/runtime~main.26d714fb.js" as="script"> |
| <link rel="preload" href="/assets/js/main.bd54ee66.js" as="script"> |
| </head> |
| <body class="navigation-with-keyboard"> |
| <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus"> |
| <div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top navbar--dark"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/druid_nav.png" alt="Apache® Druid" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/druid_nav.png" alt="Apache® Druid" class="themedImage_ToTc themedImage--dark_i4oU"></div></a></div><div class="navbar__items navbar__items--right"><a class="navbar__item navbar__link" href="/technology">Technology</a><a class="navbar__item navbar__link" href="/use-cases">Use Cases</a><a class="navbar__item navbar__link" href="/druid-powered">Powered By</a><a class="navbar__item navbar__link" href="/docs/latest/design/">Docs</a><a class="navbar__item navbar__link" href="/community/">Community</a><div class="navbar__item dropdown dropdown--hoverable dropdown--right"><a href="#" aria-haspopup="true" aria-expanded="false" role="button" class="navbar__link">Apache®</a><ul class="dropdown__menu"><li><a href="https://www.apache.org/" target="_blank" rel="noopener noreferrer" class="dropdown__link">Foundation<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://apachecon.com/?ref=druid.apache.org" target="_blank" rel="noopener noreferrer" class="dropdown__link">Events<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/licenses/" target="_blank" rel="noopener noreferrer" class="dropdown__link">License<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener noreferrer" class="dropdown__link">Thanks<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/security/" target="_blank" rel="noopener noreferrer" class="dropdown__link">Security<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li><a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener noreferrer" class="dropdown__link">Sponsorship<svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><a class="navbar__item navbar__link" href="/downloads/">Download</a><div class="searchBox_ZlJk"><div class="navbar__search"><span aria-label="expand searchbar" role="button" class="search-icon" tabindex="0"></span><input type="search" id="search_input_react" placeholder="Loading..." aria-label="Search" class="navbar__search-input search-bar" disabled=""></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0 docsWrapper_BCFX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docPage__5DB"><aside class="theme-doc-sidebar-container docSidebarContainer_b6E3"><div class="sidebarViewport_Xe31"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/design/">Getting started</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/tutorials/tutorial-msq-extern">Tutorials</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/design/architecture">Design</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/ingestion/">Ingestion</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/data-management/">Data management</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/querying/sql">Querying</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" aria-expanded="true" href="/docs/latest/api-reference/">API reference</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/latest/api-reference/">Overview</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" tabindex="0" href="/docs/latest/api-reference/sql-api">HTTP APIs</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" aria-expanded="true" tabindex="0" href="/docs/latest/api-reference/sql-jdbc">Java APIs</a></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-3 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/latest/api-reference/sql-jdbc">SQL JDBC driver</a></li></ul></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/configuration/">Configuration</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/operations/web-console">Operations</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/development/overview">Development</a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="/docs/latest/misc/papers-and-talks">Misc</a></div></li></ul></nav></div></div></aside><main class="docMainContainer_gTbr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">API reference</span><meta itemprop="position" content="1"></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Java APIs</span><meta itemprop="position" content="2"></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">SQL JDBC driver</span><meta itemprop="position" content="3"></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>SQL JDBC driver API</h1></header><div class="theme-admonition theme-admonition-info alert alert--info admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>info</div><div class="admonitionContent_S0QG"><p>Apache Druid supports two query languages: Druid SQL and <a href="/docs/latest/querying/">native queries</a>. |
| This document describes the SQL language.</p></div></div><p>You can make <a href="/docs/latest/querying/sql">Druid SQL</a> queries using the <a href="https://calcite.apache.org/avatica/downloads/" target="_blank" rel="noopener noreferrer">Avatica JDBC driver</a>. We recommend using Avatica JDBC driver version 1.17.0 or later. Note that as of the time of this writing, Avatica 1.17.0, the latest version, does not support passing connection string parameters from the URL to Druid, so you must pass them using a <code>Properties</code> object. Once you've downloaded the Avatica client jar, add it to your classpath and use the connect string <code>jdbc:avatica:remote:url=http://BROKER:8082/druid/v2/sql/avatica/</code>.</p><p>When using the JDBC connector for the <a href="#examples">examples</a> or in general, it's helpful to understand the parts of the connect string stored in the <code>url</code> variable:</p><ul><li><code>jdbc:avatica:remote:url=</code> is prepended to the hostname and port.</li><li>The hostname and port number for your Druid deployment depends on whether you want to connect to the Router or a specific Broker. For more information, see <a href="#connection-stickiness">Connection stickiness</a>. In the case of the quickstart deployment, the hostname and port are <code>http://localhost:8888</code>, which connects to the Router running on your local machine.</li><li>The SQL endpoint in Druid for the Avatica driver is <code>/druid/v2/sql/avatica/</code>.</li></ul><p>Example code:</p><div class="language-java codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-java codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">// Connect to /druid/v2/sql/avatica/ on your Broker.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">String url = "jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica/";</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">// Set any connection context parameters you need here</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">// Or leave empty for default behavior.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">Properties connectionProperties = new Properties();</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> try (</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> final Statement statement = connection.createStatement();</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> final ResultSet resultSet = statement.executeQuery(query)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> ) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> while (resultSet.next()) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // process result set</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>For a runnable example that includes a query that you might run, see <a href="#examples">Examples</a>.</p><p>It is also possible to use a protocol buffers JDBC connection with Druid, this offer reduced bloat and potential performance |
| improvements for larger result sets. To use it apply the following connection URL instead, everything else remains the same</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">String url = "jdbc:avatica:remote:url=http://localhost:8082/druid/v2/sql/avatica-protobuf/;serialization=protobuf";</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><div class="theme-admonition theme-admonition-info alert alert--info admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>info</div><div class="admonitionContent_S0QG"><p>The protobuf endpoint is also known to work with the official <a href="https://github.com/apache/calcite-avatica-go" target="_blank" rel="noopener noreferrer">Golang Avatica driver</a></p></div></div><p>Table metadata is available over JDBC using <code>connection.getMetaData()</code> or by querying the |
| <a href="/docs/latest/querying/sql-metadata-tables">INFORMATION_SCHEMA tables</a>. For an example of this, see <a href="#get-the-metadata-for-a-datasource">Get the metadata for a datasource</a>.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="connection-stickiness">Connection stickiness<a href="#connection-stickiness" class="hash-link" aria-label="Direct link to Connection stickiness" title="Direct link to Connection stickiness"></a></h2><p>Druid's JDBC server does not share connection state between Brokers. This means that if you're using JDBC and have |
| multiple Druid Brokers, you should either connect to a specific Broker or use a load balancer with sticky sessions |
| enabled. The Druid Router process provides connection stickiness when balancing JDBC requests, and can be used to achieve |
| the necessary stickiness even with a normal non-sticky load balancer. Please see the |
| <a href="/docs/latest/design/router">Router</a> documentation for more details.</p><p>Note that the non-JDBC <a href="/docs/latest/api-reference/sql-api#submit-a-query">JSON over HTTP</a> API is stateless and does not require stickiness.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="dynamic-parameters">Dynamic parameters<a href="#dynamic-parameters" class="hash-link" aria-label="Direct link to Dynamic parameters" title="Direct link to Dynamic parameters"></a></h2><p>You can use <a href="/docs/latest/querying/sql#dynamic-parameters">parameterized queries</a> in JDBC code, as in this example:</p><div class="language-java codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-java codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">PreparedStatement statement = connection.prepareStatement("SELECT COUNT(*) AS cnt FROM druid.foo WHERE dim1 = ? OR dim1 = ?");</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">statement.setString(1, "abc");</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">statement.setString(2, "def");</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">final ResultSet resultSet = statement.executeQuery();</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="examples">Examples<a href="#examples" class="hash-link" aria-label="Direct link to Examples" title="Direct link to Examples"></a></h2><p>The following section contains two complete samples that use the JDBC connector:</p><ul><li><a href="#get-the-metadata-for-a-datasource">Get the metadata for a datasource</a> shows you how to query the <code>INFORMATION_SCHEMA</code> to get metadata like column names. </li><li><a href="#query-data">Query data</a> runs a select query against the datasource.</li></ul><p>You can try out these examples after verifying that you meet the <a href="#prerequisites">prerequisites</a>.</p><p>For more information about the connection options, see <a href="https://calcite.apache.org/avatica/docs/client_reference.html" target="_blank" rel="noopener noreferrer">Client Reference</a>.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="prerequisites">Prerequisites<a href="#prerequisites" class="hash-link" aria-label="Direct link to Prerequisites" title="Direct link to Prerequisites"></a></h3><p>Make sure you meet the following requirements before trying these examples:</p><ul><li><p>A supported <a href="/docs/latest/operations/java">Java version</a></p></li><li><p><a href="https://calcite.apache.org/avatica/downloads/" target="_blank" rel="noopener noreferrer">Avatica JDBC driver</a>. You can add the JAR to your <code>CLASSPATH</code> directly or manage it externally, such as through Maven and a <code>pom.xml</code> file.</p></li><li><p>An available Druid instance. You can use the <code>micro-quickstart</code> configuration described in <a href="/docs/latest/tutorials/">Quickstart (local)</a>. The examples assume that you are using the quickstart, so no authentication or authorization is expected unless explicitly mentioned. </p></li><li><p>The example <code>wikipedia</code> datasource from the quickstart is loaded on your Druid instance. If you have a different datasource loaded, you can still try these examples. You'll have to update the table name and column names to match your datasource.</p></li></ul><h3 class="anchor anchorWithStickyNavbar_LWe7" id="get-the-metadata-for-a-datasource">Get the metadata for a datasource<a href="#get-the-metadata-for-a-datasource" class="hash-link" aria-label="Direct link to Get the metadata for a datasource" title="Direct link to Get the metadata for a datasource"></a></h3><p>Metadata, such as column names, is available either through the <a href="/docs/latest/querying/sql-metadata-tables"><code>INFORMATION_SCHEMA</code></a> table or through <code>connection.getMetaData()</code>. The following example uses the <code>INFORMATION_SCHEMA</code> table to retrieve and print the list of column names for the <code>wikipedia</code> datasource that you loaded during a previous tutorial.</p><div class="language-java codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-java codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">import java.sql.*;</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">import java.util.Properties;</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">public class JdbcListColumns {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> public static void main(String[] args)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // Connect to /druid/v2/sql/avatica/ on your Router. </span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // You can connect to a Broker but must configure connection stickiness if you do. </span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> String url = "jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/";</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> String query = "SELECT COLUMN_NAME,* FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME = 'wikipedia' and TABLE_SCHEMA='druid'";</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // Set any connection context parameters you need here</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // Or leave empty for default behavior.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> Properties connectionProperties = new Properties();</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> try (</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> final Statement statement = connection.createStatement();</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> final ResultSet rs = statement.executeQuery(query)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> ) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> while (rs.next()) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> String columnName = rs.getString("COLUMN_NAME");</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> System.out.println(columnName);</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> } catch (SQLException e) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> throw new RuntimeException(e);</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithStickyNavbar_LWe7" id="query-data">Query data<a href="#query-data" class="hash-link" aria-label="Direct link to Query data" title="Direct link to Query data"></a></h3><p>Now that you know what columns are available, you can start querying the data. The following example queries the datasource named <code>wikipedia</code> for the timestamps and comments from Japan. It also sets the <a href="/docs/latest/querying/sql-query-context">query context parameter</a> <code>sqlTimeZone</code>. Optionally, you can also parameterize queries by using <a href="#dynamic-parameters">dynamic parameters</a>.</p><div class="language-java codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-java codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">import java.sql.*;</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">import java.util.Properties;</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">public class JdbcCountryAndTime {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> public static void main(String[] args)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // Connect to /druid/v2/sql/avatica/ on your Router. </span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // You can connect to a Broker but must configure connection stickiness if you do. </span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> String url = "jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/";</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> //The query you want to run.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> String query = "SELECT __time, isRobot, countryName, comment FROM wikipedia WHERE countryName='Japan'";</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // Set any connection context parameters you need here</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> // Or leave empty for default behavior.</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> Properties connectionProperties = new Properties();</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> try (</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> final Statement statement = connection.createStatement();</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> final ResultSet rs = statement.executeQuery(query)</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> ) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> while (rs.next()) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> Timestamp timeStamp = rs.getTimestamp("__time");</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> String comment = rs.getString("comment");</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> System.out.println(timeStamp);</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> System.out.println(comment);</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> } catch (SQLException e) {</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> throw new RuntimeException(e);</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain" style="display:inline-block"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain"> }</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">}</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div></div></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/latest/api-reference/legacy-metadata-api"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Legacy metadata</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/latest/configuration/"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Configuration reference</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#connection-stickiness" class="table-of-contents__link toc-highlight">Connection stickiness</a></li><li><a href="#dynamic-parameters" class="table-of-contents__link toc-highlight">Dynamic parameters</a></li><li><a href="#examples" class="table-of-contents__link toc-highlight">Examples</a><ul><li><a href="#prerequisites" class="table-of-contents__link toc-highlight">Prerequisites</a></li><li><a href="#get-the-metadata-for-a-datasource" class="table-of-contents__link toc-highlight">Get the metadata for a datasource</a></li><li><a href="#query-data" class="table-of-contents__link toc-highlight">Query data</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="footer"><div class="container container-fluid"><div class="footer__bottom text--center"><div class="margin-bottom--sm"><img src="/img/favicon.png" class="themedImage_ToTc themedImage--light_HNdA footer__logo"><img src="/img/favicon.png" class="themedImage_ToTc themedImage--dark_i4oU footer__logo"></div><div class="footer__copyright">Copyright © 2023 Apache Software Foundation. Except where otherwise noted, licensed under CC BY-SA 4.0. Apache Druid, Druid, and the Druid logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.</div></div></div></footer></div> |
| <script src="/assets/js/runtime~main.26d714fb.js"></script> |
| <script src="/assets/js/main.bd54ee66.js"></script> |
| </body> |
| </html> |
