Google Git
Sign in
apache / druid-website / c64404bcdd987c5711beee2ac61b40c05dbe19e1 / . / docs / 0.15.0-incubating / querying / searchquery.html
blob: b385b42bd7f0aeaf432b440f92139c3b69226c3e [file] [log] [blame]
<!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 | Search Queries</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="search-queries">Search Queries</h1>
<p>A search query returns dimension values that match the search specification.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;queryType&quot;</span><span class="p">:</span> <span class="s2">&quot;search&quot;</span><span class="p">,</span>
<span class="nt">&quot;dataSource&quot;</span><span class="p">:</span> <span class="s2">&quot;sample_datasource&quot;</span><span class="p">,</span>
<span class="nt">&quot;granularity&quot;</span><span class="p">:</span> <span class="s2">&quot;day&quot;</span><span class="p">,</span>
<span class="nt">&quot;searchDimensions&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;dim1&quot;</span><span class="p">,</span>
<span class="s2">&quot;dim2&quot;</span>
<span class="p">],</span>
<span class="nt">&quot;query&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;insensitive_contains&quot;</span><span class="p">,</span>
<span class="nt">&quot;value&quot;</span><span class="p">:</span> <span class="s2">&quot;Ke&quot;</span>
<span class="p">},</span>
<span class="nt">&quot;sort&quot;</span> <span class="p">:</span> <span class="p">{</span>
<span class="nt">&quot;type&quot;</span><span class="p">:</span> <span class="s2">&quot;lexicographic&quot;</span>
<span class="p">},</span>
<span class="nt">&quot;intervals&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;2013-01-01T00:00:00.000/2013-01-03T00:00:00.000&quot;</span>
<span class="p">]</span>
<span class="p">}</span>
</code></pre></div>
<p>There are several main parts to a search query:</p>
<table><thead>
<tr>
<th>property</th>
<th>description</th>
<th>required?</th>
</tr>
</thead><tbody>
<tr>
<td>queryType</td>
<td>This String should always be &quot;search&quot;; this is the first thing Apache Druid (incubating) looks at to figure out how to interpret the query.</td>
<td>yes</td>
</tr>
<tr>
<td>dataSource</td>
<td>A String or Object defining the data source to query, very similar to a table in a relational database. See <a href="../querying/datasource.html">DataSource</a> for more information.</td>
<td>yes</td>
</tr>
<tr>
<td>granularity</td>
<td>Defines the granularity of the query. See <a href="../querying/granularities.html">Granularities</a>.</td>
<td>yes</td>
</tr>
<tr>
<td>filter</td>
<td>See <a href="../querying/filters.html">Filters</a>.</td>
<td>no</td>
</tr>
<tr>
<td>limit</td>
<td>Defines the maximum number per Historical process (parsed as int) of search results to return.</td>
<td>no (default to 1000)</td>
</tr>
<tr>
<td>intervals</td>
<td>A JSON Object representing ISO-8601 Intervals. This defines the time ranges to run the query over.</td>
<td>yes</td>
</tr>
<tr>
<td>searchDimensions</td>
<td>The dimensions to run the search over. Excluding this means the search is run over all dimensions.</td>
<td>no</td>
</tr>
<tr>
<td>query</td>
<td>See <a href="../querying/searchqueryspec.html">SearchQuerySpec</a>.</td>
<td>yes</td>
</tr>
<tr>
<td>sort</td>
<td>An object specifying how the results of the search should be sorted.<br/>Possible types are &quot;lexicographic&quot; (the default sort), &quot;alphanumeric&quot;, &quot;strlen&quot;, and &quot;numeric&quot;.<br/>See <a href="./sorting-orders.html">Sorting Orders</a> for more details.</td>
<td>no</td>
</tr>
<tr>
<td>context</td>
<td>See <a href="../querying/query-context.html">Context</a></td>
<td>no</td>
</tr>
</tbody></table>
<p>The format of the result is:</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2012-01-01T00:00:00.000Z&quot;</span><span class="p">,</span>
<span class="nt">&quot;result&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;dimension&quot;</span><span class="p">:</span> <span class="s2">&quot;dim1&quot;</span><span class="p">,</span>
<span class="nt">&quot;value&quot;</span><span class="p">:</span> <span class="s2">&quot;Ke$ha&quot;</span><span class="p">,</span>
<span class="nt">&quot;count&quot;</span><span class="p">:</span> <span class="mi">3</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;dimension&quot;</span><span class="p">:</span> <span class="s2">&quot;dim2&quot;</span><span class="p">,</span>
<span class="nt">&quot;value&quot;</span><span class="p">:</span> <span class="s2">&quot;Ke$haForPresident&quot;</span><span class="p">,</span>
<span class="nt">&quot;count&quot;</span><span class="p">:</span> <span class="mi">1</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;timestamp&quot;</span><span class="p">:</span> <span class="s2">&quot;2012-01-02T00:00:00.000Z&quot;</span><span class="p">,</span>
<span class="nt">&quot;result&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&quot;dimension&quot;</span><span class="p">:</span> <span class="s2">&quot;dim1&quot;</span><span class="p">,</span>
<span class="nt">&quot;value&quot;</span><span class="p">:</span> <span class="s2">&quot;SomethingThatContainsKe&quot;</span><span class="p">,</span>
<span class="nt">&quot;count&quot;</span><span class="p">:</span> <span class="mi">1</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&quot;dimension&quot;</span><span class="p">:</span> <span class="s2">&quot;dim2&quot;</span><span class="p">,</span>
<span class="nt">&quot;value&quot;</span><span class="p">:</span> <span class="s2">&quot;SomethingElseThatContainsKe&quot;</span><span class="p">,</span>
<span class="nt">&quot;count&quot;</span><span class="p">:</span> <span class="mi">2</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">]</span>
</code></pre></div>
<h3 id="implementation-details">Implementation details</h3>
<h4 id="strategies">Strategies</h4>
<p>Search queries can be executed using two different strategies. The default strategy is determined by the
&quot;druid.query.search.searchStrategy&quot; runtime property on the Broker. This can be overridden using &quot;searchStrategy&quot; in the
query context. If neither the context field nor the property is set, the &quot;useIndexes&quot; strategy will be used.</p>
<ul>
<li><p>&quot;useIndexes&quot; strategy, the default, first categorizes search dimensions into two groups according to their support for
bitmap indexes. And then, it applies index-only and cursor-based execution plans to the group of dimensions supporting
bitmaps and others, respectively. The index-only plan uses only indexes for search query processing. For each dimension,
it reads the bitmap index for each dimension value, evaluates the search predicate, and finally checks the time interval
and filter predicates. For the cursor-based execution plan, please refer to the &quot;cursorOnly&quot; strategy. The index-only
plan shows low performance for the search dimensions of large cardinality which means most values of search dimensions
are unique.</p></li>
<li><p>&quot;cursorOnly&quot; strategy generates a cursor-based execution plan. This plan creates a cursor which reads a row from a
queryableIndexSegment, and then evaluates search predicates. If some filters support bitmap indexes, the cursor can read
only the rows which satisfy those filters, thereby saving I/O cost. However, it might be slow with filters of low selectivity.</p></li>
<li><p>&quot;auto&quot; strategy uses a cost-based planner for choosing an optimal search strategy. It estimates the cost of index-only
and cursor-based execution plans, and chooses the optimal one. Currently, it is not enabled by default due to the overhead
of cost estimation.</p></li>
</ul>
<h4 id="server-configuration">Server configuration</h4>
<p>The following runtime properties apply:</p>
<table><thead>
<tr>
<th>Property</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead><tbody>
<tr>
<td><code>druid.query.search.searchStrategy</code></td>
<td>Default search query strategy.</td>
<td>useIndexes</td>
</tr>
</tbody></table>
<h4 id="query-context">Query context</h4>
<p>The following query context parameters apply:</p>
<table><thead>
<tr>
<th>Property</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td><code>searchStrategy</code></td>
<td>Overrides the value of <code>druid.query.search.searchStrategy</code> for this query.</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>&ensp;·&ensp;
<a href="/use-cases">Use Cases</a>&ensp;·&ensp;
<a href="/druid-powered">Powered by Druid</a>&ensp;·&ensp;
<a href="/docs/latest/">Docs</a>&ensp;·&ensp;
<a href="/community/">Community</a>&ensp;·&ensp;
<a href="/downloads.html">Download</a>&ensp;·&ensp;
<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>&ensp;·&ensp;
<a title="Follow Druid" href="https://twitter.com/druidio" target="_blank"><span class="fab fa-twitter"></span></a>&ensp;·&ensp;
<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.15.0-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>