| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content="Apache Druid"> |
| <meta name="keywords" content="druid,kafka,database,analytics,streaming,real-time,real time,apache,open source"> |
| <meta name="author" content="Apache Software Foundation"> |
| |
| <title>Druid | Querying</title> |
| |
| <link rel="alternate" type="application/atom+xml" href="/feed"> |
| <link rel="shortcut icon" href="/img/favicon.png"> |
| |
| <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.7.2/css/all.css" integrity="sha384-fnmOCqbTlWIlj8LyTjo7mOUStjsKC4pOpQbqyi7RrhN7udi9RwhKkMHpvLbHG9Sr" crossorigin="anonymous"> |
| |
| <link href='//fonts.googleapis.com/css?family=Open+Sans+Condensed:300,700,300italic|Open+Sans:300italic,400italic,600italic,400,300,600,700' rel='stylesheet' type='text/css'> |
| |
| <link rel="stylesheet" href="/css/bootstrap-pure.css?v=1.1"> |
| <link rel="stylesheet" href="/css/base.css?v=1.1"> |
| <link rel="stylesheet" href="/css/header.css?v=1.1"> |
| <link rel="stylesheet" href="/css/footer.css?v=1.1"> |
| <link rel="stylesheet" href="/css/syntax.css?v=1.1"> |
| <link rel="stylesheet" href="/css/docs.css?v=1.1"> |
| |
| <script> |
| (function() { |
| var cx = '000162378814775985090:molvbm0vggm'; |
| var gcse = document.createElement('script'); |
| gcse.type = 'text/javascript'; |
| gcse.async = true; |
| gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + |
| '//cse.google.com/cse.js?cx=' + cx; |
| var s = document.getElementsByTagName('script')[0]; |
| s.parentNode.insertBefore(gcse, s); |
| })(); |
| </script> |
| |
| |
| </head> |
| |
| <body> |
| <!-- Start page_header include --> |
| <script src="//ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js"></script> |
| |
| <div class="top-navigator"> |
| <div class="container"> |
| <div class="left-cont"> |
| <a class="logo" href="/"><span class="druid-logo"></span></a> |
| </div> |
| <div class="right-cont"> |
| <ul class="links"> |
| <li class=""><a href="/technology">Technology</a></li> |
| <li class=""><a href="/use-cases">Use Cases</a></li> |
| <li class=""><a href="/druid-powered">Powered By</a></li> |
| <li class=""><a href="/docs/latest/design/">Docs</a></li> |
| <li class=""><a href="/community/">Community</a></li> |
| <li class="header-dropdown"> |
| <a>Apache</a> |
| <div class="header-dropdown-menu"> |
| <a href="https://www.apache.org/" target="_blank">Foundation</a> |
| <a href="https://www.apache.org/events/current-event" target="_blank">Events</a> |
| <a href="https://www.apache.org/licenses/" target="_blank">License</a> |
| <a href="https://www.apache.org/foundation/thanks.html" target="_blank">Thanks</a> |
| <a href="https://www.apache.org/security/" target="_blank">Security</a> |
| <a href="https://www.apache.org/foundation/sponsorship.html" target="_blank">Sponsorship</a> |
| </div> |
| </li> |
| <li class=" button-link"><a href="/downloads.html">Download</a></li> |
| </ul> |
| </div> |
| </div> |
| <div class="action-button menu-icon"> |
| <span class="fa fa-bars"></span> MENU |
| </div> |
| <div class="action-button menu-icon-close"> |
| <span class="fa fa-times"></span> MENU |
| </div> |
| </div> |
| |
| <script type="text/javascript"> |
| var $menu = $('.right-cont'); |
| var $menuIcon = $('.menu-icon'); |
| var $menuIconClose = $('.menu-icon-close'); |
| |
| function showMenu() { |
| $menu.fadeIn(100); |
| $menuIcon.fadeOut(100); |
| $menuIconClose.fadeIn(100); |
| } |
| |
| $menuIcon.click(showMenu); |
| |
| function hideMenu() { |
| $menu.fadeOut(100); |
| $menuIconClose.fadeOut(100); |
| $menuIcon.fadeIn(100); |
| } |
| |
| $menuIconClose.click(hideMenu); |
| |
| $(window).resize(function() { |
| if ($(window).width() >= 840) { |
| $menu.fadeIn(100); |
| $menuIcon.fadeOut(100); |
| $menuIconClose.fadeOut(100); |
| } |
| else { |
| $menu.fadeOut(100); |
| $menuIcon.fadeIn(100); |
| $menuIconClose.fadeOut(100); |
| } |
| }); |
| </script> |
| |
| <!-- Stop page_header include --> |
| |
| |
| <div class="container doc-container"> |
| |
| |
| |
| |
| <p> Looking for the <a href="/docs/0.19.0/">latest stable documentation</a>?</p> |
| |
| |
| <div class="row"> |
| <div class="col-md-9 doc-content"> |
| <p> |
| <a class="btn btn-default btn-xs visible-xs-inline-block visible-sm-inline-block" href="#toc">Table of Contents</a> |
| </p> |
| <!-- |
| ~ Licensed to the Apache Software Foundation (ASF) under one |
| ~ or more contributor license agreements. See the NOTICE file |
| ~ distributed with this work for additional information |
| ~ regarding copyright ownership. The ASF licenses this file |
| ~ to you under the Apache License, Version 2.0 (the |
| ~ "License"); you may not use this file except in compliance |
| ~ with the License. You may obtain a copy of the License at |
| ~ |
| ~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~ |
| ~ Unless required by applicable law or agreed to in writing, |
| ~ software distributed under the License is distributed on an |
| ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~ KIND, either express or implied. See the License for the |
| ~ specific language governing permissions and limitations |
| ~ under the License. |
| --> |
| |
| <h1 id="querying">Querying</h1> |
| |
| <p>Apache Druid (incubating) queries are made using an HTTP REST style request to queryable processes (<a href="../design/broker.html">Broker</a>, |
| <a href="../design/historical.html">Historical</a>. <a href="../design/peons.html">Peons</a>) that are running stream ingestion tasks can also accept queries. The |
| query is expressed in JSON and each of these process types expose the same |
| REST query interface. For normal Druid operations, queries should be issued to the Broker processes. Queries can be posted |
| to the queryable processes like this -</p> |
| <div class="highlight"><pre><code class="language-bash" data-lang="bash"><span></span> curl -X POST <span class="s1">'<queryable_host>:<port>/druid/v2/?pretty'</span> -H <span class="s1">'Content-Type:application/json'</span> -H <span class="s1">'Accept:application/json'</span> -d @<query_json_file> |
| </code></pre></div> |
| <p>Druid's native query language is JSON over HTTP, although many members of the community have contributed different |
| <a href="../development/libraries.html">client libraries</a> in other languages to query Druid. </p> |
| |
| <p>The Content-Type/Accept Headers can also take 'application/x-jackson-smile'.</p> |
| <div class="highlight"><pre><code class="language-bash" data-lang="bash"><span></span> curl -X POST <span class="s1">'<queryable_host>:<port>/druid/v2/?pretty'</span> -H <span class="s1">'Content-Type:application/json'</span> -H <span class="s1">'Accept:application/x-jackson-smile'</span> -d @<query_json_file> |
| </code></pre></div> |
| <p>Note: If Accept header is not provided, it defaults to value of 'Content-Type' header.</p> |
| |
| <p>Druid's native query is relatively low level, mapping closely to how computations are performed internally. Druid queries |
| are designed to be lightweight and complete very quickly. This means that for more complex analysis, or to build |
| more complex visualizations, multiple Druid queries may be required.</p> |
| |
| <h2 id="available-queries">Available Queries</h2> |
| |
| <p>Druid has numerous query types for various use cases. Queries are composed of various JSON properties and Druid has different types of queries for different use cases. The documentation for the various query types describe all the JSON properties that can be set.</p> |
| |
| <h3 id="aggregation-queries">Aggregation Queries</h3> |
| |
| <ul> |
| <li><a href="../querying/timeseriesquery.html">Timeseries</a></li> |
| <li><a href="../querying/topnquery.html">TopN</a></li> |
| <li><a href="../querying/groupbyquery.html">GroupBy</a></li> |
| </ul> |
| |
| <h3 id="metadata-queries">Metadata Queries</h3> |
| |
| <ul> |
| <li><a href="../querying/timeboundaryquery.html">Time Boundary</a></li> |
| <li><a href="../querying/segmentmetadataquery.html">Segment Metadata</a></li> |
| <li><a href="../querying/datasourcemetadataquery.html">Datasource Metadata</a></li> |
| </ul> |
| |
| <h3 id="search-queries">Search Queries</h3> |
| |
| <ul> |
| <li><a href="../querying/searchquery.html">Search</a></li> |
| </ul> |
| |
| <h2 id="which-query-should-i-use">Which Query Should I Use?</h2> |
| |
| <p>Where possible, we recommend using <a href="">Timeseries</a> and <a href="">TopN</a> queries instead of <a href="">GroupBy</a>. GroupBy is the most flexible Druid query, but also has the poorest performance. |
| Timeseries are significantly faster than groupBy queries for aggregations that don't require grouping over dimensions. For grouping and sorting over a single dimension, |
| topN queries are much more optimized than groupBys.</p> |
| |
| <h2 id="query-cancellation">Query Cancellation</h2> |
| |
| <p>Queries can be cancelled explicitly using their unique identifier. If the |
| query identifier is set at the time of query, or is otherwise known, the following |
| endpoint can be used on the Broker or Router to cancel the query.</p> |
| <div class="highlight"><pre><code class="language-sh" data-lang="sh"><span></span>DELETE /druid/v2/<span class="o">{</span>queryId<span class="o">}</span> |
| </code></pre></div> |
| <p>For example, if the query ID is <code>abc123</code>, the query can be cancelled as follows:</p> |
| <div class="highlight"><pre><code class="language-sh" data-lang="sh"><span></span>curl -X DELETE <span class="s2">"http://host:port/druid/v2/abc123"</span> |
| </code></pre></div> |
| <h2 id="query-errors">Query Errors</h2> |
| |
| <p>If a query fails, you will get an HTTP 500 response containing a JSON object with the following structure:</p> |
| <div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span> |
| <span class="nt">"error"</span> <span class="p">:</span> <span class="s2">"Query timeout"</span><span class="p">,</span> |
| <span class="nt">"errorMessage"</span> <span class="p">:</span> <span class="s2">"Timeout waiting for task."</span><span class="p">,</span> |
| <span class="nt">"errorClass"</span> <span class="p">:</span> <span class="s2">"java.util.concurrent.TimeoutException"</span><span class="p">,</span> |
| <span class="nt">"host"</span> <span class="p">:</span> <span class="s2">"druid1.example.com:8083"</span> |
| <span class="p">}</span> |
| </code></pre></div> |
| <p>The fields in the response are:</p> |
| |
| <table><thead> |
| <tr> |
| <th>field</th> |
| <th>description</th> |
| </tr> |
| </thead><tbody> |
| <tr> |
| <td>error</td> |
| <td>A well-defined error code (see below).</td> |
| </tr> |
| <tr> |
| <td>errorMessage</td> |
| <td>A free-form message with more information about the error. May be null.</td> |
| </tr> |
| <tr> |
| <td>errorClass</td> |
| <td>The class of the exception that caused this error. May be null.</td> |
| </tr> |
| <tr> |
| <td>host</td> |
| <td>The host on which this error occurred. May be null.</td> |
| </tr> |
| </tbody></table> |
| |
| <p>Possible codes for the <em>error</em> field include:</p> |
| |
| <table><thead> |
| <tr> |
| <th>code</th> |
| <th>description</th> |
| </tr> |
| </thead><tbody> |
| <tr> |
| <td><code>Query timeout</code></td> |
| <td>The query timed out.</td> |
| </tr> |
| <tr> |
| <td><code>Query interrupted</code></td> |
| <td>The query was interrupted, possibly due to JVM shutdown.</td> |
| </tr> |
| <tr> |
| <td><code>Query cancelled</code></td> |
| <td>The query was cancelled through the query cancellation API.</td> |
| </tr> |
| <tr> |
| <td><code>Resource limit exceeded</code></td> |
| <td>The query exceeded a configured resource limit (e.g. groupBy maxResults).</td> |
| </tr> |
| <tr> |
| <td><code>Unauthorized request.</code></td> |
| <td>The query was denied due to security policy. Either the user was not recognized, or the user was recognized but does not have access to the requested resource.</td> |
| </tr> |
| <tr> |
| <td><code>Unknown exception</code></td> |
| <td>Some other exception occurred. Check errorMessage and errorClass for details, although keep in mind that the contents of those fields are free-form and may change from release to release.</td> |
| </tr> |
| </tbody></table> |
| |
| </div> |
| <div class="col-md-3"> |
| <div class="searchbox"> |
| <gcse:searchbox-only></gcse:searchbox-only> |
| </div> |
| <div id="toc" class="nav toc hidden-print"> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <!-- Start page_footer include --> |
| <footer class="druid-footer"> |
| <div class="container"> |
| <div class="text-center"> |
| <p> |
| <a href="/technology">Technology</a> ·  |
| <a href="/use-cases">Use Cases</a> ·  |
| <a href="/druid-powered">Powered by Druid</a> ·  |
| <a href="/docs/latest/">Docs</a> ·  |
| <a href="/community/">Community</a> ·  |
| <a href="/downloads.html">Download</a> ·  |
| <a href="/faq">FAQ</a> |
| </p> |
| </div> |
| <div class="text-center"> |
| <a title="Join the user group" href="https://groups.google.com/forum/#!forum/druid-user" target="_blank"><span class="fa fa-comments"></span></a> ·  |
| <a title="Follow Druid" href="https://twitter.com/druidio" target="_blank"><span class="fab fa-twitter"></span></a> ·  |
| <a title="GitHub" href="https://github.com/apache/druid" target="_blank"><span class="fab fa-github"></span></a> |
| </div> |
| <div class="text-center license"> |
| Copyright © 2020 <a href="https://www.apache.org/" target="_blank">Apache Software Foundation</a>.<br> |
| Except where otherwise noted, licensed under <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>.<br> |
| 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> |
| </footer> |
| |
| <script async src="https://www.googletagmanager.com/gtag/js?id=UA-131010415-1"></script> |
| <script> |
| window.dataLayer = window.dataLayer || []; |
| function gtag(){dataLayer.push(arguments);} |
| gtag('js', new Date()); |
| gtag('config', 'UA-131010415-1'); |
| </script> |
| <script> |
| function trackDownload(type, url) { |
| ga('send', 'event', 'download', type, url); |
| } |
| </script> |
| <script src="//code.jquery.com/jquery.min.js"></script> |
| <script src="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script> |
| <script src="/assets/js/druid.js"></script> |
| <!-- stop page_footer include --> |
| |
| |
| <script> |
| $(function() { |
| $(".toc").load("/docs/0.14.2-incubating/toc.html"); |
| |
| // There is no way to tell when .gsc-input will be async loaded into the page so just try to set a placeholder until it works |
| var tries = 0; |
| var timer = setInterval(function() { |
| tries++; |
| if (tries > 300) clearInterval(timer); |
| var searchInput = $('input.gsc-input'); |
| if (searchInput.length) { |
| searchInput.attr('placeholder', 'Search'); |
| clearInterval(timer); |
| } |
| }, 100); |
| }); |
| </script> |
| </body> |
| </html> |
