blob: 59e893ac569fa1dcc30df421b828f4729a8dceda [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!-- NewPage -->
<html lang="en">
<head>
<!-- Generated by javadoc -->
<title>ZOrderByteUtils</title>
<link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
<script type="text/javascript" src="../../../../script.js"></script>
</head>
<body>
<script type="text/javascript"><!--
try {
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="ZOrderByteUtils";
}
}
catch(err) {
}
//-->
var methods = {"i0":9,"i1":9,"i2":9,"i3":9,"i4":9,"i5":9,"i6":9,"i7":9,"i8":9};
var tabs = {65535:["t0","All Methods"],1:["t1","Static Methods"],8:["t4","Concrete Methods"]};
var altColor = "altColor";
var rowColor = "rowColor";
var tableTab = "tableTab";
var activeTableTab = "activeTableTab";
</script>
<noscript>
<div>JavaScript is disabled on your browser.</div>
</noscript>
<!-- ========= START OF TOP NAVBAR ======= -->
<div class="topNav"><a name="navbar.top">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.top.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../org/apache/iceberg/util/WapUtil.html" title="class in org.apache.iceberg.util"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li>Next&nbsp;Class</li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?org/apache/iceberg/util/ZOrderByteUtils.html" target="_top">Frames</a></li>
<li><a href="ZOrderByteUtils.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_top">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_top");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li><a href="#field.summary">Field</a>&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li><a href="#field.detail">Field</a>&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.top">
<!-- -->
</a></div>
<!-- ========= END OF TOP NAVBAR ========= -->
<!-- ======== START OF CLASS DATA ======== -->
<div class="header">
<div class="subTitle">org.apache.iceberg.util</div>
<h2 title="Class ZOrderByteUtils" class="title">Class ZOrderByteUtils</h2>
</div>
<div class="contentContainer">
<ul class="inheritance">
<li>java.lang.Object</li>
<li>
<ul class="inheritance">
<li>org.apache.iceberg.util.ZOrderByteUtils</li>
</ul>
</li>
</ul>
<div class="description">
<ul class="blockList">
<li class="blockList">
<hr>
<br>
<pre>public class <span class="typeNameLabel">ZOrderByteUtils</span>
extends java.lang.Object</pre>
<div class="block">Within Z-Ordering the byte representations of objects being compared must be ordered, this
requires several types to be transformed when converted to bytes. The goal is to map object's
whose byte representation are not lexicographically ordered into representations that are
lexicographically ordered. Bytes produced should be compared lexicographically as unsigned bytes,
big-endian.
<p>All types except for String are stored within an 8 Byte Buffer
<p>Most of these techniques are derived from
https://aws.amazon.com/blogs/database/z-order-indexing-for-multifaceted-queries-in-amazon-dynamodb-part-2/
<p>Some implementation is taken from
https://github.com/apache/hbase/blob/master/hbase-common/src/main/java/org/apache/hadoop/hbase/util/OrderedBytes.java</div>
</li>
</ul>
</div>
<div class="summary">
<ul class="blockList">
<li class="blockList">
<!-- =========== FIELD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="field.summary">
<!-- -->
</a>
<h3>Field Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Field Summary table, listing fields, and an explanation">
<caption><span>Fields</span><span class="tabEnd">&nbsp;</span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Field and Description</th>
</tr>
<tr class="altColor">
<td class="colFirst"><code>static int</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#PRIMITIVE_BUFFER_SIZE">PRIMITIVE_BUFFER_SIZE</a></span></code>&nbsp;</td>
</tr>
</table>
</li>
</ul>
<!-- ========== METHOD SUMMARY =========== -->
<ul class="blockList">
<li class="blockList"><a name="method.summary">
<!-- -->
</a>
<h3>Method Summary</h3>
<table class="memberSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">
<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd">&nbsp;</span></span><span id="t1" class="tableTab"><span><a href="javascript:show(1);">Static Methods</a></span><span class="tabEnd">&nbsp;</span></span><span id="t4" class="tableTab"><span><a href="javascript:show(8);">Concrete Methods</a></span><span class="tabEnd">&nbsp;</span></span></caption>
<tr>
<th class="colFirst" scope="col">Modifier and Type</th>
<th class="colLast" scope="col">Method and Description</th>
</tr>
<tr id="i0" class="altColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#byteTruncateOrFill-byte:A-int-java.nio.ByteBuffer-">byteTruncateOrFill</a></span>(byte[]&nbsp;val,
int&nbsp;length,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">Return a bytebuffer with the given bytes truncated to length, or filled with 0's to length
depending on whether the given bytes are larger or smaller than the given length.</div>
</td>
</tr>
<tr id="i1" class="rowColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#doubleToOrderedBytes-double-java.nio.ByteBuffer-">doubleToOrderedBytes</a></span>(double&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">Doubles are treated the same as floats in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#floatToOrderedBytes-float-java.nio.ByteBuffer-"><code>floatToOrderedBytes(float, ByteBuffer)</code></a></div>
</td>
</tr>
<tr id="i2" class="altColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#floatToOrderedBytes-float-java.nio.ByteBuffer-">floatToOrderedBytes</a></span>(float&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">IEEE 754 : “If two floating-point numbers in the same format are ordered (say, x &lt;
y), they are ordered the same way when their bits are reinterpreted as sign-magnitude
integers.”</div>
</td>
</tr>
<tr id="i3" class="rowColor">
<td class="colFirst"><code>static byte[]</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#interleaveBits-byte:A:A-int-java.nio.ByteBuffer-">interleaveBits</a></span>(byte[][]&nbsp;columnsBinary,
int&nbsp;interleavedSize,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">Interleave bits using a naive loop.</div>
</td>
</tr>
<tr id="i4" class="altColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#intToOrderedBytes-int-java.nio.ByteBuffer-">intToOrderedBytes</a></span>(int&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">Signed ints do not have their bytes in magnitude order because of the sign bit.</div>
</td>
</tr>
<tr id="i5" class="rowColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#longToOrderedBytes-long-java.nio.ByteBuffer-">longToOrderedBytes</a></span>(long&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">Signed longs are treated the same as the signed ints in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#intToOrderedBytes-int-java.nio.ByteBuffer-"><code>intToOrderedBytes(int,
ByteBuffer)</code></a></div>
</td>
</tr>
<tr id="i6" class="altColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#shortToOrderedBytes-short-java.nio.ByteBuffer-">shortToOrderedBytes</a></span>(short&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">Signed shorts are treated the same as the signed ints in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#intToOrderedBytes-int-java.nio.ByteBuffer-"><code>intToOrderedBytes(int,
ByteBuffer)</code></a></div>
</td>
</tr>
<tr id="i7" class="rowColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#stringToOrderedBytes-java.lang.String-int-java.nio.ByteBuffer-java.nio.charset.CharsetEncoder-">stringToOrderedBytes</a></span>(java.lang.String&nbsp;val,
int&nbsp;length,
java.nio.ByteBuffer&nbsp;reuse,
java.nio.charset.CharsetEncoder&nbsp;encoder)</code>
<div class="block">Strings are lexicographically sortable BUT if different byte array lengths will ruin the
Z-Ordering.</div>
</td>
</tr>
<tr id="i8" class="altColor">
<td class="colFirst"><code>static java.nio.ByteBuffer</code></td>
<td class="colLast"><code><span class="memberNameLink"><a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#tinyintToOrderedBytes-byte-java.nio.ByteBuffer-">tinyintToOrderedBytes</a></span>(byte&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</code>
<div class="block">Signed tiny ints are treated the same as the signed ints in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#intToOrderedBytes-int-java.nio.ByteBuffer-"><code>intToOrderedBytes(int,
ByteBuffer)</code></a></div>
</td>
</tr>
</table>
<ul class="blockList">
<li class="blockList"><a name="methods.inherited.from.class.java.lang.Object">
<!-- -->
</a>
<h3>Methods inherited from class&nbsp;java.lang.Object</h3>
<code>clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</code></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="details">
<ul class="blockList">
<li class="blockList">
<!-- ============ FIELD DETAIL =========== -->
<ul class="blockList">
<li class="blockList"><a name="field.detail">
<!-- -->
</a>
<h3>Field Detail</h3>
<a name="PRIMITIVE_BUFFER_SIZE">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>PRIMITIVE_BUFFER_SIZE</h4>
<pre>public static final&nbsp;int PRIMITIVE_BUFFER_SIZE</pre>
<dl>
<dt><span class="seeLabel">See Also:</span></dt>
<dd><a href="../../../../constant-values.html#org.apache.iceberg.util.ZOrderByteUtils.PRIMITIVE_BUFFER_SIZE">Constant Field Values</a></dd>
</dl>
</li>
</ul>
</li>
</ul>
<!-- ============ METHOD DETAIL ========== -->
<ul class="blockList">
<li class="blockList"><a name="method.detail">
<!-- -->
</a>
<h3>Method Detail</h3>
<a name="intToOrderedBytes-int-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>intToOrderedBytes</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;intToOrderedBytes(int&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">Signed ints do not have their bytes in magnitude order because of the sign bit. To fix this,
flip the sign bit so that all negatives are ordered before positives. This essentially shifts
the 0 value so that we don't break our ordering when we cross the new 0 value.</div>
</li>
</ul>
<a name="longToOrderedBytes-long-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>longToOrderedBytes</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;longToOrderedBytes(long&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">Signed longs are treated the same as the signed ints in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#intToOrderedBytes-int-java.nio.ByteBuffer-"><code>intToOrderedBytes(int,
ByteBuffer)</code></a></div>
</li>
</ul>
<a name="shortToOrderedBytes-short-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>shortToOrderedBytes</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;shortToOrderedBytes(short&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">Signed shorts are treated the same as the signed ints in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#intToOrderedBytes-int-java.nio.ByteBuffer-"><code>intToOrderedBytes(int,
ByteBuffer)</code></a></div>
</li>
</ul>
<a name="tinyintToOrderedBytes-byte-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>tinyintToOrderedBytes</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;tinyintToOrderedBytes(byte&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">Signed tiny ints are treated the same as the signed ints in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#intToOrderedBytes-int-java.nio.ByteBuffer-"><code>intToOrderedBytes(int,
ByteBuffer)</code></a></div>
</li>
</ul>
<a name="floatToOrderedBytes-float-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>floatToOrderedBytes</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;floatToOrderedBytes(float&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">IEEE 754 : “If two floating-point numbers in the same format are ordered (say, x &lt;
y), they are ordered the same way when their bits are reinterpreted as sign-magnitude
integers.”
<p>Which means floats can be treated as sign magnitude integers which can then be converted
into lexicographically comparable bytes</div>
</li>
</ul>
<a name="doubleToOrderedBytes-double-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>doubleToOrderedBytes</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;doubleToOrderedBytes(double&nbsp;val,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">Doubles are treated the same as floats in <a href="../../../../org/apache/iceberg/util/ZOrderByteUtils.html#floatToOrderedBytes-float-java.nio.ByteBuffer-"><code>floatToOrderedBytes(float, ByteBuffer)</code></a></div>
</li>
</ul>
<a name="stringToOrderedBytes-java.lang.String-int-java.nio.ByteBuffer-java.nio.charset.CharsetEncoder-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>stringToOrderedBytes</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;stringToOrderedBytes(java.lang.String&nbsp;val,
int&nbsp;length,
java.nio.ByteBuffer&nbsp;reuse,
java.nio.charset.CharsetEncoder&nbsp;encoder)</pre>
<div class="block">Strings are lexicographically sortable BUT if different byte array lengths will ruin the
Z-Ordering. (ZOrder requires that a given column contribute the same number of bytes every
time). This implementation just uses a set size to for all output byte representations.
Truncating longer strings and right padding 0 for shorter strings.</div>
</li>
</ul>
<a name="byteTruncateOrFill-byte:A-int-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockList">
<li class="blockList">
<h4>byteTruncateOrFill</h4>
<pre>public static&nbsp;java.nio.ByteBuffer&nbsp;byteTruncateOrFill(byte[]&nbsp;val,
int&nbsp;length,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">Return a bytebuffer with the given bytes truncated to length, or filled with 0's to length
depending on whether the given bytes are larger or smaller than the given length.</div>
</li>
</ul>
<a name="interleaveBits-byte:A:A-int-java.nio.ByteBuffer-">
<!-- -->
</a>
<ul class="blockListLast">
<li class="blockList">
<h4>interleaveBits</h4>
<pre>public static&nbsp;byte[]&nbsp;interleaveBits(byte[][]&nbsp;columnsBinary,
int&nbsp;interleavedSize,
java.nio.ByteBuffer&nbsp;reuse)</pre>
<div class="block">Interleave bits using a naive loop. Variable length inputs are allowed but to get a consistent
ordering it is required that every column contribute the same number of bytes in each
invocation. Bits are interleaved from all columns that have a bit available at that position.
Once a Column has no more bits to produce it is skipped in the interleaving.</div>
<dl>
<dt><span class="paramLabel">Parameters:</span></dt>
<dd><code>columnsBinary</code> - an array of ordered byte representations of the columns being ZOrdered</dd>
<dd><code>interleavedSize</code> - the number of bytes to use in the output</dd>
<dt><span class="returnLabel">Returns:</span></dt>
<dd>the columnbytes interleaved</dd>
</dl>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<!-- ========= END OF CLASS DATA ========= -->
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<div class="bottomNav"><a name="navbar.bottom">
<!-- -->
</a>
<div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
<a name="navbar.bottom.firstrow">
<!-- -->
</a>
<ul class="navList" title="Navigation">
<li><a href="../../../../overview-summary.html">Overview</a></li>
<li><a href="package-summary.html">Package</a></li>
<li class="navBarCell1Rev">Class</li>
<li><a href="package-tree.html">Tree</a></li>
<li><a href="../../../../deprecated-list.html">Deprecated</a></li>
<li><a href="../../../../index-all.html">Index</a></li>
<li><a href="../../../../help-doc.html">Help</a></li>
</ul>
</div>
<div class="subNav">
<ul class="navList">
<li><a href="../../../../org/apache/iceberg/util/WapUtil.html" title="class in org.apache.iceberg.util"><span class="typeNameLink">Prev&nbsp;Class</span></a></li>
<li>Next&nbsp;Class</li>
</ul>
<ul class="navList">
<li><a href="../../../../index.html?org/apache/iceberg/util/ZOrderByteUtils.html" target="_top">Frames</a></li>
<li><a href="ZOrderByteUtils.html" target="_top">No&nbsp;Frames</a></li>
</ul>
<ul class="navList" id="allclasses_navbar_bottom">
<li><a href="../../../../allclasses-noframe.html">All&nbsp;Classes</a></li>
</ul>
<div>
<script type="text/javascript"><!--
allClassesLink = document.getElementById("allclasses_navbar_bottom");
if(window==top) {
allClassesLink.style.display = "block";
}
else {
allClassesLink.style.display = "none";
}
//-->
</script>
</div>
<div>
<ul class="subNavList">
<li>Summary:&nbsp;</li>
<li>Nested&nbsp;|&nbsp;</li>
<li><a href="#field.summary">Field</a>&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.summary">Method</a></li>
</ul>
<ul class="subNavList">
<li>Detail:&nbsp;</li>
<li><a href="#field.detail">Field</a>&nbsp;|&nbsp;</li>
<li>Constr&nbsp;|&nbsp;</li>
<li><a href="#method.detail">Method</a></li>
</ul>
</div>
<a name="skip.navbar.bottom">
<!-- -->
</a></div>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
</body>
</html>