You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kudu.apache.org by to...@apache.org on 2016/07/01 17:11:02 UTC
[02/47] incubator-kudu-site git commit: Publish commit(s) from site
source repo: 6e3145f Update docs for 0.9.1 2119e12 Update version numbers on
releases page to say incubating 9126357 Update links to kudu.apache.org
http://git-wip-us.apache.org/repos/asf/incubator-kudu-site/blob/2d464066/releases/0.9.1/docs/schema_design.html
----------------------------------------------------------------------
diff --git a/releases/0.9.1/docs/schema_design.html b/releases/0.9.1/docs/schema_design.html
new file mode 100644
index 0000000..872787f
--- /dev/null
+++ b/releases/0.9.1/docs/schema_design.html
@@ -0,0 +1,630 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
+ <meta name="description" content="A new open source Apache Hadoop ecosystem project, Apache Kudu (incubating) completes Hadoop's storage layer to enable fast analytics on fast data" />
+ <meta name="author" content="Cloudera" />
+ <title>Apache Kudu (incubating) - Apache Kudu (incubating) Schema Design</title>
+ <!-- Bootstrap core CSS -->
+ <link href="/css/bootstrap.min.css" rel="stylesheet" />
+
+ <!-- Custom styles for this template -->
+ <link href="/css/justified-nav.css" rel="stylesheet" />
+
+ <link href="/css/kudu.css" rel="stylesheet"/>
+ <link href="/css/asciidoc.css" rel="stylesheet"/>
+ <link rel="shortcut icon" href="/img/logo-favicon.ico" />
+ <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css" />
+
+
+
+ <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
+ <!--[if lt IE 9]>
+ <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
+ <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
+ <![endif]-->
+ </head>
+ <body>
+ <!-- Fork me on GitHub -->
+ <a class="fork-me-on-github" href="https://github.com/apache/incubator-kudu"><img src="//aral.github.io/fork-me-on-github-retina-ribbons/right-cerulean@2x.png" alt="Fork me on GitHub" /></a>
+
+ <div class="kudu-site container-fluid">
+ <!-- Static navbar -->
+ <nav class="container-fluid navbar-default">
+ <div class="navbar-header">
+ <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
+ <span class="sr-only">Toggle navigation</span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+
+ <a class="logo" href="/"><img src="/img/logo_small.png" width="80" /></a>
+
+ </div>
+ <div id="navbar" class="navbar-collapse collapse navbar-right">
+ <ul class="nav navbar-nav">
+ <li >
+ <a href="/">Home</a>
+ </li>
+ <li >
+ <a href="/overview.html">Overview</a>
+ </li>
+ <li class="active">
+ <a href="/docs/">Documentation</a>
+ </li>
+ <li >
+ <a href="/releases/">Download</a>
+ </li>
+ <li >
+ <a href="/blog/">Blog</a>
+ </li>
+ <li >
+ <a href="/community.html">Community</a>
+ </li>
+ <li >
+ <a href="/faq.html">FAQ</a>
+ </li>
+ </ul>
+ </div><!--/.nav-collapse -->
+ </nav>
+
+<!--
+
+Licensed 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.
+-->
+
+
+<div class="container">
+ <div class="row">
+ <div class="col-md-9">
+
+<h1>Apache Kudu (incubating) Schema Design</h1>
+ <div id="preamble">
+<div class="sectionbody">
+<div class="paragraph">
+<p>Kudu tables have a structured data model similar to tables in a traditional
+RDBMS. Schema design is critical for achieving the best performance and operational
+stability from Kudu. Every workload is unique, and there is no single schema design
+that is best for every table. This document outlines effective schema design
+philosophies for Kudu, paying particular attention to where they differ from
+approaches used for traditional RDBMS schemas.</p>
+</div>
+<div class="paragraph">
+<p>At a high level, there are three concerns in Kudu schema design:
+<a href="#column-design">column design</a>, <a href="#primary-keys">primary keys</a>, and
+<a href="#data-distribution">data distribution</a>. Of these, only data distribution will
+be a new concept for those familiar with traditional relational databases. The
+next sections discuss <a href="#alter-schema">altering the schema</a> of an existing table,
+and <a href="#known-limitations">known limitations</a> with regard to schema design.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="column-design"><a class="link" href="#column-design">Column Design</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>A Kudu Table consists of one or more columns, each with a predefined type.
+Columns that are not part of the primary key may optionally be nullable.
+Supported column types include:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>boolean</p>
+</li>
+<li>
+<p>8-bit signed integer</p>
+</li>
+<li>
+<p>16-bit signed integer</p>
+</li>
+<li>
+<p>32-bit signed integer</p>
+</li>
+<li>
+<p>64-bit signed integer</p>
+</li>
+<li>
+<p>timestamp</p>
+</li>
+<li>
+<p>single-precision (32-bit) IEEE-754 floating-point number</p>
+</li>
+<li>
+<p>double-precision (64-bit) IEEE-754 floating-point number</p>
+</li>
+<li>
+<p>UTF-8 encoded string</p>
+</li>
+<li>
+<p>binary</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>Kudu takes advantage of strongly-typed columns and a columnar on-disk storage
+format to provide efficient encoding and serialization. To make the most of these
+features, columns must be specified as the appropriate type, rather than
+simulating a 'schemaless' table using string or binary columns for data which
+may otherwise be structured. In addition to encoding, Kudu optionally allows
+compression to be specified on a per-column basis.</p>
+</div>
+<div class="sect2">
+<h3 id="encoding"><a class="link" href="#encoding">Column Encoding</a></h3>
+<div class="paragraph">
+<p>Each column in a Kudu table can be created with an encoding, based on the type
+of the column. Columns use plain encoding by default.</p>
+</div>
+<table class="tableblock frame-all grid-all spread">
+<caption class="title">Table 1. Encoding Types</caption>
+<colgroup>
+<col style="width: 50%;">
+<col style="width: 50%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Column Type</th>
+<th class="tableblock halign-left valign-top">Encoding</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">integer, timestamp</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">plain, bitshuffle, run length</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">float</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">plain, bitshuffle</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">bool</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">plain, dictionary, run length</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">string, binary</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">plain, prefix, dictionary</p></td>
+</tr>
+</tbody>
+</table>
+<div id="plain" class="dlist">
+<dl>
+<dt class="hdlist1">Plain Encoding</dt>
+<dd>
+<p>Data is stored in its natural format. For example, <code>int32</code> values
+are stored as fixed-size 32-bit little-endian integers.</p>
+</dd>
+</dl>
+</div>
+<div id="bitshuffle" class="dlist">
+<dl>
+<dt class="hdlist1">Bitshuffle Encoding</dt>
+<dd>
+<p>Data is rearranged to store the most significant bit of
+every value, followed by the second most significant bit of every value, and so
+on. Finally, the result is LZ4 compressed. Bitshuffle encoding is a good choice for
+columns that have many repeated values, or values that change by small amounts
+when sorted by primary key. The
+<a href="https://github.com/kiyo-masui/bitshuffle">bitshuffle</a> project has a good
+overview of performance and use cases.</p>
+</dd>
+</dl>
+</div>
+<div id="run-length" class="dlist">
+<dl>
+<dt class="hdlist1">Run Length Encoding</dt>
+<dd>
+<p><em>Runs</em> (consecutive repeated values) are compressed in a
+column by storing only the value and the count. Run length encoding is effective
+for columns with many consecutive repeated values when sorted by primary key.</p>
+</dd>
+</dl>
+</div>
+<div id="dictionary" class="dlist">
+<dl>
+<dt class="hdlist1">Dictionary Encoding</dt>
+<dd>
+<p>A dictionary of unique values is built, and each column value
+is encoded as its corresponding index in the dictionary. Dictionary encoding
+is effective for columns with low cardinality. If the column values of a given row set
+are unable to be compressed because the number of unique values is too high, Kudu will
+transparently fall back to plain encoding for that row set. This is evaluated during
+flush.</p>
+</dd>
+</dl>
+</div>
+<div id="prefix" class="dlist">
+<dl>
+<dt class="hdlist1">Prefix Encoding</dt>
+<dd>
+<p>Common prefixes are compressed in consecutive column values. Prefix
+encoding can be effective for values that share common prefixes, or the first
+column of the primary key, since rows are sorted by primary key within tablets.</p>
+</dd>
+</dl>
+</div>
+</div>
+<div class="sect2">
+<h3 id="compression"><a class="link" href="#compression">Column Compression</a></h3>
+<div class="paragraph">
+<p>Kudu allows per-column compression using LZ4, <code>snappy</code>, or <code>zlib</code> compression
+codecs. By default, columns are stored uncompressed. Consider using compression
+if reducing storage space is more important than raw scan performance.</p>
+</div>
+<div class="paragraph">
+<p>Every data set will compress differently, but in general LZ4 has the least effect on
+performance, while <code>zlib</code> will compress to the smallest data sizes.
+Bitshuffle-encoded columns are inherently compressed using LZ4, so it is not
+typically beneficial to apply additional compression on top of this encoding.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="primary-keys"><a class="link" href="#primary-keys">Primary Keys</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Each Kudu table must declare a primary key comprised of one or more columns.
+Primary key columns must be non-nullable, and may not be a boolean or
+floating-point type. Every row in a table must have a unique set of values for
+its primary key columns. As with a traditional RDBMS, primary key
+selection is critical to ensuring performant database operations.</p>
+</div>
+<div class="paragraph">
+<p>Unlike an RDBMS, Kudu does not provide an auto-incrementing column feature, so
+the application must always provide the full primary key during insert or
+ingestion. In addition, Kudu does not allow the primary key values of a row to
+be updated.</p>
+</div>
+<div class="paragraph">
+<p>Within a tablet, rows are stored sorted lexicographically by primary key. Advanced
+schema designs can take advantage of this ordering to achieve good distribution of
+data among tablets, while retaining consistent ordering in intra-tablet scans. See
+<a href="#data-distribution">Data Distribution</a> for more information.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="data-distribution"><a class="link" href="#data-distribution">Data Distribution</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Kudu tables, unlike traditional relational tables, are partitioned into tablets
+and distributed across many tablet servers. A row always belongs to a single
+tablet (and its replicas). The method of assigning rows to tablets is specified
+in a configurable <em>partition schema</em> for each table, during table creation.</p>
+</div>
+<div class="paragraph">
+<p>Choosing a data distribution strategy requires you to understand the data model and
+expected workload of a table. For write-heavy workloads, it is important to
+design the distribution such that writes are spread across tablets in order to
+avoid overloading a single tablet. For workloads involving many short scans, performance
+can be improved if all of the data for the scan is located in the same
+tablet. Understanding these fundamental trade-offs is central to designing an effective
+partition schema.</p>
+</div>
+<div id="no_default_partitioning" class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+<div class="title">No Default Partitioning</div>
+===
+Kudu does not provide a default partitioning strategy when creating tables. It
+is strongly recommended to ensure that new tables have at least as many tablets
+as tablet servers (but Kudu can support many tablets per tablet server).
+===
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>Kudu provides two types of partition schema: <a href="#range-partitioning">range partitioning</a> and
+<a href="#hash-bucketing">hash bucketing</a>. These schema types can be <a href="#hash-and-range">used
+together</a> or independently. Kudu does not yet allow tablets to be split after
+creation, so you must design your partition schema ahead of time to ensure that
+a sufficient number of tablets are created.</p>
+</div>
+<div class="sect2">
+<h3 id="range-partitioning"><a class="link" href="#range-partitioning">Range Partitioning</a></h3>
+<div class="paragraph">
+<p>With range partitioning, rows are distributed into tablets using a totally-ordered
+distribution key. Each tablet is assigned a contiguous segment of the table’s
+distribution keyspace. Tables may be range partitioned on any subset of the
+primary key columns.</p>
+</div>
+<div class="paragraph">
+<p>During table creation, tablet boundaries are specified as a sequence of <em>split
+rows</em>. Consider the following table schema (using SQL syntax for clarity):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-sql" data-lang="sql">CREATE TABLE customers (last_name STRING NOT NULL,
+ first_name STRING NOT NULL,
+ order_count INT32)
+PRIMARY KEY (last_name, first_name)
+DISTRIBUTE BY RANGE (last_name, first_name);</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Specifying the split rows as <code>(("b", ""), ("c", ""), ("d", ""), .., ("z", ""))</code>
+(25 split rows total) will result in the creation of 26 tablets, with each
+tablet containing a range of customer surnames all beginning with a given letter.
+This is an effective partition schema for a workload where customers are inserted
+and updated uniformly by last name, and scans are typically performed over a range
+of surnames.</p>
+</div>
+<div class="paragraph">
+<p>It may make sense to partition a table by range using only a subset of the
+primary key columns, or with a different ordering than the primary key. For
+instance, you can change the above example to specify that the range partition
+should only include the <code>last_name</code> column. In that case, Kudu would guarantee that all
+customers with the same last name would fall into the same tablet, regardless of
+the provided split rows.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="hash-bucketing"><a class="link" href="#hash-bucketing">Hash Bucketing</a></h3>
+<div class="paragraph">
+<p>Hash bucketing distributes rows by hash value into one of many buckets. Each
+tablet is responsible for the rows falling into a single bucket. The number of
+buckets (and therefore tablets), is specified during table creation. Typically,
+all of the primary key columns are used as the columns to hash, but as with range
+partitioning, any subset of the primary key columns can be used.</p>
+</div>
+<div class="paragraph">
+<p>Hash partitioning is an effective strategy to increase the amount of parallelism
+for workloads that would otherwise skew writes into a small number of tablets.
+Consider the following table schema.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-sql" data-lang="sql">CREATE TABLE metrics (
+ host STRING NOT NULL,
+ metric STRING,
+ time TIMESTAMP NOT NULL,
+ measurement DOUBLE,
+ PRIMARY KEY (time, metric, host),
+)</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>If you use range partitioning over the primary key columns, inserts will
+tend to only go to the tablet covering the current time, which limits the
+maximum write throughput to the throughput of a single tablet. If you use hash
+partitioning, you can guarantee a number of parallel writes equal to the number
+of buckets specified when defining the partition schema. The trade-off is that a
+scan over a single time range now must touch each of these tablets, instead of
+(possibly) a single tablet. Hash bucketing can be an effective tool for mitigating
+other types of write skew as well, such as monotonically increasing values.</p>
+</div>
+<div class="paragraph">
+<p>As an advanced optimization, you can create a table with more than one
+hash bucket component, as long as the column sets included in each are disjoint,
+and all hashed columns are part of the primary key. The total number of tablets
+created will be the product of the hash bucket counts. For example, the above
+<code>metrics</code> table could be created with two hash bucket components, one over the
+<code>time</code> column with 4 buckets, and one over the <code>metric</code> and <code>host</code> columns with
+8 buckets. The total number of tablets will be 32. The advantage of using two
+separate hash bucket components is that scans which specify equality constraints
+on the <code>metric</code> and <code>host</code> columns will be able to skip 7/8 of the total
+tablets, leaving a total of just 4 tablets to scan.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="hash-and-range"><a class="link" href="#hash-and-range">Hash Bucketing and Range Partitioning</a></h3>
+<div class="paragraph">
+<p>Hash bucketing can be combined with range partitioning. Adding hash bucketing to
+a range partitioned table has the effect of parallelizing operations that would
+otherwise operate sequentially over the range. The total number of tablets is
+the product of the number of hash buckets and the number of split rows plus one.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="alter-schema"><a class="link" href="#alter-schema">Schema Alterations</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>You can alter a table’s schema in the following ways:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Rename the table</p>
+</li>
+<li>
+<p>Rename, add, or drop columns</p>
+</li>
+<li>
+<p>Rename (but not drop) primary key columns</p>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>You cannot modify the partition schema after table creation.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="known-limitations"><a class="link" href="#known-limitations">Known Limitations</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Kudu currently has some known limitations that may factor into schema design:</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1">Immutable Primary Keys</dt>
+<dd>
+<p>Kudu does not allow you to update the primary key of a
+row after insertion.</p>
+</dd>
+<dt class="hdlist1">Non-alterable Primary Key</dt>
+<dd>
+<p>Kudu does not allow you to alter the primary key
+columns after table creation.</p>
+</dd>
+<dt class="hdlist1">Non-alterable Partition Schema</dt>
+<dd>
+<p>Kudu does not allow you to alter the
+partition schema after table creation.</p>
+</dd>
+<dt class="hdlist1">Partition Pruning</dt>
+<dd>
+<p>When tables use hash buckets, the Java client does not yet
+use scan predicates to prune tablets for scans over these tables. In the future,
+specifying an equality predicate on all columns in the hash bucket component
+will limit the scan to only the tablets corresponding to the hash bucket.</p>
+</dd>
+<dt class="hdlist1">Tablet Splitting</dt>
+<dd>
+<p>You currently cannot split or merge tablets after table
+creation. You must create the appropriate number of tablets in the
+partition schema at table creation. As a workaround, you can copy the contents
+of one table to another by using a <code>CREATE TABLE AS SELECT</code> statement or creating
+an empty table and using an <code>INSERT</code> query with <code>SELECT</code> in the predicate to
+populate the new table.</p>
+</dd>
+</dl>
+</div>
+</div>
+</div>
+ </div>
+ <div class="col-md-3">
+
+ <div id="toc" data-spy="affix" data-offset-top="70">
+ <ul>
+
+ <li>
+
+ <a href="introduction.html">Introducing Kudu</a>
+ </li>
+ <li>
+
+ <a href="release_notes.html">Kudu Release Notes</a>
+ </li>
+ <li>
+
+ <a href="quickstart.html">Getting Started with Kudu</a>
+ </li>
+ <li>
+
+ <a href="installation.html">Installation Guide</a>
+ </li>
+ <li>
+
+ <a href="configuration.html">Configuring Kudu</a>
+ </li>
+ <li>
+
+ <a href="kudu_impala_integration.html">Using Impala with Kudu</a>
+ </li>
+ <li>
+
+ <a href="administration.html">Administering Kudu</a>
+ </li>
+ <li>
+
+ <a href="troubleshooting.html">Troubleshooting Kudu</a>
+ </li>
+ <li>
+
+ <a href="developing.html">Developing Applications with Kudu</a>
+ </li>
+ <li>
+<span class="active-toc">Kudu Schema Design</span>
+ <ul class="sectlevel1">
+<li><a href="#column-design">Column Design</a>
+<ul class="sectlevel2">
+<li><a href="#encoding">Column Encoding</a></li>
+<li><a href="#compression">Column Compression</a></li>
+</ul>
+</li>
+<li><a href="#primary-keys">Primary Keys</a></li>
+<li><a href="#data-distribution">Data Distribution</a>
+<ul class="sectlevel2">
+<li><a href="#range-partitioning">Range Partitioning</a></li>
+<li><a href="#hash-bucketing">Hash Bucketing</a></li>
+<li><a href="#hash-and-range">Hash Bucketing and Range Partitioning</a></li>
+</ul>
+</li>
+<li><a href="#alter-schema">Schema Alterations</a></li>
+<li><a href="#known-limitations">Known Limitations</a></li>
+</ul>
+ </li>
+ <li>
+
+ <a href="transaction_semantics.html">Kudu Transaction Semantics</a>
+ </li>
+ <li>
+
+ <a href="contributing.html">Contributing to Kudu</a>
+ </li>
+ <li>
+
+ <a href="style_guide.html">Kudu Documentation Style Guide</a>
+ </li>
+ <li>
+
+ <a href="configuration_reference.html">Kudu Configuration Reference</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+</div>
+ <footer class="footer">
+ <p class="pull-left">
+ <a href="http://incubator.apache.org"><img src="/img/apache-incubator.png" width="225" height="53" align="right"/></a>
+ </p>
+ <p class="small">
+ Apache Kudu (incubating) is an effort undergoing incubation at the Apache Software
+ Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is
+ required of all newly accepted projects until a further review
+ indicates that the infrastructure, communications, and decision making
+ process have stabilized in a manner consistent with other successful
+ ASF projects. While incubation status is not necessarily a reflection
+ of the completeness or stability of the code, it does indicate that the
+ project has yet to be fully endorsed by the ASF.
+
+ Copyright © 2016 The Apache Software Foundation. Last updated 2016-06-30 15:12:19 PDT
+ </p>
+ </footer>
+ </div>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
+ <script src="/js/bootstrap.js"></script>
+ <script>
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-68448017-1', 'auto');
+ ga('send', 'pageview');
+
+ </script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.1.0/anchor.js"></script>
+ <script>
+ anchors.options = {
+ placement: 'right',
+ visible: 'touch',
+ };
+ anchors.add();
+ </script>
+ </body>
+</html>
+
http://git-wip-us.apache.org/repos/asf/incubator-kudu-site/blob/2d464066/releases/0.9.1/docs/style_guide.html
----------------------------------------------------------------------
diff --git a/releases/0.9.1/docs/style_guide.html b/releases/0.9.1/docs/style_guide.html
new file mode 100644
index 0000000..96914d7
--- /dev/null
+++ b/releases/0.9.1/docs/style_guide.html
@@ -0,0 +1,855 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
+ <meta name="description" content="A new open source Apache Hadoop ecosystem project, Apache Kudu (incubating) completes Hadoop's storage layer to enable fast analytics on fast data" />
+ <meta name="author" content="Cloudera" />
+ <title>Apache Kudu (incubating) - Apache Kudu (incubating) Documentation Style Guide</title>
+ <!-- Bootstrap core CSS -->
+ <link href="/css/bootstrap.min.css" rel="stylesheet" />
+
+ <!-- Custom styles for this template -->
+ <link href="/css/justified-nav.css" rel="stylesheet" />
+
+ <link href="/css/kudu.css" rel="stylesheet"/>
+ <link href="/css/asciidoc.css" rel="stylesheet"/>
+ <link rel="shortcut icon" href="/img/logo-favicon.ico" />
+ <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css" />
+
+
+
+ <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
+ <!--[if lt IE 9]>
+ <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
+ <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
+ <![endif]-->
+ </head>
+ <body>
+ <!-- Fork me on GitHub -->
+ <a class="fork-me-on-github" href="https://github.com/apache/incubator-kudu"><img src="//aral.github.io/fork-me-on-github-retina-ribbons/right-cerulean@2x.png" alt="Fork me on GitHub" /></a>
+
+ <div class="kudu-site container-fluid">
+ <!-- Static navbar -->
+ <nav class="container-fluid navbar-default">
+ <div class="navbar-header">
+ <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
+ <span class="sr-only">Toggle navigation</span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+
+ <a class="logo" href="/"><img src="/img/logo_small.png" width="80" /></a>
+
+ </div>
+ <div id="navbar" class="navbar-collapse collapse navbar-right">
+ <ul class="nav navbar-nav">
+ <li >
+ <a href="/">Home</a>
+ </li>
+ <li >
+ <a href="/overview.html">Overview</a>
+ </li>
+ <li class="active">
+ <a href="/docs/">Documentation</a>
+ </li>
+ <li >
+ <a href="/releases/">Download</a>
+ </li>
+ <li >
+ <a href="/blog/">Blog</a>
+ </li>
+ <li >
+ <a href="/community.html">Community</a>
+ </li>
+ <li >
+ <a href="/faq.html">FAQ</a>
+ </li>
+ </ul>
+ </div><!--/.nav-collapse -->
+ </nav>
+
+<!--
+
+Licensed 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.
+-->
+
+
+<div class="container">
+ <div class="row">
+ <div class="col-md-9">
+
+<h1>Apache Kudu (incubating) Documentation Style Guide</h1>
+ <div id="preamble">
+<div class="sectionbody">
+<div class="paragraph">
+<p>This document gives you the information you need to get started contributing to Kudu
+documentation. For code contribution guidelines, see
+<a href="contributing.html">Contributing to Kudu</a>.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_asciidoc"><a class="link" href="#_asciidoc">Asciidoc</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Kudu documentation is written in <a href="https://en.wikipedia.org/wiki/AsciiDoc">Asciidoc</a>
+and compiled into HTML and output using the <a href="http://asciidoctor.org/">Asciidoctor</a>
+toolchain. This provides several advantages. Among them:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>Asciidoc is a superset of Markdown, so if you already know Markdown you can get
+started right away.</p>
+</li>
+<li>
+<p>Github includes support for Asciidoc in its Atom editor, as well as real-time
+simplified HTML rendering.</p>
+</li>
+<li>
+<p>Patch submissions are small and easy to review.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_code_standards"><a class="link" href="#_code_standards">Code Standards</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Within reason, try to adhere to these standards:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>100 or fewer columns per line</p>
+</li>
+<li>
+<p>2 spaces rather than tabs for indentation</p>
+</li>
+<li>
+<p>No more than 4 nested levels in the documentation if possible: <code>(Document → Chapter
+→ Section → Subsection)</code></p>
+</li>
+<li>
+<p>When possible, provide the language that a code listing is in, using the
+<code>[source,<language>]</code> macro. for example, <code>[source,sql]</code></p>
+</li>
+<li>
+<p>In general, do not indent Asciidoc, as indentation is significant. Code listings
+are one exception.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_building_documentation"><a class="link" href="#_building_documentation">Building Documentation</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>To build the documentation locally, you need the Asciidoctor Ruby application. To build the
+entire Kudu documentation set, change to the <code>docs/</code> directory and run:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlight"><code class="language-bash" data-lang="bash">asciidoctor -d book -D docs *.adoc</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This builds the HTML output in a new <em>docs/</em> directory within the current directory.
+Some content, such as the per-daemon configuration reference files, is not populated
+during a local build.</p>
+</div>
+<div class="paragraph">
+<p>To view the HTML, open <em>docs/index.html</em> in your local browser.</p>
+</div>
+<div class="paragraph">
+<p>You can also build only a single chapter. such as <em>release_notes.adoc</em>, by passing its name instead.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_asciidoc_style_guide"><a class="link" href="#_asciidoc_style_guide">Asciidoc Style Guide</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Asciidoc supports a lot of syntax that we do not need to use. When possible, stick
+with the following, adapted from the
+<a href="https://hbase.apache.org/book.html#_hbase_reference_guide_style_guide_and_cheat_sheet">HBase Reference Guide</a>:</p>
+</div>
+<table class="tableblock frame-all grid-all spread">
+<caption class="title">Table 1. AsciiDoc Cheat Sheet</caption>
+<colgroup>
+<col style="width: 33%;">
+<col style="width: 33%;">
+<col style="width: 33%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Element Type</th>
+<th class="tableblock halign-left valign-top">Desired Rendering</th>
+<th class="tableblock halign-left valign-top">How to do it</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A paragraph</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">a paragraph</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>Just type some text with a blank line at the top and bottom.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Add line breaks within a paragraph without adding blank lines</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Manual line breaks</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>This will break + at the plus sign. Or prefix the whole paragraph with a line containing '[%hardbreaks]'</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Give a title to anything</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Colored italic bold differently-sized text</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+</div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">In-Line Code or commands</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">monospace</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>`text`</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">In-line literal content (things to be typed exactly as shown)</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">bold mono</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>*`typethis`*</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">In-line replaceable content (things to substitute with your own values)</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">bold italic mono</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>*_typesomething_*</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Code blocks with highlighting</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">monospace, highlighted, preserve space</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>[source,java]
+----
+ myAwesomeCode() {
+}
+----</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Code block included from a separate file</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">included just as though it were part of the main file</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>[source,ruby]
+----
+include::path/to/app.rb[]
+----</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Include only part of a separate file</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Similar to Javadoc</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>See <a href="http://asciidoctor.org/docs/user-manual/#by-tagged-regions" class="bare">http://asciidoctor.org/docs/user-manual/#by-tagged-regions</a></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">File names, directory names, new terms</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">italic</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>_hbase-default.xml_</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">External naked URLs</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A link with the URL as link text</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>http://www.google.com</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">External URLs with text</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A link with arbitrary link text</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>link:http://www.google.com[Google]</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Create an internal anchor to cross-reference</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">not rendered</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>[[anchor_name]]</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cross-reference an existing anchor using its default title</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">an internal hyperlink using the element title if available, otherwise using the anchor name</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre><<anchor_name>></pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Cross-reference an existing anchor using custom text</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">an internal hyperlink using arbitrary text</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre><<anchor_name,Anchor Text>></pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A block image</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The image with alt text</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>image::sunset.jpg[Alt Text]</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>(put the image in the src/main/site/resources/images directory)</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">An inline image</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The image with alt text, as part of the text flow</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>image:sunset.jpg [Alt Text]</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>(only one colon)</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Link to a remote image</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">show an image hosted elsewhere</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>image::http://inkscape.org/doc/examples/tux.svg[Tux,250,350]</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>(or <code>image:</code>)</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Add dimensions or a URL to the image</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">depends</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>inside the brackets after the alt text, specify width, height and/or link="http://my_link.com"</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A footnote</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">subscript link which takes you to the footnote</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>Some text.footnote:[The footnote text.]</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A note or warning with no title</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The admonition image followed by the admonition</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>NOTE: My note here</pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>WARNING: My warning here</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A complex note</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The note has a title and/or multiple paragraphs and/or code blocks or lists, etc</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>.The Title
+[NOTE]
+====
+Here is the note text.
+Everything until the second set of four equals signs
+is part of the note.
+----
+some source code
+----
+====</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Bullet lists</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">bullet lists</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>* list item 1</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>(see <a href="http://asciidoctor.org/docs/user-manual/#unordered-lists" class="bare">http://asciidoctor.org/docs/user-manual/#unordered-lists</a>)</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Numbered lists</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">numbered list</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>. list item 2</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>(see <a href="http://asciidoctor.org/docs/user-manual/#ordered-lists" class="bare">http://asciidoctor.org/docs/user-manual/#ordered-lists</a>)</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Checklists</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Checked or unchecked boxes</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>Checked:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>- [*]</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Unchecked:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>- [ ]</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Multiple levels of lists</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">bulleted or numbered or combo</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>. Numbered (1), at top level
+* Bullet (2), nested under 1
+* Bullet (3), nested under 1
+. Numbered (4), at top level
+* Bullet (5), nested under 4
+** Bullet (6), nested under 5
+- [x] Checked (7), at top level</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Labelled lists / variablelists</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">a list item title or summary followed by content</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>Title:: content
+
+Title::
+ content</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">GUI menu cascades</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">bold text with arrows to show levels</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>Use an ASCII arrow.</p>
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>*File -> Print*</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>renders like <strong>File → Print</strong></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Sidebars, quotes, or other blocks of text</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">a block of text, formatted differently from the default</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>Delimited using different delimiters, see <a href="http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary" class="bare">http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary</a>. Some of the examples above use delimiters like ...., ----,====.</p>
+</div>
+<div class="literalblock">
+<div class="content">
+<pre>[example]
+====
+This is an example block.
+====
+
+[source]
+----
+This is a source block.
+----
+
+[note]
+====
+This is a note block.
+====
+
+[quote]
+____
+This is a quote block.
+____</pre>
+</div>
+</div>
+<div class="paragraph">
+<p><strong>If you want to insert literal Asciidoc content that keeps being interpreted, when in doubt, use eight dots as the delimiter at the top and bottom.</strong></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Nested Sections</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">chapter, section, sub-section, etc</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>= Book (or chapter if the chapter can be built alone, see leveloffset below)
+
+== Chapter (or section if the chapter is standalone)
+
+=== Section (or subsection, etc)
+
+==== Subsection</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>and so on up to 6 levels (think carefully about going deeper than 4 levels, maybe you can just titled paragraphs or lists instead). Note that you can include a book inside another book by adding the <code>:leveloffset:+1</code> macro directive directly before your include, and resetting it to 0 directly after. See the <em>book.adoc</em> source for examples, as this is how this guide handles chapters. <strong>Don’t do it for prefaces, glossaries, appendixes, or other special types of chapters.</strong></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Include one file from another</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Content is included as though it were inline</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>include::[/path/to/file.adoc]</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>For plenty of examples. see <em>docs/docs.adoc</em>.</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A table</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">a table</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p>See <a href="http://asciidoctor.org/docs/user-manual/#tables" class="bare">http://asciidoctor.org/docs/user-manual/#tables</a>. Generally rows are separated by newlines and columns by pipes</p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Comment out a single line</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A line is skipped during rendering</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="paragraph">
+<p><code>// This line won’t show up</code></p>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Comment out a block</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">A section of the file is skipped during rendering</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>////
+Nothing between the slashes will show up.
+////</pre>
+</div>
+</div></div></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Highlight text for review</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">text shows up with yellow background</p></td>
+<td class="tableblock halign-left valign-top"><div><div id="toc" class="toc">
+<div id="toctitle">Table of Contents</div>
+
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>Test between #hash marks# is highlighted yellow.</pre>
+</div>
+</div></div></td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+ </div>
+ <div class="col-md-3">
+
+ <div id="toc" data-spy="affix" data-offset-top="70">
+ <ul>
+
+ <li>
+
+ <a href="introduction.html">Introducing Kudu</a>
+ </li>
+ <li>
+
+ <a href="release_notes.html">Kudu Release Notes</a>
+ </li>
+ <li>
+
+ <a href="quickstart.html">Getting Started with Kudu</a>
+ </li>
+ <li>
+
+ <a href="installation.html">Installation Guide</a>
+ </li>
+ <li>
+
+ <a href="configuration.html">Configuring Kudu</a>
+ </li>
+ <li>
+
+ <a href="kudu_impala_integration.html">Using Impala with Kudu</a>
+ </li>
+ <li>
+
+ <a href="administration.html">Administering Kudu</a>
+ </li>
+ <li>
+
+ <a href="troubleshooting.html">Troubleshooting Kudu</a>
+ </li>
+ <li>
+
+ <a href="developing.html">Developing Applications with Kudu</a>
+ </li>
+ <li>
+
+ <a href="schema_design.html">Kudu Schema Design</a>
+ </li>
+ <li>
+
+ <a href="transaction_semantics.html">Kudu Transaction Semantics</a>
+ </li>
+ <li>
+
+ <a href="contributing.html">Contributing to Kudu</a>
+ </li>
+ <li>
+<span class="active-toc">Kudu Documentation Style Guide</span>
+ <ul class="sectlevel1">
+<li><a href="#_asciidoc">Asciidoc</a></li>
+<li><a href="#_code_standards">Code Standards</a></li>
+<li><a href="#_building_documentation">Building Documentation</a></li>
+<li><a href="#_asciidoc_style_guide">Asciidoc Style Guide</a></li>
+</ul>
+ </li>
+ <li>
+
+ <a href="configuration_reference.html">Kudu Configuration Reference</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+</div>
+ <footer class="footer">
+ <p class="pull-left">
+ <a href="http://incubator.apache.org"><img src="/img/apache-incubator.png" width="225" height="53" align="right"/></a>
+ </p>
+ <p class="small">
+ Apache Kudu (incubating) is an effort undergoing incubation at the Apache Software
+ Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is
+ required of all newly accepted projects until a further review
+ indicates that the infrastructure, communications, and decision making
+ process have stabilized in a manner consistent with other successful
+ ASF projects. While incubation status is not necessarily a reflection
+ of the completeness or stability of the code, it does indicate that the
+ project has yet to be fully endorsed by the ASF.
+
+ Copyright © 2016 The Apache Software Foundation. Last updated 2016-06-23 13:53:47 PDT
+ </p>
+ </footer>
+ </div>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
+ <script src="/js/bootstrap.js"></script>
+ <script>
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-68448017-1', 'auto');
+ ga('send', 'pageview');
+
+ </script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.1.0/anchor.js"></script>
+ <script>
+ anchors.options = {
+ placement: 'right',
+ visible: 'touch',
+ };
+ anchors.add();
+ </script>
+ </body>
+</html>
+
http://git-wip-us.apache.org/repos/asf/incubator-kudu-site/blob/2d464066/releases/0.9.1/docs/transaction_semantics.html
----------------------------------------------------------------------
diff --git a/releases/0.9.1/docs/transaction_semantics.html b/releases/0.9.1/docs/transaction_semantics.html
new file mode 100644
index 0000000..34b541f
--- /dev/null
+++ b/releases/0.9.1/docs/transaction_semantics.html
@@ -0,0 +1,597 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="utf-8" />
+ <meta http-equiv="X-UA-Compatible" content="IE=edge" />
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
+ <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
+ <meta name="description" content="A new open source Apache Hadoop ecosystem project, Apache Kudu (incubating) completes Hadoop's storage layer to enable fast analytics on fast data" />
+ <meta name="author" content="Cloudera" />
+ <title>Apache Kudu (incubating) - Transaction Semantics in Apache Kudu (incubating)</title>
+ <!-- Bootstrap core CSS -->
+ <link href="/css/bootstrap.min.css" rel="stylesheet" />
+
+ <!-- Custom styles for this template -->
+ <link href="/css/justified-nav.css" rel="stylesheet" />
+
+ <link href="/css/kudu.css" rel="stylesheet"/>
+ <link href="/css/asciidoc.css" rel="stylesheet"/>
+ <link rel="shortcut icon" href="/img/logo-favicon.ico" />
+ <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.1/css/font-awesome.min.css" />
+
+
+
+ <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
+ <!--[if lt IE 9]>
+ <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
+ <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
+ <![endif]-->
+ </head>
+ <body>
+ <!-- Fork me on GitHub -->
+ <a class="fork-me-on-github" href="https://github.com/apache/incubator-kudu"><img src="//aral.github.io/fork-me-on-github-retina-ribbons/right-cerulean@2x.png" alt="Fork me on GitHub" /></a>
+
+ <div class="kudu-site container-fluid">
+ <!-- Static navbar -->
+ <nav class="container-fluid navbar-default">
+ <div class="navbar-header">
+ <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
+ <span class="sr-only">Toggle navigation</span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </button>
+
+ <a class="logo" href="/"><img src="/img/logo_small.png" width="80" /></a>
+
+ </div>
+ <div id="navbar" class="navbar-collapse collapse navbar-right">
+ <ul class="nav navbar-nav">
+ <li >
+ <a href="/">Home</a>
+ </li>
+ <li >
+ <a href="/overview.html">Overview</a>
+ </li>
+ <li class="active">
+ <a href="/docs/">Documentation</a>
+ </li>
+ <li >
+ <a href="/releases/">Download</a>
+ </li>
+ <li >
+ <a href="/blog/">Blog</a>
+ </li>
+ <li >
+ <a href="/community.html">Community</a>
+ </li>
+ <li >
+ <a href="/faq.html">FAQ</a>
+ </li>
+ </ul>
+ </div><!--/.nav-collapse -->
+ </nav>
+
+<!--
+
+Licensed 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.
+-->
+
+
+<div class="container">
+ <div class="row">
+ <div class="col-md-9">
+
+<h1>Transaction Semantics in Apache Kudu (incubating)</h1>
+ <div id="preamble">
+<div class="sectionbody">
+<div class="sidebarblock">
+<div class="content">
+<div class="paragraph">
+<p>This is a brief introduction to Kudu’s transaction and consistency semantics. For an
+in-depth technical exposition of most of what is mentioned here, and why it is correct,
+see the technical report <a href="#1">[1]</a>.</p>
+</div>
+</div>
+</div>
+<div class="paragraph">
+<p>Kudu’s transactional semantics and architecture are inspired by state-of-the-art
+systems such as Spanner <a href="#2">[2]</a> and Calvin <a href="#3">[3]</a>. Kudu builds upon decades of database
+research. The core philosophy is to make the lives of developers easier by providing transactions with
+simple, strong semantics, without sacrificing performance or the ability to tune to different
+requirements.</p>
+</div>
+<div class="paragraph">
+<p>Kudu is designed to eventually be fully ACID, however, multi-tablet transactions are not
+yet implemented. As such, this discussion focuses on single-tablet write operations, and only
+briefly touches multi-tablet reads. Eventually Kudu will support fully strict-serializable
+semantics. In fact it already does in a limited context, but not all corner cases are covered
+as this is still a work in progress.</p>
+</div>
+<div class="paragraph">
+<p>Kudu currently allows the following operations:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>Write operations</strong> are sets of rows to be inserted, updated, or deleted in the storage
+engine, in a single tablet with multiple replicas. Write operations do not have separate
+"read sets" i.e. they do not scan existing data before performing the write. Each write
+is only concerned with previous state of the rows that are about to change.
+Writes are not "committed" explicitly by the user. Instead, they are committed automatically
+by the system, after completion.</p>
+</li>
+<li>
+<p><strong>Scans</strong> are read operations that can traverse multiple tablets and read information
+with some consistency or correctness guarantees. Scans can perform time-travel reads, i.e.
+the user is able to set a scan timestamp in the past and get back results that reflect
+the state of the storage engine at that point in time.</p>
+</li>
+</ul>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="title">Before We Begin</div>
+<div class="ulist">
+<ul>
+<li>
+<p>The term <em>timestamp</em> is mentioned several times to illustrate the
+functionality, but <em>timestamp</em> is an internal concept mostly invisible to users,
+except when setting timestamp on a <code>KuduScanner</code>.</p>
+</li>
+<li>
+<p>We generally refer to methods and classes of the <em>async java</em> client. While the C++
+client mostly has analogous methods and classes, parity between the APIs is still
+a work in progress. At times, we may refer specifically to the C++ client.</p>
+</li>
+</ul>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_single_tablet_write_operations"><a class="link" href="#_single_tablet_write_operations">Single tablet write operations</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Kudu employs <em>Multiversion Concurrency Control (MVCC)</em> and the <em>Raft consensus</em> algorithm <a href="#4">[4]</a>.
+Each write operation in Kudu must go through the tablet’s leader.</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>The leader acquires all locks for the rows that it will change.</p>
+</li>
+<li>
+<p>The leader assigns the write a timestamp before the write is submitted for
+replication. This timestamp will be the write’s "tag" in MVCC.</p>
+</li>
+<li>
+<p>After a majority of replicas acknowledges the change, the actual rows are changed.</p>
+</li>
+<li>
+<p>After the changes are complete, they are made visible to concurrent writes
+and reads, atomically.</p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>All replicas of a tablet observe the same order of operations and if a write
+operation is assigned timestamp <em>n</em> and changes row <em>x</em>, a second write operation
+at timestamp <em>m > n</em> is guaranteed to see the new value of <em>x</em>.</p>
+</div>
+<div class="paragraph">
+<p>This strict ordering of lock acquisition and timestamp assignment is enforced to be
+consistent across all replicas of a tablet through consensus. Therefore, write operations
+are totally ordered with regard to clock-assigned timestamps, relative to other writes
+in the same tablet. In other words, writes have strict-serializable semantics,
+though in an admittedly limited context. See this
+<a href="http://www.bailis.org/blog/linearizability-versus-serializability">blog post</a>
+for a little more context regarding what these semantics mean.</p>
+</div>
+<div class="paragraph">
+<p>While Isolated and Durable in an ACID sense, write operations are not yet fully Atomic.
+The failure of a single write in a batch operation does not roll back the operation,
+but produces per-row errors.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_writing_to_multiple_tablets"><a class="link" href="#_writing_to_multiple_tablets">Writing to multiple tablets</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Kudu does not yet support transactions that span multiple tablets. However,
+consistent snapshot reads are possible (with caveats in the current implementation)
+as explained below.</p>
+</div>
+<div class="paragraph">
+<p>Writes to a Kudu client are optionally buffered in memory until they are flushed and sent
+to the server. During the client’s session flush, the rows for each tablet are batched
+together, and sent to the tablet server which hosts the leader replica of the tablet.
+Since there are no inter-tablet transactions, each of these batches represents a single,
+independent write operation with its own timestamp.
+However you have the option to impose some constraints on the assigned timestamps
+and on how writes to different tablets can be observed by clients.</p>
+</div>
+<div class="paragraph">
+<p>Kudu, like Spanner, was designed to be externally consistent <a href="#5">[5]</a>, preserving consistency
+even when operations span multiple tablets and even multiple data centers. In practice this
+means that, if a write operation changes item <em>x</em> at tablet <em>A</em>, and a following write
+operation changes item <em>y</em> at tablet <em>B</em>, you might want to enforce that if
+the change to <em>y</em> is observed, the change to <em>x</em> must also be observed. There
+are many examples where this can be important. For example, if Kudu is
+storing clickstreams for further analysis, and two clicks follow each other but
+are stored in different tablets, subsequent clicks should be assigned subsequent
+timestamps so that the causal relationship between them is captured.</p>
+</div>
+<div class="paragraph">
+<div class="title"><code>CLIENT_PROPAGATED</code> Consistency</div>
+<p>Kudu’s default external consistency mode is called <code>CLIENT_PROPAGATED</code>.
+See <a href="#1">[1]</a> for an extensive explanation on how it works. In brief, this mode causes writes
+from <em>a single client</em> to be automatically externally consistent. In this mode, writes are only externally
+consistent from the perspective of a single client. In the clickstream scenario above,
+if the two clicks are submitted by different client instances, the application must
+manually propagate timestamps from one client to the other for the causal relationship
+to be captured.</p>
+</div>
+<div class="paragraph">
+<p><code>CLIENT_PROPAGATED</code> consistency is currently only available on the java client
+and is exposed through the <code>AsyncKuduClient#getLastPropagatedTimestamp()</code> and
+<code>AsyncKuduClient#setLastPropagatedTimestamp()</code> methods.</p>
+</div>
+<div class="paragraph">
+<div class="title"><code>Commit Wait</code> Consistency</div>
+<p>Kudu also implements an experimental implementation of an external consistency
+model used in Google’s Spanner , called <code>Commit Wait</code>. <code>Commit Wait</code> works
+by tightly synchronizing the clocks on all machines in the cluster. Then, when a
+write occurs, timestamps are assigned and the results of the write are not made
+visible until enough time has passed so that no other machine in the cluster could
+possibly assign a lower timestamp to a following write.</p>
+</div>
+<div class="paragraph">
+<p>For the moment, Kudu’s experimental implementation of <code>Commit Wait</code> is only available
+in the java client, by setting <code>KuduSession#setExternalConsistencyMode()</code>
+to <code>COMMIT_WAIT</code>. When using this mode, the latency of writes is tightly
+tied to the accuracy of clocks on all the cluster hosts, and using this mode
+with loose clock synchronization causes writes to take a long time to complete or even time
+out. See <a href="#known_issues">Known Issues and Limitations</a>.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_read_operations_scans"><a class="link" href="#_read_operations_scans">Read Operations (Scans)</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>Scans are read operations performed by clients that may span one or more rows across
+one or more tablets. When a server receives a scan, it takes a snapshot of the MVCC
+state and then proceeds in one of two ways depending on the read mode selected by
+the user by means of the <code>KuduScanner::SetReadMode()</code> method.</p>
+</div>
+<div class="dlist">
+<dl>
+<dt class="hdlist1"><code>READ_LATEST</code></dt>
+<dd>
+<p>This is the default read mode. The server takes a snapshot of
+the MVCC state and proceeds with the read immediately. Reads in this mode only yield
+'Read Committed' isolation.</p>
+</dd>
+<dt class="hdlist1"><code>READ_AT_SNAPSHOT</code></dt>
+<dd>
+<p>In this read mode, scans are consistent and repeatable. A
+timestamp for the snapshot is selected either by the server, or set
+explicitly by the user through <code>KuduScanner::SetSnapshotMicros()</code>. Explicitly setting
+the timestamp is recommended; see <a href="#recommendations">Recommendations</a>. The server waits until this
+timestamp is 'safe' (until all write operations that have a lower timestamp have
+completed and are visible). This delay, coupled with an external consistency method,
+will eventually allow Kudu to have full <code>strict-serializable</code> semantics for reads
+and writes. This is still a work in progress and some anomalies are still possible
+(see <a href="#known_issues">Known Issues and Limitations</a>). Only scans in this mode can be fault-tolerant.</p>
+</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p>Selecting between read modes requires balancing the trade-offs and making a choice
+that fits your workload. For instance, a reporting application that needs to
+scan the entire database might need to perform careful accounting operations, so that
+scan may need to be fault-tolerant, but probably doesn’t require a to-the-microsecond
+up-to-date view of the database. In that case, you might choose <code>READ_AT_SNAPSHOT</code>
+and select a timestamp that is a few seconds in the past when the scan starts. On
+the other hand, a machine learning workload that is not ingesting the whole data
+set and is already statistical in nature might not require the scan to be repeatable,
+so you might choose <code>READ_LATEST</code> instead.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="known_issues"><a class="link" href="#known_issues">Known Issues and Limitations</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>We plan to fix the following issues. Monitor the linked JIRAs for progress.</p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_serialization"><a class="link" href="#_serialization">Serialization</a></h2>
+<div class="sectionbody">
+<div class="paragraph">
+<p>There are several gaps and corner cases that prevent Kudu from being fully strictly-serializable
+in some situations, at the moment. Below are the details and next, some recommendations.</p>
+</div>
+<div class="sect2">
+<h3 id="known_issues_scans"><a class="link" href="#known_issues_scans">Scans</a></h3>
+<div class="ulist">
+<ul>
+<li>
+<p>Support for <code>COMMIT_WAIT</code> is experimental and requires careful tuning of the
+time-synchronization protocol, such as NTP (Network Time Protocol).</p>
+</li>
+<li>
+<p>Support for externally-consistent write modes is only fully available in the Java
+API at this time. (see <a href="https://issues.cloudera.org/browse/KUDU-1187">KUDU-1187</a>)</p>
+</li>
+<li>
+<p>In some rare circumstances, the <code>READ_AT_SNAPSHOT</code> scan mode may yield anomalous,
+non-repeatable reads.</p>
+<div class="ulist">
+<ul>
+<li>
+<p>When scanning a replica at a snapshot, the replica may not have received all the writes
+from the leader and might reply immediately, yielding a non-repeatable read (see <a href="https://issues.cloudera.org/browse/KUDU-798">KUDU-798</a>).</p>
+</li>
+<li>
+<p>On a leader change, scans at a snapshot whose timestamp is beyond the last
+write may also yield non-repeatable reads (see <a href="https://issues.cloudera.org/browse/KUDU-1188">KUDU-1188</a>). See <a href="#recommendations">Recommendations</a> for a workaround.</p>
+</li>
+<li>
+<p>When performing multi-tablet scans without selecting a snapshot timestamp (see <a href="https://issues.cloudera.org/browse/KUDU-1189">KUDU-1189</a>).</p>
+</li>
+</ul>
+</div>
+</li>
+<li>
+<p>Impala scans are currently performed as <code>READ_LATEST</code> and have no consistency
+guarantees.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_writes"><a class="link" href="#_writes">Writes</a></h3>
+<div class="ulist">
+<ul>
+<li>
+<p>When a write fails with a timeout or is aborted, it is possible that it may
+actually be committed. Kudu is currently missing a way to determine if a particular
+timed-out write ever actually succeeded. On a retry, the write may succeed but
+may also generate errors if some rows have already been inserted, or deleted (see <a href="https://issues.cloudera.org/browse/KUDU-568">KUDU-568</a>).</p>
+</li>
+<li>
+<p>When a delete is performed to a row that has already been flushed, and the row is reinserted
+all history is reset (see <a href="https://issues.cloudera.org/browse/KUDU-237">KUDU-237</a>).
+This is not the case for rows that haven’t been flushed yet and still reside in memory.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="recommendations"><a class="link" href="#recommendations">Recommendations</a></h2>
+<div class="sectionbody">
+<div class="ulist">
+<ul>
+<li>
+<p>If repeatable snapshot reads are a requirement, use <code>READ_AT_SNAPSHOT</code>
+with a timestamp that is slightly in the past (between 2-5 seconds, ideally).
+This will circumvent the anomalies described in <a href="#known_issues_scans">Scans</a>. Even when the
+anomalies have been addressed, back-dating the timestamp will always make scans
+faster, since they are unlikely to block.</p>
+</li>
+<li>
+<p>If external consistency is a requirement and you decide to use <code>Commit Wait</code>, the
+time-synchronization protocol needs to be tuned carefully. Each transaction will wait
+2x the maximum clock error at the time of execution, which is usually in the 100 msec.
+to 1 sec. range with the default settings, maybe more. Thus, transactions would take at least
+200 msec. to 2 sec. to complete when using the default settings and may even time out.</p>
+<div class="ulist">
+<ul>
+<li>
+<p>A local server should be used as a time server. We’ve performed experiments using the default
+NTP time source available in a Google Compute Engine data center and were able to obtain
+a reasonable tight max error bound, usually varying between 12-17 milliseconds.</p>
+</li>
+<li>
+<p>The following parameters should be adjusted in <code>/etc/ntp.conf</code> to tighten the maximum error:</p>
+<div class="ulist">
+<ul>
+<li>
+<p><code>server my_server.org iburst minpoll 1 maxpoll 8</code></p>
+</li>
+<li>
+<p><code>tinker dispersion 500</code></p>
+</li>
+<li>
+<p><code>tinker allan 0</code></p>
+</li>
+</ul>
+</div>
+</li>
+</ul>
+</div>
+</li>
+</ul>
+</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
+The above parameters minimize <code>maximum error</code> at the expense of <code>estimated error</code>,
+the latter might be orders of magnitude above it’s "normal" value. These parameters also
+may place a greater load on the time server, since they make the servers poll much more
+frequently.
+</td>
+</tr>
+</table>
+</div>
+<div class="ulist bibliography">
+<div class="title">References</div>
+<ul class="bibliography">
+<li>
+<p><a id="1"></a>[1] David Alves, Todd Lipcon and Vijay Garg. Technical Report: HybridTime - Accessible Global Consistency with High Clock Uncertainty. April, 2014. <a href="http://users.ece.utexas.edu/~garg/pdslab/david/hybrid-time-tech-report-01.pdf" class="bare">http://users.ece.utexas.edu/~garg/pdslab/david/hybrid-time-tech-report-01.pdf</a></p>
+</li>
+<li>
+<p><a id="2"></a>[2] James C. Corbett, Jeffrey Dean, Michael Epstein, Andrew Fikes, Christopher Frost, J. J. Furman, Sanjay Ghemawat, Andrey Gubarev, Christopher Heiser, Peter Hochschild, Wilson Hsieh, Sebastian Kanthak, Eugene Kogan, Hongyi Li, Alexander Lloyd, Sergey Melnik, David Mwaura, David Nagle, Sean Quinlan, Rajesh Rao, Lindsay Rolig, Yasushi Saito, Michal Szymaniak, Christopher Taylor, Ruth Wang, and Dale Woodford. 2012. Spanner: Google’s globally-distributed database. In Proceedings of the 10th USENIX conference on Operating Systems Design and Implementation (OSDI'12). USENIX Association, Berkeley, CA, USA, 251-264.</p>
+</li>
+<li>
+<p><a id="3"></a>[3] Alexander Thomson, Thaddeus Diamond, Shu-Chun Weng, Kun Ren, Philip Shao, and Daniel J. Abadi. 2012. Calvin: fast distributed transactions for partitioned database systems. In Proceedings of the 2012 ACM SIGMOD International Conference on Management of Data (SIGMOD '12). ACM, New York, NY, USA, 1-12. DOI=10.1145/2213836.2213838 <a href="http://doi.acm.org/10.1145/2213836.2213838" class="bare">http://doi.acm.org/10.1145/2213836.2213838</a></p>
+</li>
+<li>
+<p><a id="4"></a>[4] Diego Ongaro and John Ousterhout. 2014. In search of an understandable consensus algorithm. In Proceedings of the 2014 USENIX conference on USENIX Annual Technical Conference (USENIX ATC'14), Garth Gibson and Nickolai Zeldovich (Eds.). USENIX Association, Berkeley, CA, USA, 305-320.</p>
+</li>
+<li>
+<p><a id="5"></a>[5] Kwei-Jay Lin, "Consistency issues in real-time database systems," in System Sciences, 1989. Vol.II: Software Track, Proceedings of the Twenty-Second Annual Hawaii International Conference on , vol.2, no., pp.654-661 vol.2, 3-6 Jan 1989 doi: 10.1109/HICSS.1989.48069</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+ </div>
+ <div class="col-md-3">
+
+ <div id="toc" data-spy="affix" data-offset-top="70">
+ <ul>
+
+ <li>
+
+ <a href="introduction.html">Introducing Kudu</a>
+ </li>
+ <li>
+
+ <a href="release_notes.html">Kudu Release Notes</a>
+ </li>
+ <li>
+
+ <a href="quickstart.html">Getting Started with Kudu</a>
+ </li>
+ <li>
+
+ <a href="installation.html">Installation Guide</a>
+ </li>
+ <li>
+
+ <a href="configuration.html">Configuring Kudu</a>
+ </li>
+ <li>
+
+ <a href="kudu_impala_integration.html">Using Impala with Kudu</a>
+ </li>
+ <li>
+
+ <a href="administration.html">Administering Kudu</a>
+ </li>
+ <li>
+
+ <a href="troubleshooting.html">Troubleshooting Kudu</a>
+ </li>
+ <li>
+
+ <a href="developing.html">Developing Applications with Kudu</a>
+ </li>
+ <li>
+
+ <a href="schema_design.html">Kudu Schema Design</a>
+ </li>
+ <li>
+<span class="active-toc">Kudu Transaction Semantics</span>
+ <ul class="sectlevel1">
+<li><a href="#_single_tablet_write_operations">Single tablet write operations</a></li>
+<li><a href="#_writing_to_multiple_tablets">Writing to multiple tablets</a></li>
+<li><a href="#_read_operations_scans">Read Operations (Scans)</a></li>
+<li><a href="#known_issues">Known Issues and Limitations</a></li>
+<li><a href="#_serialization">Serialization</a>
+<ul class="sectlevel2">
+<li><a href="#known_issues_scans">Scans</a></li>
+<li><a href="#_writes">Writes</a></li>
+</ul>
+</li>
+<li><a href="#recommendations">Recommendations</a></li>
+</ul>
+ </li>
+ <li>
+
+ <a href="contributing.html">Contributing to Kudu</a>
+ </li>
+ <li>
+
+ <a href="style_guide.html">Kudu Documentation Style Guide</a>
+ </li>
+ <li>
+
+ <a href="configuration_reference.html">Kudu Configuration Reference</a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+</div>
+ <footer class="footer">
+ <p class="pull-left">
+ <a href="http://incubator.apache.org"><img src="/img/apache-incubator.png" width="225" height="53" align="right"/></a>
+ </p>
+ <p class="small">
+ Apache Kudu (incubating) is an effort undergoing incubation at the Apache Software
+ Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is
+ required of all newly accepted projects until a further review
+ indicates that the infrastructure, communications, and decision making
+ process have stabilized in a manner consistent with other successful
+ ASF projects. While incubation status is not necessarily a reflection
+ of the completeness or stability of the code, it does indicate that the
+ project has yet to be fully endorsed by the ASF.
+
+ Copyright © 2016 The Apache Software Foundation. Last updated 2016-05-23 22:10:33 PDT
+ </p>
+ </footer>
+ </div>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
+ <script src="/js/bootstrap.js"></script>
+ <script>
+ (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+ m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+ })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
+
+ ga('create', 'UA-68448017-1', 'auto');
+ ga('send', 'pageview');
+
+ </script>
+ <script src="https://cdnjs.cloudflare.com/ajax/libs/anchor-js/3.1.0/anchor.js"></script>
+ <script>
+ anchors.options = {
+ placement: 'right',
+ visible: 'touch',
+ };
+ anchors.add();
+ </script>
+ </body>
+</html>
+