Published site at d5aaeee88b331e064830a2774f4fed238631457c.
[hbase-site.git] / 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>