acid-semantics.html

   1 <!DOCTYPE html>
   2 <!--
   3  | Generated by Apache Maven Doxia Site Renderer 1.6
   4  | Rendered using Apache Maven Fluido Skin 1.5-HBASE
   5 -->
   6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   7   <head>
   8     <meta charset="UTF-8" />
   9     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  10     <meta name="Date-Revision-yyyymmdd" content="20180311" />
  11     <meta http-equiv="Content-Language" content="en" />
  12     <title>Apache HBase &#x2013;
  13       Apache HBase (TM) ACID Properties
  14     </title>
  15     <link rel="stylesheet" href="./css/apache-maven-fluido-1.5-HBASE.min.css" />
  16     <link rel="stylesheet" href="./css/site.css" />
  17     <link rel="stylesheet" href="./css/print.css" media="print" />
  18
  19
  20     <script type="text/javascript" src="./js/apache-maven-fluido-1.5-HBASE.min.js"></script>
  21
  22
  23
  24 <meta name="viewport" content="width=device-width, initial-scale=1.0"></meta>
  25
  26
  27 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/2.3.2/css/bootstrap-responsive.min.css"/>
  28
  29
  30 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/styles/github.min.css"/>
  31
  32
  33 <link rel="stylesheet" href="css/site.css"/>
  34
  35
  36 <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/8.9.1/highlight.min.js"></script>
  37
  38                   </head>
  39         <body class="topBarEnabled">
  40
  41
  42
  43
  44
  45     <div id="topbar" class="navbar navbar-fixed-top ">
  46       <div class="navbar-inner">
  47                                   <div class="container">
  48                 <a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar">
  49                   <span class="icon-bar"></span>
  50                   <span class="icon-bar"></span>
  51                   <span class="icon-bar"></span>
  52                 </a>
  53                 <div class="nav-collapse">
  54
  55                                 <ul class="nav">
  56                           <li class="dropdown">
  57         <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache HBase Project <b class="caret"></b></a>
  58         <ul class="dropdown-menu">
  59
  60                       <li>      <a href="index.html"  title="Overview">Overview</a>
  61 </li>
  62
  63                       <li>      <a href="license.html"  title="License">License</a>
  64 </li>
  65
  66                       <li>      <a href="http://www.apache.org/dyn/closer.cgi/hbase/"  title="Downloads">Downloads</a>
  67 </li>
  68
  69                       <li>      <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"  title="Release Notes">Release Notes</a>
  70 </li>
  71
  72                       <li>      <a href="coc.html"  title="Code Of Conduct">Code Of Conduct</a>
  73 </li>
  74
  75                       <li>      <a href="http://blogs.apache.org/hbase/"  title="Blog">Blog</a>
  76 </li>
  77
  78                       <li>      <a href="mail-lists.html"  title="Mailing Lists">Mailing Lists</a>
  79 </li>
  80
  81                       <li>      <a href="team-list.html"  title="Team">Team</a>
  82 </li>
  83
  84                       <li>      <a href="https://reviews.apache.org/"  title="ReviewBoard">ReviewBoard</a>
  85 </li>
  86
  87                       <li>      <a href="sponsors.html"  title="Thanks">Thanks</a>
  88 </li>
  89
  90                       <li>      <a href="poweredbyhbase.html"  title="Powered by HBase">Powered by HBase</a>
  91 </li>
  92
  93                       <li>      <a href="resources.html"  title="Other resources">Other resources</a>
  94 </li>
  95                           </ul>
  96       </li>
  97                 <li class="dropdown">
  98         <a href="#" class="dropdown-toggle" data-toggle="dropdown">Project Information <b class="caret"></b></a>
  99         <ul class="dropdown-menu">
 100
 101                       <li>      <a href="project-summary.html"  title="Project Summary">Project Summary</a>
 102 </li>
 103
 104                       <li>      <a href="dependency-info.html"  title="Dependency Information">Dependency Information</a>
 105 </li>
 106
 107                       <li>      <a href="team-list.html"  title="Team">Team</a>
 108 </li>
 109
 110                       <li>      <a href="source-repository.html"  title="Source Repository">Source Repository</a>
 111 </li>
 112
 113                       <li>      <a href="issue-tracking.html"  title="Issue Tracking">Issue Tracking</a>
 114 </li>
 115
 116                       <li>      <a href="dependency-management.html"  title="Dependency Management">Dependency Management</a>
 117 </li>
 118
 119                       <li>      <a href="dependencies.html"  title="Dependencies">Dependencies</a>
 120 </li>
 121
 122                       <li>      <a href="dependency-convergence.html"  title="Dependency Convergence">Dependency Convergence</a>
 123 </li>
 124
 125                       <li>      <a href="integration.html"  title="Continuous Integration">Continuous Integration</a>
 126 </li>
 127
 128                       <li>      <a href="plugin-management.html"  title="Plugin Management">Plugin Management</a>
 129 </li>
 130
 131                       <li>      <a href="plugins.html"  title="Plugins">Plugins</a>
 132 </li>
 133                           </ul>
 134       </li>
 135                 <li class="dropdown">
 136         <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation and API <b class="caret"></b></a>
 137         <ul class="dropdown-menu">
 138
 139                       <li>      <a href="book.html"  target="_blank" title="Reference Guide">Reference Guide</a>
 140 </li>
 141
 142                       <li>      <a href="apache_hbase_reference_guide.pdf"  target="_blank" title="Reference Guide (PDF)">Reference Guide (PDF)</a>
 143 </li>
 144
 145                       <li>      <a href="book.html#quickstart"  target="_blank" title="Getting Started">Getting Started</a>
 146 </li>
 147
 148                       <li>      <a href="apidocs/index.html"  target="_blank" title="User API">User API</a>
 149 </li>
 150
 151                       <li>      <a href="testapidocs/index.html"  target="_blank" title="User API (Test)">User API (Test)</a>
 152 </li>
 153
 154                       <li>      <a href="devapidocs/index.html"  target="_blank" title="Developer API">Developer API</a>
 155 </li>
 156
 157                       <li>      <a href="testdevapidocs/index.html"  target="_blank" title="Developer API (Test)">Developer API (Test)</a>
 158 </li>
 159
 160                       <li>      <a href="http://abloz.com/hbase/book.html"  target="_blank" title="中文参考指南(单页)">中文参考指南(单页)</a>
 161 </li>
 162
 163                       <li>      <a href="book.html#faq"  target="_blank" title="FAQ">FAQ</a>
 164 </li>
 165
 166                       <li>      <a href="book.html#other.info"  target="_blank" title="Videos/Presentations">Videos/Presentations</a>
 167 </li>
 168
 169                       <li>      <a href="http://wiki.apache.org/hadoop/Hbase"  target="_blank" title="Wiki">Wiki</a>
 170 </li>
 171
 172                       <li>      <a href="acid-semantics.html"  target="_blank" title="ACID Semantics">ACID Semantics</a>
 173 </li>
 174
 175                       <li>      <a href="book.html#arch.bulk.load"  target="_blank" title="Bulk Loads">Bulk Loads</a>
 176 </li>
 177
 178                       <li>      <a href="metrics.html"  target="_blank" title="Metrics">Metrics</a>
 179 </li>
 180
 181                       <li>      <a href="cygwin.html"  target="_blank" title="HBase on Windows">HBase on Windows</a>
 182 </li>
 183
 184                       <li>      <a href="book.html#replication"  target="_blank" title="Cluster replication">Cluster replication</a>
 185 </li>
 186
 187                       <li class="dropdown-submenu">
 188                                       <a href=""  title="1.2 Documentation">1.2 Documentation</a>
 189               <ul class="dropdown-menu">
 190                                   <li>      <a href="1.2/apidocs/index.html"  target="_blank" title="API">API</a>
 191 </li>
 192                                   <li>      <a href="1.2/xref/index.html"  target="_blank" title="X-Ref">X-Ref</a>
 193 </li>
 194                                   <li>      <a href="1.2/book.html"  target="_blank" title="Ref Guide (single-page)">Ref Guide (single-page)</a>
 195 </li>
 196                               </ul>
 197             </li>
 198                           </ul>
 199       </li>
 200                 <li class="dropdown">
 201         <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a>
 202         <ul class="dropdown-menu">
 203
 204                       <li>      <a href="http://www.apache.org/foundation/"  target="_blank" title="Apache Software Foundation">Apache Software Foundation</a>
 205 </li>
 206
 207                       <li>      <a href="http://www.apache.org/foundation/how-it-works.html"  target="_blank" title="How Apache Works">How Apache Works</a>
 208 </li>
 209
 210                       <li>      <a href="http://www.apache.org/foundation/sponsorship.html"  target="_blank" title="Sponsoring Apache">Sponsoring Apache</a>
 211 </li>
 212                           </ul>
 213       </li>
 214                   </ul>
 215
 216                           <div id="search-form" class="navbar-search pull-right">
 217       <script type="text/javascript">
 218       var cx = '000385458301414556862:sq1bb0xugjg';
 219
 220       (function() {
 221         var gcse = document.createElement('script'); gcse.type = 'text/javascript'; gcse.async = true;
 222         gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + '//cse.google.com/cse.js?cx=' + cx;
 223         var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gcse, s);
 224       })();
 225
 226     </script>
 227     <gcse:search></gcse:search>
 228   </div>
 229
 230
 231
 232                       </div>
 233
 234         </div>
 235       </div>
 236     </div>
 237
 238         <div class="container">
 239           <div id="banner">
 240         <div class="pull-left">
 241                                                           <a href="./" id="bannerLeft">
 242                                                                                                 <img src=""  alt=""/>
 243                 </a>
 244                       </div>
 245         <div class="pull-right">                                <a href="./" id="bannerRight">
 246                                                                                                 <img src="images/hbase_logo_with_orca_large.png"  alt="Apache HBase"/>
 247                 </a>
 248       </div>
 249         <div class="clear"><hr/></div>
 250       </div>
 251
 252       <div id="breadcrumbs">
 253         <ul class="breadcrumb">
 254
 255
 256
 257
 258
 259
 260                             </ul>
 261       </div>
 262
 263
 264
 265         <div id="bodyColumn" >
 266
 267             <!-- Licensed to the Apache Software Foundation (ASF) under one
 268 or more contributor license agreements.  See the NOTICE file
 269 distributed with this work for additional information
 270 regarding copyright ownership.  The ASF licenses this file
 271 to you under the Apache License, Version 2.0 (the
 272 "License"); you may not use this file except in compliance
 273 with the License.  You may obtain a copy of the License at
 274
 275   http://www.apache.org/licenses/LICENSE-2.0
 276
 277 Unless required by applicable law or agreed to in writing,
 278 software distributed under the License is distributed on an
 279 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 280 KIND, either express or implied.  See the License for the
 281 specific language governing permissions and limitations
 282 under the License. -->
 283
 284     <div class="section">
 285 <h2><a name="About_this_Document"></a>About this Document</h2>
 286
 287 <p>Apache HBase (TM) is not an ACID compliant database. However, it does guarantee certain specific
 288       properties.</p>
 289
 290 <p>This specification enumerates the ACID properties of HBase.</p>
 291     </div>
 292
 293 <div class="section">
 294 <h2><a name="Definitions"></a>Definitions</h2>
 295
 296 <p>For the sake of common vocabulary, we define the following terms:</p>
 297
 298 <dl>
 299
 300 <dt>Atomicity</dt>
 301
 302 <dd>an operation is atomic if it either completes entirely or not at all</dd>
 303
 304
 305 <dt>Consistency</dt>
 306
 307 <dd>
 308           all actions cause the table to transition from one valid state directly to another
 309           (eg a row will not disappear during an update, etc)
 310         </dd>
 311
 312
 313 <dt>Isolation</dt>
 314
 315 <dd>
 316           an operation is isolated if it appears to complete independently of any other concurrent transaction
 317         </dd>
 318
 319
 320 <dt>Durability</dt>
 321
 322 <dd>any update that reports &quot;successful&quot; to the client will not be lost</dd>
 323
 324
 325 <dt>Visibility</dt>
 326
 327 <dd>an update is considered visible if any subsequent read will see the update as having been committed</dd>
 328       </dl>
 329
 330 <p>
 331         The terms <i>must</i> and <i>may</i> are used as specified by RFC 2119.
 332         In short, the word &quot;must&quot; implies that, if some case exists where the statement
 333         is not true, it is a bug. The word &quot;may&quot; implies that, even if the guarantee
 334         is provided in a current release, users should not rely on it.
 335       </p>
 336     </div>
 337
 338 <div class="section">
 339 <h2><a name="APIs_to_consider"></a>APIs to consider</h2>
 340
 341 <ul>
 342
 343 <li>Read APIs
 344
 345 <ul>
 346
 347 <li>get</li>
 348
 349 <li>scan</li>
 350         </ul>
 351         </li>
 352
 353 <li>Write APIs</li>
 354
 355 <ul>
 356
 357 <li>put</li>
 358
 359 <li>batch put</li>
 360
 361 <li>delete</li>
 362         </ul>
 363
 364 <li>Combination (read-modify-write) APIs</li>
 365
 366 <ul>
 367
 368 <li>incrementColumnValue</li>
 369
 370 <li>checkAndPut</li>
 371         </ul>
 372       </ul>
 373     </div>
 374
 375
 376 <div class="section">
 377 <h2><a name="Guarantees_Provided"></a>Guarantees Provided</h2>
 378
 379
 380 <div class="section">
 381 <h2><a name="Atomicity"></a>Atomicity</h2>
 382
 383
 384 <ol style="list-style-type: decimal">
 385
 386 <li>All mutations are atomic within a row. Any put will either wholly succeed or wholly fail.[3]</li>
 387
 388 <ol style="list-style-type: decimal">
 389
 390 <li>An operation that returns a &quot;success&quot; code has completely succeeded.</li>
 391
 392 <li>An operation that returns a &quot;failure&quot; code has completely failed.</li>
 393
 394 <li>An operation that times out may have succeeded and may have failed. However,
 395             it will not have partially succeeded or failed.</li>
 396           </ol>
 397
 398 <li> This is true even if the mutation crosses multiple column families within a row.</li>
 399
 400 <li> APIs that mutate several rows will _not_ be atomic across the multiple rows.
 401           For example, a multiput that operates on rows 'a','b', and 'c' may return having
 402           mutated some but not all of the rows. In such cases, these APIs will return a list
 403           of success codes, each of which may be succeeded, failed, or timed out as described above.</li>
 404
 405 <li> The checkAndPut API happens atomically like the typical compareAndSet (CAS) operation
 406           found in many hardware architectures.</li>
 407
 408 <li> The order of mutations is seen to happen in a well-defined order for each row, with no
 409           interleaving. For example, if one writer issues the mutation &quot;a=1,b=1,c=1&quot; and
 410           another writer issues the mutation &quot;a=2,b=2,c=2&quot;, the row must either
 411           be &quot;a=1,b=1,c=1&quot; or &quot;a=2,b=2,c=2&quot; and must <i>not</i> be something
 412           like &quot;a=1,b=2,c=1&quot;.</li>
 413
 414 <ol style="list-style-type: decimal">
 415
 416 <li>Please note that this is not true _across rows_ for multirow batch mutations.</li>
 417           </ol>
 418         </ol>
 419       </div>
 420
 421 <div class="section">
 422 <h2><a name="Consistency_and_Isolation"></a>Consistency and Isolation</h2>
 423
 424 <ol style="list-style-type: decimal">
 425
 426 <li>All rows returned via any access API will consist of a complete row that existed at
 427           some point in the table's history.</li>
 428
 429 <li>This is true across column families - i.e a get of a full row that occurs concurrent
 430           with some mutations 1,2,3,4,5 will return a complete row that existed at some point in time
 431           between mutation i and i+1 for some i between 1 and 5.</li>
 432
 433 <li>The state of a row will only move forward through the history of edits to it.</li>
 434         </ol>
 435
 436
 437 <div class="section">
 438 <h2><a name="Consistency_of_Scans"></a>Consistency of Scans</h2>
 439
 440 <p>
 441           A scan is <b>not</b> a consistent view of a table. Scans do
 442           <b>not</b> exhibit <i>snapshot isolation</i>.
 443         </p>
 444
 445 <p>
 446           Rather, scans have the following properties:
 447         </p>
 448
 449
 450 <ol style="list-style-type: decimal">
 451
 452 <li>
 453             Any row returned by the scan will be a consistent view (i.e. that version
 454             of the complete row existed at some point in time) [1]
 455           </li>
 456
 457 <li>
 458             A scan will always reflect a view of the data <i>at least as new as</i>
 459             the beginning of the scan. This satisfies the visibility guarantees
 460           enumerated below.</li>
 461
 462 <ol style="list-style-type: decimal">
 463
 464 <li>For example, if client A writes data X and then communicates via a side
 465             channel to client B, any scans started by client B will contain data at least
 466             as new as X.</li>
 467
 468 <li>A scan _must_ reflect all mutations committed prior to the construction
 469             of the scanner, and _may_ reflect some mutations committed subsequent to the
 470             construction of the scanner.</li>
 471
 472 <li>Scans must include <i>all</i> data written prior to the scan (except in
 473             the case where data is subsequently mutated, in which case it _may_ reflect
 474             the mutation)</li>
 475           </ol>
 476         </ol>
 477
 478 <p>
 479           Those familiar with relational databases will recognize this isolation level as &quot;read committed&quot;.
 480         </p>
 481
 482 <p>
 483           Please note that the guarantees listed above regarding scanner consistency
 484           are referring to &quot;transaction commit time&quot;, not the &quot;timestamp&quot;
 485           field of each cell. That is to say, a scanner started at time <i>t</i> may see edits
 486           with a timestamp value greater than <i>t</i>, if those edits were committed with a
 487           &quot;forward dated&quot; timestamp before the scanner was constructed.
 488         </p>
 489         </div>
 490       </div>
 491
 492 <div class="section">
 493 <h2><a name="Visibility"></a>Visibility</h2>
 494
 495 <ol style="list-style-type: decimal">
 496
 497 <li> When a client receives a &quot;success&quot; response for any mutation, that
 498           mutation is immediately visible to both that client and any client with whom it
 499           later communicates through side channels. [3]</li>
 500
 501 <li> A row must never exhibit so-called &quot;time-travel&quot; properties. That
 502           is to say, if a series of mutations moves a row sequentially through a series of
 503           states, any sequence of concurrent reads will return a subsequence of those states.</li>
 504
 505 <ol style="list-style-type: decimal">
 506
 507 <li>For example, if a row's cells are mutated using the &quot;incrementColumnValue&quot;
 508             API, a client must never see the value of any cell decrease.</li>
 509
 510 <li>This is true regardless of which read API is used to read back the mutation.</li>
 511           </ol>
 512
 513 <li> Any version of a cell that has been returned to a read operation is guaranteed to
 514           be durably stored.</li>
 515         </ol>
 516
 517       </div>
 518
 519 <div class="section">
 520 <h2><a name="Durability"></a>Durability</h2>
 521
 522 <ol style="list-style-type: decimal">
 523
 524 <li> All visible data is also durable data. That is to say, a read will never return
 525           data that has not been made durable on disk[2]</li>
 526
 527 <li> Any operation that returns a &quot;success&quot; code (eg does not throw an exception)
 528           will be made durable.[3]</li>
 529
 530 <li> Any operation that returns a &quot;failure&quot; code will not be made durable
 531           (subject to the Atomicity guarantees above)</li>
 532
 533 <li> All reasonable failure scenarios will not affect any of the guarantees of this document.</li>
 534
 535         </ol>
 536       </div>
 537
 538 <div class="section">
 539 <h2><a name="Tunability"></a>Tunability</h2>
 540
 541 <p>All of the above guarantees must be possible within Apache HBase. For users who would like to trade
 542         off some guarantees for performance, HBase may offer several tuning options. For example:</p>
 543
 544 <ul>
 545
 546 <li>Visibility may be tuned on a per-read basis to allow stale reads or time travel.</li>
 547
 548 <li>Durability may be tuned to only flush data to disk on a periodic basis</li>
 549         </ul>
 550       </div>
 551     </div>
 552
 553 <div class="section">
 554 <h2><a name="More_Information"></a>More Information</h2>
 555
 556 <p>
 557       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.
 558       </p>
 559     </div>
 560
 561
 562 <div class="section">
 563 <h2><a name="Footnotes"></a>Footnotes</h2>
 564
 565 <p>[1] A consistent view is not guaranteed intra-row scanning -- i.e. fetching a portion of
 566           a row in one RPC then going back to fetch another portion of the row in a subsequent RPC.
 567           Intra-row scanning happens when you set a limit on how many values to return per Scan#next
 568           (See <a class="externalLink" href="http://hbase.apache.org/apidocs/org/apache/hadoop/hbase/client/Scan.html#setBatch(int)">Scan#setBatch(int)</a>).
 569       </p>
 570
 571
 572 <p>[2] In the context of Apache HBase, &quot;durably on disk&quot; implies an hflush() call on the transaction
 573       log. This does not actually imply an fsync() to magnetic media, but rather just that the data has been
 574       written to the OS cache on all replicas of the log. In the case of a full datacenter power loss, it is
 575       possible that the edits are not truly durable.</p>
 576
 577 <p>[3] Puts will either wholly succeed or wholly fail, provided that they are actually sent
 578       to the RegionServer.  If the writebuffer is used, Puts will not be sent until the writebuffer is filled
 579       or it is explicitly flushed.</p>
 580
 581     </div>
 582
 583
 584
 585                   </div>
 586           </div>
 587
 588     <hr/>
 589
 590     <footer>
 591             <div class="container">
 592                       <div class="row">
 593                                       <p >Copyright &copy;                    2007&#x2013;2018
 594                         <a href="https://www.apache.org/">The Apache Software Foundation</a>.
 595             All rights reserved.
 596
 597                   <li id="publishDate" class="pull-right">Last Published: 2018-03-11</li>
 598             </p>
 599                 </div>
 600
 601                 <p id="poweredBy" class="pull-right">
 602                           <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
 603         <img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
 604       </a>
 605               </p>
 606
 607                 </div>
 608     </footer>
 609         </body>
 610 </html>