blob: 88484980b619edd401286eb8177139b495aaa279 [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 | DataSketches Tuple Sketch module</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.20.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="datasketches-tuple-sketch-module">DataSketches Tuple Sketch module</h1>
<p>This module provides Apache Druid (incubating) aggregators based on Tuple sketch from <a href="http://datasketches.github.io/">datasketches</a> library. ArrayOfDoublesSketch sketches extend the functionality of the count-distinct Theta sketches by adding arrays of double values associated with unique keys.</p>
<p>To use this aggregator, make sure you <a href="../../operations/including-extensions.html">include</a> the extension in your config file:</p>
<div class="highlight"><pre><code class="language-text" data-lang="text"><span></span>druid.extensions.loadList=[&quot;druid-datasketches&quot;]
</code></pre></div>
<h3 id="aggregators">Aggregators</h3>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketch&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span> <span class="p">:</span> <span class="err">&lt;output_name&gt;</span><span class="p">,</span>
<span class="nt">&quot;fieldName&quot;</span> <span class="p">:</span> <span class="err">&lt;metric_name&gt;</span><span class="p">,</span>
<span class="nt">&quot;nominalEntries&quot;</span><span class="p">:</span> <span class="err">&lt;number&gt;</span><span class="p">,</span>
<span class="nt">&quot;numberOfValues&quot;</span> <span class="p">:</span> <span class="err">&lt;number&gt;</span><span class="p">,</span>
<span class="nt">&quot;metricColumns&quot;</span> <span class="p">:</span> <span class="err">&lt;array</span> <span class="err">of</span> <span class="err">strings&gt;</span>
<span class="p">}</span>
</code></pre></div>
<table><thead>
<tr>
<th>property</th>
<th>description</th>
<th>required?</th>
</tr>
</thead><tbody>
<tr>
<td>type</td>
<td>This String should always be &quot;arrayOfDoublesSketch&quot;</td>
<td>yes</td>
</tr>
<tr>
<td>name</td>
<td>A String for the output (result) name of the calculation.</td>
<td>yes</td>
</tr>
<tr>
<td>fieldName</td>
<td>A String for the name of the input field.</td>
<td>yes</td>
</tr>
<tr>
<td>nominalEntries</td>
<td>Parameter that determines the accuracy and size of the sketch. Higher k means higher accuracy but more space to store sketches. Must be a power of 2. See the <a href="https://datasketches.github.io/docs/Theta/ThetaErrorTable.html">Theta sketch accuracy</a> for details.</td>
<td>no, defaults to 16384</td>
</tr>
<tr>
<td>numberOfValues</td>
<td>Number of values associated with each distinct key.</td>
<td>no, defaults to 1</td>
</tr>
<tr>
<td>metricCoulumns</td>
<td>If building sketches from raw data, an array of names of the input columns containing numeric vaues to be associated with each distinct key.</td>
<td>no, defaults to empty array</td>
</tr>
</tbody></table>
<h3 id="post-aggregators">Post Aggregators</h3>
<h4 id="estimate-of-the-number-of-distinct-keys">Estimate of the number of distinct keys</h4>
<p>Returns a distinct count estimate from a given ArrayOfDoublesSketch.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchToEstimate&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;field&quot;</span> <span class="p">:</span> <span class="err">&lt;post</span> <span class="err">aggregator</span> <span class="err">that</span> <span class="err">refers</span> <span class="err">to</span> <span class="err">an</span> <span class="err">ArrayOfDoublesSketch</span> <span class="err">(fieldAccess</span> <span class="err">or</span> <span class="err">another</span> <span class="err">post</span> <span class="err">aggregator)&gt;</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="estimate-of-the-number-of-distinct-keys-with-error-bounds">Estimate of the number of distinct keys with error bounds</h4>
<p>Returns a distinct count estimate and error bounds from a given ArrayOfDoublesSketch. The result will be three double values: estimate of the number of distinct keys, lower bound and upper bound. The bounds are provided at the given number of standard deviations (optional, defaults to 1). This must be an integer value of 1, 2 or 3 corresponding to approximately 68.3%, 95.4% and 99.7% confidence intervals.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchToEstimateAndBounds&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;field&quot;</span> <span class="p">:</span> <span class="err">&lt;post</span> <span class="err">aggregator</span> <span class="err">that</span> <span class="err">refers</span> <span class="err">to</span> <span class="err">an</span> <span class="err">ArrayOfDoublesSketch</span> <span class="err">(fieldAccess</span> <span class="err">or</span> <span class="err">another</span> <span class="err">post</span> <span class="err">aggregator)&gt;</span><span class="p">,</span>
<span class="nt">&quot;numStdDevs&quot;</span><span class="p">,</span> <span class="err">&lt;number</span> <span class="err">from</span> <span class="err">1</span> <span class="err">to</span> <span class="err">3&gt;</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="number-of-retained-entries">Number of retained entries</h4>
<p>Returns the number of retained entries from a given ArrayOfDoublesSketch.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchToNumEntries&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;field&quot;</span> <span class="p">:</span> <span class="err">&lt;post</span> <span class="err">aggregator</span> <span class="err">that</span> <span class="err">refers</span> <span class="err">to</span> <span class="err">an</span> <span class="err">ArrayOfDoublesSketch</span> <span class="err">(fieldAccess</span> <span class="err">or</span> <span class="err">another</span> <span class="err">post</span> <span class="err">aggregator)&gt;</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="mean-values-for-each-column">Mean values for each column</h4>
<p>Returns a list of mean values from a given ArrayOfDoublesSketch. The result will be N double values, where N is the number of double values kept in the sketch per key.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchToMeans&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;field&quot;</span> <span class="p">:</span> <span class="err">&lt;post</span> <span class="err">aggregator</span> <span class="err">that</span> <span class="err">refers</span> <span class="err">to</span> <span class="err">a</span> <span class="err">DoublesSketch</span> <span class="err">(fieldAccess</span> <span class="err">or</span> <span class="err">another</span> <span class="err">post</span> <span class="err">aggregator)&gt;</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="variance-values-for-each-column">Variance values for each column</h4>
<p>Returns a list of variance values from a given ArrayOfDoublesSketch. The result will be N double values, where N is the number of double values kept in the sketch per key.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchToVariances&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;field&quot;</span> <span class="p">:</span> <span class="err">&lt;post</span> <span class="err">aggregator</span> <span class="err">that</span> <span class="err">refers</span> <span class="err">to</span> <span class="err">a</span> <span class="err">DoublesSketch</span> <span class="err">(fieldAccess</span> <span class="err">or</span> <span class="err">another</span> <span class="err">post</span> <span class="err">aggregator)&gt;</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="quantiles-sketch-from-a-column">Quantiles sketch from a column</h4>
<p>Returns a quanitles DoublesSketch constructed from a given column of values from a given ArrayOfDoublesSketch using optional parameter k that determines the accuracy and size of the quantiles sketch. See <a href="datasketches-quantiles.html">Quantiles Sketch Module</a></p>
<ul>
<li>The column number is 1-based and is optional (the default is 1).</li>
<li>The parameter k is optional (the default is defined in the sketch library).</li>
<li>The result is a quantiles sketch.</li>
</ul>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchToQuantilesSketch&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;field&quot;</span> <span class="p">:</span> <span class="err">&lt;post</span> <span class="err">aggregator</span> <span class="err">that</span> <span class="err">refers</span> <span class="err">to</span> <span class="err">a</span> <span class="err">DoublesSketch</span> <span class="err">(fieldAccess</span> <span class="err">or</span> <span class="err">another</span> <span class="err">post</span> <span class="err">aggregator)&gt;</span><span class="p">,</span>
<span class="nt">&quot;column&quot;</span> <span class="p">:</span> <span class="err">&lt;number&gt;</span><span class="p">,</span>
<span class="nt">&quot;k&quot;</span> <span class="p">:</span> <span class="err">&lt;parameter</span> <span class="err">that</span> <span class="err">determines</span> <span class="err">the</span> <span class="err">accuracy</span> <span class="err">and</span> <span class="err">size</span> <span class="err">of</span> <span class="err">the</span> <span class="err">quantiles</span> <span class="err">sketch&gt;</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="set-operations">Set Operations</h4>
<p>Returns a result of a specified set operation on the given array of sketches. Supported operations are: union, intersection and set difference (UNION, INTERSECT, NOT).</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchSetOp&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;operation&quot;</span><span class="p">:</span> <span class="err">&lt;</span><span class="s2">&quot;UNION&quot;</span><span class="err">|</span><span class="s2">&quot;INTERSECT&quot;</span><span class="err">|</span><span class="s2">&quot;NOT&quot;</span><span class="err">&gt;</span><span class="p">,</span>
<span class="nt">&quot;fields&quot;</span> <span class="p">:</span> <span class="err">&lt;array</span> <span class="err">of</span> <span class="err">post</span> <span class="err">aggregators</span> <span class="err">to</span> <span class="err">access</span> <span class="err">sketch</span> <span class="err">aggregators</span> <span class="err">or</span> <span class="err">post</span> <span class="err">aggregators</span> <span class="err">to</span> <span class="err">allow</span> <span class="err">arbitrary</span> <span class="err">combination</span> <span class="err">of</span> <span class="err">set</span> <span class="err">operations&gt;</span><span class="p">,</span>
<span class="nt">&quot;nominalEntries&quot;</span> <span class="p">:</span> <span class="err">&lt;parameter</span> <span class="err">that</span> <span class="err">determines</span> <span class="err">the</span> <span class="err">accuracy</span> <span class="err">and</span> <span class="err">size</span> <span class="err">of</span> <span class="err">the</span> <span class="err">sketch&gt;</span><span class="p">,</span>
<span class="nt">&quot;numberOfValues&quot;</span> <span class="p">:</span> <span class="err">&lt;number</span> <span class="err">of</span> <span class="err">values</span> <span class="err">associated</span> <span class="err">with</span> <span class="err">each</span> <span class="err">distinct</span> <span class="err">key&gt;</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="students-t-test">Student&#39;s t-test</h4>
<p>Performs Student&#39;s t-test and returns a list of p-values given two instances of ArrayOfDoublesSketch. The result will be N double values, where N is the number of double values kept in the sketch per key. See <a href="http://commons.apache.org/proper/commons-math/javadocs/api-3.4/org/apache/commons/math3/stat/inference/TTest.html">t-test documentation</a>.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchTTest&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;fields&quot;</span> <span class="p">:</span> <span class="err">&lt;array</span> <span class="err">with</span> <span class="err">two</span> <span class="err">post</span> <span class="err">aggregators</span> <span class="err">to</span> <span class="err">access</span> <span class="err">sketch</span> <span class="err">aggregators</span> <span class="err">or</span> <span class="err">post</span> <span class="err">aggregators</span> <span class="err">referring</span> <span class="err">to</span> <span class="err">an</span> <span class="err">ArrayOfDoublesSketch&gt;</span><span class="p">,</span>
<span class="p">}</span>
</code></pre></div>
<h4 id="sketch-summary">Sketch summary</h4>
<p>Returns a human-readable summary of a given ArrayOfDoublesSketch. This is a string returned by toString() method of the sketch. This can be useful for debugging.</p>
<div class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span>
<span class="nt">&quot;type&quot;</span> <span class="p">:</span> <span class="s2">&quot;arrayOfDoublesSketchToString&quot;</span><span class="p">,</span>
<span class="nt">&quot;name&quot;</span><span class="p">:</span> <span class="err">&lt;output</span> <span class="err">name&gt;</span><span class="p">,</span>
<span class="nt">&quot;field&quot;</span> <span class="p">:</span> <span class="err">&lt;post</span> <span class="err">aggregator</span> <span class="err">that</span> <span class="err">refers</span> <span class="err">to</span> <span class="err">an</span> <span class="err">ArrayOfDoublesSketch</span> <span class="err">(fieldAccess</span> <span class="err">or</span> <span class="err">another</span> <span class="err">post</span> <span class="err">aggregator)&gt;</span>
<span class="p">}</span>
</code></pre></div>
</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.14.1-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>