You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hbase.apache.org by mi...@apache.org on 2015/11/05 00:16:10 UTC
[50/51] [partial] hbase git commit: Put back 0.94 directory
http://git-wip-us.apache.org/repos/asf/hbase/blob/a293c00d/0.94/acid-semantics.html
----------------------------------------------------------------------
diff --git a/0.94/acid-semantics.html b/0.94/acid-semantics.html
new file mode 100644
index 0000000..ff22672
--- /dev/null
+++ b/0.94/acid-semantics.html
@@ -0,0 +1,501 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<!-- Generated by Apache Maven Doxia at 2015-11-03 -->
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <title>HBase -
+
+ Apache HBase (TM) ACID Properties
+ </title>
+ <style type="text/css" media="all">
+ @import url("./css/maven-base.css");
+ @import url("./css/maven-theme.css");
+ @import url("./css/site.css");
+ </style>
+ <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
+ <link rel="shortcut icon" href="/images/favicon.ico" />
+ <meta name="Date-Revision-yyyymmdd" content="20151103" />
+ <meta http-equiv="Content-Language" content="en" />
+ <!--Google Analytics-->
+<script type="text/javascript">
+
+ var _gaq = _gaq || [];
+ _gaq.push(['_setAccount', 'UA-30210968-1']);
+ _gaq.push(['_trackPageview']);
+
+ (function() {
+ var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+ ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+ })();
+
+</script>
+ </head>
+ <body class="composite">
+ <div id="banner">
+ <a href="./" id="bannerLeft">
+ <img src="images/hbase_logo.png" alt="$alt" />
+ </a>
+ <!-- Commented out since we do not use it. St.Ack 20110906
+ -->
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="breadcrumbs">
+ <div class="xright" style="padding-left: 8px; margin-top: -4px;">
+ <form method="GET" action="http://search-hadoop.com/">
+ <input type="text" style="width: 192px; height: 15px; font-size: inherit; border: 1px solid darkgray" name="q" value="Search wiki, mailing lists & more" onfocus="this.value=''"/>
+ <input type="hidden" name="fc_project" value="HBase"/>
+ <button style="height: 20px; width: 60px;">Search</button>
+ </form>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ <div id="leftColumn">
+ <div id="navcolumn">
+
+
+ <h5>Apache HBase Project</h5>
+ <ul>
+ <li class="none">
+ <a href="index.html" title="Overview">Overview</a>
+ </li>
+ <li class="none">
+ <a href="license.html" title="License">License</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/dyn/closer.cgi/hbase/" class="externalLink" title="Downloads">Downloads</a>
+ </li>
+ <li class="none">
+ <a href="https://issues.apache.org/jira/browse/HBASE?report=com.atlassian.jira.plugin.system.project:changelog-panel#selectedTab=com.atlassian.jira.plugin.system.project%3Achangelog-panel" class="externalLink" title="Release Notes">Release Notes</a>
+ </li>
+ <li class="none">
+ <a href="issue-tracking.html" title="Issue Tracking">Issue Tracking</a>
+ </li>
+ <li class="none">
+ <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
+ </li>
+ <li class="none">
+ <a href="source-repository.html" title="Source Repository">Source Repository</a>
+ </li>
+ <li class="none">
+ <a href="https://reviews.apache.org" class="externalLink" title="ReviewBoard">ReviewBoard</a>
+ </li>
+ <li class="none">
+ <a href="team-list.html" title="Team">Team</a>
+ </li>
+ <li class="none">
+ <a href="sponsors.html" title="Thanks">Thanks</a>
+ </li>
+ <li class="none">
+ <a href="http://blogs.apache.org/hbase/" class="externalLink" title="Blog">Blog</a>
+ </li>
+ <li class="none">
+ <a href="resources.html" title="Other resources">Other resources</a>
+ </li>
+ </ul>
+ <h5>0.94 Documentation</h5>
+ <ul>
+ <li class="none">
+ <a href="book/quickstart.html" title="Getting Started">Getting Started</a>
+ </li>
+ <li class="none">
+ <a href="apidocs/index.html" title="API">API</a>
+ </li>
+ <li class="none">
+ <a href="xref/index.html" title="X-Ref">X-Ref</a>
+ </li>
+ <li class="none">
+ <a href="book/book.html" title="Ref Guide (multi-page)">Ref Guide (multi-page)</a>
+ </li>
+ <li class="none">
+ <a href="book.html" title="Ref Guide (single-page)">Ref Guide (single-page)</a>
+ </li>
+ <li class="none">
+ <a href="http://abloz.com/hbase/book.html" class="externalLink" title="中文参考指南(单页)">中文参考指南(单页)</a>
+ </li>
+ <li class="none">
+ <a href="book/faq.html" title="FAQ">FAQ</a>
+ </li>
+ <li class="none">
+ <a href="book.html#other.info" title="Videos/Presentations">Videos/Presentations</a>
+ </li>
+ <li class="none">
+ <a href="http://wiki.apache.org/hadoop/Hbase" class="externalLink" title="Wiki">Wiki</a>
+ </li>
+ <li class="none">
+ <strong>ACID Semantics</strong>
+ </li>
+ <li class="none">
+ <a href="book.html#arch.bulk.load" title="Bulk Loads">Bulk Loads</a>
+ </li>
+ <li class="none">
+ <a href="metrics.html" title="Metrics">Metrics</a>
+ </li>
+ <li class="none">
+ <a href="cygwin.html" title="HBase on Windows">HBase on Windows</a>
+ </li>
+ <li class="none">
+ <a href="replication.html" title="Cluster replication">Cluster replication</a>
+ </li>
+ </ul>
+ <h5>ASF</h5>
+ <ul>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/" class="externalLink" title="Apache Software Foundation">Apache Software Foundation</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How Apache Works">How Apache Works</a>
+ </li>
+ <li class="none">
+ <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsoring Apache">Sponsoring Apache</a>
+ </li>
+ </ul>
+ <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
+ <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
+ </a>
+
+
+ </div>
+ </div>
+ <div id="bodyColumn">
+ <div id="contentBox">
+ <!-- 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="section">
+<h2>About this Document<a name="About_this_Document"></a></h2>
+
+<p>Apache HBase (TM) is not an ACID compliant database. However, it does guarantee certain specific
+ properties.</p>
+
+<p>This specification enumerates the ACID properties of HBase.</p>
+ </div>
+
+<div class="section">
+<h2>Definitions<a name="Definitions"></a></h2>
+
+<p>For the sake of common vocabulary, we define the following terms:</p>
+
+<dl>
+
+<dt>Atomicity</dt>
+
+<dd>an operation is atomic if it either completes entirely or not at all</dd>
+
+
+<dt>Consistency</dt>
+
+<dd>
+ all actions cause the table to transition from one valid state directly to another
+ (eg a row will not disappear during an update, etc)
+ </dd>
+
+
+<dt>Isolation</dt>
+
+<dd>
+ an operation is isolated if it appears to complete independently of any other concurrent transaction
+ </dd>
+
+
+<dt>Durability</dt>
+
+<dd>any update that reports "successful" to the client will not be lost</dd>
+
+
+<dt>Visibility</dt>
+
+<dd>an update is considered visible if any subsequent read will see the update as having been committed</dd>
+ </dl>
+
+<p>
+ The terms <i>must</i> and <i>may</i> are used as specified by RFC 2119.
+ In short, the word "must" implies that, if some case exists where the statement
+ is not true, it is a bug. The word "may" implies that, even if the guarantee
+ is provided in a current release, users should not rely on it.
+ </p>
+ </div>
+
+<div class="section">
+<h2>APIs to consider<a name="APIs_to_consider"></a></h2>
+
+<ul>
+
+<li>Read APIs
+
+<ul>
+
+<li>get</li>
+
+<li>scan</li>
+ </ul>
+ </li>
+
+<li>Write APIs</li>
+
+<ul>
+
+<li>put</li>
+
+<li>batch put</li>
+
+<li>delete</li>
+ </ul>
+
+<li>Combination (read-modify-write) APIs</li>
+
+<ul>
+
+<li>incrementColumnValue</li>
+
+<li>checkAndPut</li>
+ </ul>
+ </ul>
+ </div>
+
+
+<div class="section">
+<h2>Guarantees Provided<a name="Guarantees_Provided"></a></h2>
+
+
+<div class="section">
+<h2>Atomicity<a name="Atomicity"></a></h2>
+
+
+<ol style="list-style-type: decimal">
+
+<li>All mutations are atomic within a row. Any put will either wholely succeed or wholely fail.[3]</li>
+
+<ol style="list-style-type: decimal">
+
+<li>An operation that returns a "success" code has completely succeeded.</li>
+
+<li>An operation that returns a "failure" code has completely failed.</li>
+
+<li>An operation that times out may have succeeded and may have failed. However,
+ it will not have partially succeeded or failed.</li>
+ </ol>
+
+<li> This is true even if the mutation crosses multiple column families within a row.</li>
+
+<li> APIs that mutate several rows will _not_ be atomic across the multiple rows.
+ For example, a multiput that operates on rows 'a','b', and 'c' may return having
+ mutated some but not all of the rows. In such cases, these APIs will return a list
+ of success codes, each of which may be succeeded, failed, or timed out as described above.</li>
+
+<li> The checkAndPut API happens atomically like the typical compareAndSet (CAS) operation
+ found in many hardware architectures.</li>
+
+<li> The order of mutations is seen to happen in a well-defined order for each row, with no
+ interleaving. For example, if one writer issues the mutation "a=1,b=1,c=1" and
+ another writer issues the mutation "a=2,b=2,c=2", the row must either
+ be "a=1,b=1,c=1" or "a=2,b=2,c=2" and must <i>not</i> be something
+ like "a=1,b=2,c=1".</li>
+
+<ol style="list-style-type: decimal">
+
+<li>Please note that this is not true _across rows_ for multirow batch mutations.</li>
+ </ol>
+ </ol>
+ </div>
+
+<div class="section">
+<h2>Consistency and Isolation<a name="Consistency_and_Isolation"></a></h2>
+
+<ol style="list-style-type: decimal">
+
+<li>All rows returned via any access API will consist of a complete row that existed at
+ some point in the table's history.</li>
+
+<li>This is true across column families - i.e a get of a full row that occurs concurrent
+ with some mutations 1,2,3,4,5 will return a complete row that existed at some point in time
+ between mutation i and i+1 for some i between 1 and 5.</li>
+
+<li>The state of a row will only move forward through the history of edits to it.</li>
+ </ol>
+
+
+<div class="section">
+<h2>Consistency of Scans<a name="Consistency_of_Scans"></a></h2>
+
+<p>
+ A scan is <b>not</b> a consistent view of a table. Scans do
+ <b>not</b> exhibit <i>snapshot isolation</i>.
+ </p>
+
+<p>
+ Rather, scans have the following properties:
+ </p>
+
+
+<ol style="list-style-type: decimal">
+
+<li>
+ Any row returned by the scan will be a consistent view (i.e. that version
+ of the complete row existed at some point in time) [1]
+ </li>
+
+<li>
+ A scan will always reflect a view of the data <i>at least as new as</i>
+ the beginning of the scan. This satisfies the visibility guarantees
+ enumerated below.</li>
+
+<ol style="list-style-type: decimal">
+
+<li>For example, if client A writes data X and then communicates via a side
+ channel to client B, any scans started by client B will contain data at least
+ as new as X.</li>
+
+<li>A scan _must_ reflect all mutations committed prior to the construction
+ of the scanner, and _may_ reflect some mutations committed subsequent to the
+ construction of the scanner.</li>
+
+<li>Scans must include <i>all</i> data written prior to the scan (except in
+ the case where data is subsequently mutated, in which case it _may_ reflect
+ the mutation)</li>
+ </ol>
+ </ol>
+
+<p>
+ Those familiar with relational databases will recognize this isolation level as "read committed".
+ </p>
+
+<p>
+ Please note that the guarantees listed above regarding scanner consistency
+ are referring to "transaction commit time", not the "timestamp"
+ field of each cell. That is to say, a scanner started at time <i>t</i> may see edits
+ with a timestamp value greater than <i>t</i>, if those edits were committed with a
+ "forward dated" timestamp before the scanner was constructed.
+ </p>
+ </div>
+ </div>
+
+<div class="section">
+<h2>Visibility<a name="Visibility"></a></h2>
+
+<ol style="list-style-type: decimal">
+
+<li> When a client receives a "success" response for any mutation, that
+ mutation is immediately visible to both that client and any client with whom it
+ later communicates through side channels. [3]</li>
+
+<li> A row must never exhibit so-called "time-travel" properties. That
+ is to say, if a series of mutations moves a row sequentially through a series of
+ states, any sequence of concurrent reads will return a subsequence of those states.</li>
+
+<ol style="list-style-type: decimal">
+
+<li>For example, if a row's cells are mutated using the "incrementColumnValue"
+ API, a client must never see the value of any cell decrease.</li>
+
+<li>This is true regardless of which read API is used to read back the mutation.</li>
+ </ol>
+
+<li> Any version of a cell that has been returned to a read operation is guaranteed to
+ be durably stored.</li>
+ </ol>
+
+ </div>
+
+<div class="section">
+<h2>Durability<a name="Durability"></a></h2>
+
+<ol style="list-style-type: decimal">
+
+<li> All visible data is also durable data. That is to say, a read will never return
+ data that has not been made durable on disk[2]</li>
+
+<li> Any operation that returns a "success" code (eg does not throw an exception)
+ will be made durable.[3]</li>
+
+<li> Any operation that returns a "failure" code will not be made durable
+ (subject to the Atomicity guarantees above)</li>
+
+<li> All reasonable failure scenarios will not affect any of the guarantees of this document.</li>
+
+ </ol>
+ </div>
+
+<div class="section">
+<h2>Tunability<a name="Tunability"></a></h2>
+
+<p>All of the above guarantees must be possible within Apache HBase. For users who would like to trade
+ off some guarantees for performance, HBase may offer several tuning options. For example:</p>
+
+<ul>
+
+<li>Visibility may be tuned on a per-read basis to allow stale reads or time travel.</li>
+
+<li>Durability may be tuned to only flush data to disk on a periodic basis</li>
+ </ul>
+ </div>
+ </div>
+
+<div class="section">
+<h2>More Information<a name="More_Information"></a></h2>
+
+<p>
+ For more information, see the <a href="book.html#client">client architecture</a> or <a href="book.html#datamodel">data model</a> sections in the Apache HBase Reference Guide.
+ </p>
+ </div>
+
+
+<div class="section">
+<h2>Footnotes<a name="Footnotes"></a></h2>
+
+<p>[1] A consistent view is not guaranteed intra-row scanning -- i.e. fetching a portion of
+ a row in one RPC then going back to fetch another portion of the row in a subsequent RPC.
+ Intra-row scanning happens when you set a limit on how many values to return per Scan#next
+ (See <a class="externalLink" href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/client/Scan.html#setBatch(int)">Scan#setBatch(int)</a>).
+ </p>
+
+
+<p>[2] In the context of Apache HBase, "durably on disk" implies an hflush() call on the transaction
+ log. This does not actually imply an fsync() to magnetic media, but rather just that the data has been
+ written to the OS cache on all replicas of the log. In the case of a full datacenter power loss, it is
+ possible that the edits are not truly durable.</p>
+
+<p>[3] Puts will either wholely succeed or wholely fail, provided that they are actually sent
+ to the RegionServer. If the writebuffer is used, Puts will not be sent until the writebuffer is filled
+ or it is explicitly flushed.</p>
+
+ </div>
+
+
+
+ </div>
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ <div id="footer">
+ <div class="xright">
+
+ <span id="publishDate">Last Published: 2015-11-03</span>
+ | <span id="projectVersion">Version: 0.94.27</span>
+
+ </div>
+ <div class="xright">Copyright ©<a href="http://www.apache.org"> 2015
+ <a href="http://www.apache.org/">The Apache Software Foundation</a>.
+ </a>All Rights Reserved. Apache Hadoop, Hadoop, HDFS, HBase and the HBase project logo are trademarks of the Apache Software Foundation.
+ </div>
+ <div class="clear">
+ <hr/>
+ </div>
+ </div>
+ </body>
+</html>