phoenix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tdsi...@apache.org
Subject svn commit: r1728246 - in /phoenix/site: publish/index.html publish/roadmap.html publish/transactions.html source/src/site/markdown/index.md source/src/site/markdown/roadmap.md source/src/site/markdown/transactions.md
Date Wed, 03 Feb 2016 01:59:35 GMT
Author: tdsilva
Date: Wed Feb  3 01:59:35 2016
New Revision: 1728246

URL: http://svn.apache.org/viewvc?rev=1728246&view=rev
Log:
PHOENIX-2440 Document transactional behavior


Modified:
    phoenix/site/publish/index.html
    phoenix/site/publish/roadmap.html
    phoenix/site/publish/transactions.html
    phoenix/site/source/src/site/markdown/index.md
    phoenix/site/source/src/site/markdown/roadmap.md
    phoenix/site/source/src/site/markdown/transactions.md

Modified: phoenix/site/publish/index.html
URL: http://svn.apache.org/viewvc/phoenix/site/publish/index.html?rev=1728246&r1=1728245&r2=1728246&view=diff
==============================================================================
--- phoenix/site/publish/index.html (original)
+++ phoenix/site/publish/index.html Wed Feb  3 01:59:35 2016
@@ -1,7 +1,7 @@
 
 <!DOCTYPE html>
 <!--
- Generated by Apache Maven Doxia at 2016-01-23
+ Generated by Apache Maven Doxia at 2016-02-02
  Rendered using Reflow Maven Skin 1.1.0 (http://andriusvelykis.github.io/reflow-maven-skin)
 -->
 <html  xml:lang="en" lang="en">
@@ -210,7 +210,6 @@
  <p>For any omitted part, the relevant property value, hbase.zookeeper.quorum, hbase.zookeeper.property.clientPort,
and zookeeper.znode.parent will be used from hbase-site.xml configuration file.</p>

  <p>Here’s a list of what is currently <b>not</b> supported:</p>

  <ul> 
-  <li><b>Full Transaction Support</b>. Although we allow client-side batching
and rollback as described <a href="#transactions">here</a>, we do not provide
transaction semantics above and beyond what HBase gives you out-of-the-box.</li> 
   <li><b>Relational operators</b>. Union, Intersect, Minus.</li>

   <li><b>Miscellaneous built-in functions</b>. These are easy to add -
read this <a class="externalLink" href="http://phoenix-hbase.blogspot.com/2013/04/how-to-add-your-own-built-in-function.html">blog</a>
for step by step instructions.</li> 
  </ul> 
@@ -251,8 +250,10 @@
 </div> 
 <div class="section"> 
  <h2 id="transactions">Transactions<a name="Transactions"></a></h2>

- <p>The DML commands of Apache Phoenix, <a href="language/index.html#upsert_values">UPSERT
VALUES</a>, <a href="language/index.html#upsert_select">UPSERT SELECT</a>
and <a href="language/index.html#delete">DELETE</a>, batch pending changes to
HBase tables on the client side. The changes are sent to the server when the transaction is
committed and discarded when the transaction is rolled back. The only transaction isolation
level we support is TRANSACTION_READ_COMMITTED. This includes not being able to see your own
uncommitted data as well. Phoenix does not providing any additional transactional semantics
beyond what HBase supports when a batch of mutations is submitted to the server. If auto commit
is turned on for a connection, then Phoenix will, whenever possible, execute the entire DML
command through a coprocessor on the server-side, so performance will improve.</p> 
- <p>Most commonly, an application will let HBase manage timestamps. However, under
some circumstances, an application needs to control the timestamps itself. In this case, a
long-valued “CurrentSCN” property may be specified at connection time to control
timestamps for any DDL, DML, or query. This capability may be used to run snapshot queries
against prior row values, since Phoenix uses the value of this connection property as the
max timestamp of scans.</p> 
+ <p>The DML commands of Apache Phoenix, <a href="language/index.html#upsert_values">UPSERT
VALUES</a>, <a href="language/index.html#upsert_select">UPSERT SELECT</a>
and <a href="language/index.html#delete">DELETE</a>, batch pending changes to
HBase tables on the client side. The changes are sent to the server when the transaction is
committed and discarded when the transaction is rolled back. </p> 
+ <p>If the “phoenix.transactions.enabled” property is enabled then the transaction
isolation level is TRANSACTION_SERIALIZABLE which allows a transaction to see its own uncommitted
data. Otherwise the transaction isolation level is TRANSACTION_READ_COMMITTED which means
a client cannot see its own uncommitted data. </p> 
+ <p>If auto commit is turned on for a connection, then Phoenix will, whenever possible,
execute the entire DML command through a coprocessor on the server-side, so performance will
improve.</p> 
+ <p>Most commonly, an application will let HBase manage timestamps. However, under
some circumstances, an application needs to control the timestamps itself. In this case, a
long-valued “CurrentSCN” property may be specified at connection time to control
timestamps for any DDL, DML, or query. This capability may be used to run snapshot queries
against prior row values, since Phoenix uses the value of this connection property as the
max timestamp of scans. However the SCN feature is not supported with transactions. </p>

 </div> 
 <div class="section"> 
  <h2 id="Metadata">Metadata</h2> 

Modified: phoenix/site/publish/roadmap.html
URL: http://svn.apache.org/viewvc/phoenix/site/publish/roadmap.html?rev=1728246&r1=1728245&r2=1728246&view=diff
==============================================================================
--- phoenix/site/publish/roadmap.html (original)
+++ phoenix/site/publish/roadmap.html Wed Feb  3 01:59:35 2016
@@ -1,7 +1,7 @@
 
 <!DOCTYPE html>
 <!--
- Generated by Apache Maven Doxia at 2016-01-23
+ Generated by Apache Maven Doxia at 2016-02-02
  Rendered using Reflow Maven Skin 1.1.0 (http://andriusvelykis.github.io/reflow-maven-skin)
 -->
 <html  xml:lang="en" lang="en">
@@ -146,7 +146,6 @@
 </div> 
 <p>Our roadmap is driven by our user community. Below, in prioritized order, is the
current plan for Phoenix:</p> 
 <ol style="list-style-type: decimal"> 
- <li><b><a class="externalLink" href="https://issues.apache.org/jira/browse/PHOENIX-1674">Transaction
Support</a></b>. Support transactions by integrating with <a class="externalLink"
href="https://github.com/continuuity/tephra">Tephra</a>. <b>See our <a class="externalLink"
href="https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/txn">txn
branch</a> to try this and track our progress.</b></li> 
  <li><b><a class="externalLink" href="https://calcite.incubator.apache.org/">Apache
Calcite</a> Adapter</b>. Create a Phoenix adapter for Calcite to increase the
breadth of our SQL support, plug into a rich cost-based optimizer framework, and enable potential
interop with other adapters. <b>See our <a class="externalLink" href="https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/calcite">calcite
branch</a> to try this and track our progress.</b></li> 
  <li><b><a class="externalLink" href="https://issues.apache.org/jira/browse/PHOENIX-628">JSON
Support</a></b>. Support a JSON data type and implement the standard operators
and built-in functions similar to Postgres. <b>See our <a class="externalLink" href="https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/json">json
branch</a> to try this and track our progress.</b></li> 
  <li><b><a class="externalLink" href="https://issues.apache.org/jira/browse/PHOENIX-1121">Monitoring
and Management Improvements</a></b>. Though we support <a href="tracing.html">tracing</a>
now, there’s more work to do to better <i>operationalize</i> Phoenix.</li>


Modified: phoenix/site/publish/transactions.html
URL: http://svn.apache.org/viewvc/phoenix/site/publish/transactions.html?rev=1728246&r1=1728245&r2=1728246&view=diff
==============================================================================
--- phoenix/site/publish/transactions.html (original)
+++ phoenix/site/publish/transactions.html Wed Feb  3 01:59:35 2016
@@ -1,7 +1,7 @@
 
 <!DOCTYPE html>
 <!--
- Generated by Apache Maven Doxia at 2016-01-23
+ Generated by Apache Maven Doxia at 2016-02-02
  Rendered using Reflow Maven Skin 1.1.0 (http://andriusvelykis.github.io/reflow-maven-skin)
 -->
 <html  xml:lang="en" lang="en">
@@ -144,41 +144,52 @@
 <div class="page-header">
  <h1>Transactions (beta)</h1>
 </div> 
-<p>Above and beyond the row-level transactional semantics of HBase, Phoenix adds cross
row and cross table transaction support with full ACID semantics by integrating with a transaction
library named <a class="externalLink" href="http://tephra.io/">Tephra</a>.</p>

+<p>Above and beyond the row-level transactional semantics of HBase, Phoenix adds cross
row and cross table transaction support with full <a class="externalLink" href="https://en.wikipedia.org/wiki/ACID">ACID</a>
semantics by integrating with a transaction library named <a class="externalLink" href="http://tephra.io/">Tephra</a>.
Tephra provides snapshot isolation of concurrent transactions by implementing multi-versioned
concurrency control.</p> 
 <p>Setting up a system to use transactions in Phoenix requires two steps:</p>

 <ol style="list-style-type: decimal"> 
- <li> <p>Enabling them through a new configuration option:</p> 
+ <li> <p>Add the following config to your client side <tt>hbase-site.xml</tt>
file to enable transactions:</p> 
   <div> 
    <pre>
 &lt;property&gt;
   &lt;name&gt;phoenix.transactions.enabled&lt;/name&gt;
   &lt;value&gt;true&lt;/value&gt;
 &lt;/property&gt;
-</pre>
+</pre> 
   </div></li> 
- <li> <p>Starting an additional component, the transaction manager:</p>

+ <li> <p>Add the following config to your server side <tt>hbase-site.xml</tt>
file to configure the transaction manager: The “Transaction Server Configuration”
section of <a class="externalLink" href="https://github.com/caskdata/tephra">Tephra</a>
describes the available configuration options.</p> 
+  <div> 
+   <pre>
+&lt;property&gt;
+  &lt;name&gt;data.tx.snapshot.dir&lt;/name&gt;
+  &lt;value&gt;/tmp/tephra/snapshots&lt;/value&gt;
+&lt;/property&gt;
+</pre> 
+  </div> <p>Also set the transaction timeout (time after which open transactions
become invalid) to a reasonable value.</p> 
+  <div> 
+   <pre>
+&lt;property&gt;
+  &lt;name&gt;data.tx.timeout&lt;/name&gt;
+  &lt;value&gt;60&lt;/value&gt;
+&lt;/property&gt;
+</pre> 
+  </div></li> 
+ <li> <p>Set $HBASE_HOME and start the transaction manager:</p> 
   <div> 
    <pre>
-./bin/tephra-env.sh
 ./bin/tephra
-</pre>
+</pre> 
   </div></li> 
 </ol> 
 <p>The transaction manager would typically be configured to run on one or more of the
master nodes in your HBase cluster.</p> 
 <p>Once this setup is done, transactions may then be enabled on a table by table basis
by using the <tt>TRANSACTIONAL=true</tt> property when you create your table:</p>

 <div class="source"> 
  <pre>CREATE TABLE my_table (k BIGINT PRIMARY KEY, v VARCHAR) TRANSACTIONAL=true;
-</pre>
+</pre> 
 </div> 
 <p>An existing table may also be altered to be transactional, <b>but be careful
because you cannot switch a transactional table back to being non transactional</b>:</p>

 <div class="source"> 
  <pre>ALTER TABLE my_other_table SET TRANSACTIONAL=true;
-</pre>
-</div> 
-<p>Indexes added to a transactional table are transactional as well with regard to
their incremental maintenance. For example, the following index added to my_table will be
kept transactional consistent with its data table as mutations are made:</p> 
-<div class="source"> 
- <pre>CREATE INDEX  my_table (k BIGINT PRIMARY KEY, v VARCHAR) TRANSACTIONAL=true;
-</pre>
+</pre> 
 </div> 
 <p>A transaction is started implicitly through the execution of a statement on a transactional
table and then finished through either a commit or rollback. Once started, the statements
will not see any data committed by other transactions until the transaction is complete. They
will, however, see their own uncommitted data. For example:</p> 
 <div class="source"> 
@@ -186,8 +197,43 @@
 UPSERT INTO my_table VALUES (1,'A');
 SELECT count(*) FROM my_table WHERE k=1; -- Will see uncommitted row
 DELETE FROM my_other_table WHERE k=2;
-COMMIT; -- Other transactions will now see your updates and you will see theirs
-</pre>
+!commit -- Other transactions will now see your updates and you will see theirs
+</pre> 
+</div> 
+<p>An exception is thrown if a transaction tries to commit a row that conflicts with
other overlapping transaction that already committed. For example:</p> 
+<div class="source"> 
+ <pre>UPSERT INTO my_table VALUES (1,'A');
+</pre> 
+</div> 
+<p>In a second transaction perform a commit for the same row.</p> 
+<div class="source"> 
+ <pre>UPSERT INTO my_table VALUES (1,'B');
+!commit
+</pre> 
+</div> 
+<p>Now if you try to commit the first transaction you will get an exception</p>

+<div class="source"> 
+ <pre>java.sql.SQLException: ERROR 523 (42900): Transaction aborted due to conflict
with other mutations. Conflict detected for transaction 1454112544975000000.
+</pre> 
+</div> 
+<p>Queries are only able to view commits that completed before the current transaction
started and are not able to view the in progress changes of other transactions.</p>

+<p>Indexes added to a transactional table are transactional as well with regard to
their incremental maintenance. For example, the following index added to my_table will be
kept transactional consistent with its data table as mutations are made:</p> 
+<div class="source"> 
+ <pre>CREATE INDEX  my_table (k BIGINT PRIMARY KEY, v VARCHAR) TRANSACTIONAL=true;
+</pre> 
+</div> 
+<p>During a commit, if either the index or data table write fails an exception is thrown
and the client can either rollback or retry. If the commit fails both the index and data table
rows are not visible.</p> 
+<p>An external Tephra transaction that has already been started can be used with Phoenix
by setting the transaction context of the phoenix connection :</p> 
+<div> 
+ <pre>setTransactionContext(TransactionContext txContext)</pre> 
+</div> 
+<div class="section"> 
+ <h2 id="Limitations">Limitations</h2> 
+ <ol style="list-style-type: decimal"> 
+  <li>Starting a transaction on a connection with an SCN set is not allowed.</li>

+  <li>Setting the maximum number of versions property while creating a transactional
table limits the number of snapshots available for concurrent transactions.</li> 
+  <li>When a transaction times out or if it cannot be rolled back by the client, it
is added to an invalid list. This list will can potentially grow if there are a lot of failed
or timed out transactions. For now, now an adminstrator can manually clear transactions from
this list. <a class="externalLink" href="https://issues.cask.co/browse/TEPHRA-35">TEPHRA-35</a>
describes ongoing work to automatically remove transactions from the invalid list once all
data associated with the transaction has been removed.</li> 
+ </ol> 
 </div>
 			</div>
 		</div>

Modified: phoenix/site/source/src/site/markdown/index.md
URL: http://svn.apache.org/viewvc/phoenix/site/source/src/site/markdown/index.md?rev=1728246&r1=1728245&r2=1728246&view=diff
==============================================================================
--- phoenix/site/source/src/site/markdown/index.md (original)
+++ phoenix/site/source/src/site/markdown/index.md Wed Feb  3 01:59:35 2016
@@ -78,7 +78,6 @@ For any omitted part, the relevant prope
 
 Here's a list of what is currently **not** supported:
 
-* **Full Transaction Support**. Although we allow client-side batching and rollback as described
[here](#transactions), we do not provide transaction semantics above and beyond what HBase
gives you out-of-the-box.
 * **Relational operators**. Union, Intersect, Minus.
 * **Miscellaneous built-in functions**. These are easy to add - read this [blog](http://phoenix-hbase.blogspot.com/2013/04/how-to-add-your-own-built-in-function.html)
for step by step instructions.
 
@@ -112,9 +111,14 @@ The other caveat is that the way the byt
 Our composite row keys are formed by simply concatenating the values together, with a zero
byte character used as a separator after a variable length type. For more information on our
type system, see the [Data Type](language/datatypes.html).
 
 ##<a id="transactions"></a>Transactions##
-The DML commands of Apache Phoenix, [UPSERT VALUES](language/index.html#upsert_values), [UPSERT
SELECT](language/index.html#upsert_select) and [DELETE](language/index.html#delete), batch
pending changes to HBase tables on the client side. The changes are sent to the server when
the transaction is committed and discarded when the transaction is rolled back. The only transaction
isolation level we support is TRANSACTION_READ_COMMITTED. This includes not being able to
see your own uncommitted data as well. Phoenix does not providing any additional transactional
semantics beyond what HBase supports when a batch of mutations is submitted to the server.
If auto commit is turned on for a connection, then Phoenix will, whenever possible, execute
the entire DML command through a coprocessor on the server-side, so performance will improve.
+The DML commands of Apache Phoenix, [UPSERT VALUES](language/index.html#upsert_values), [UPSERT
SELECT](language/index.html#upsert_select) and [DELETE](language/index.html#delete), batch
pending changes to HBase tables on the client side. The changes are sent to the server when
the transaction is committed and discarded when the transaction is rolled back. 
 
-Most commonly, an application will let HBase manage timestamps. However, under some circumstances,
an application needs to control the timestamps itself. In this case, a long-valued "CurrentSCN"
property may be specified at connection time to control timestamps for any DDL, DML, or query.
This capability may be used to run snapshot queries against prior row values, since Phoenix
uses the value of this connection property as the max timestamp of scans.
+If the "phoenix.transactions.enabled" property is enabled then the transaction isolation
level is TRANSACTION_SERIALIZABLE which allows a transaction to see its own uncommitted data.
+Otherwise the  transaction isolation level is TRANSACTION_READ_COMMITTED which means a client
cannot see its own uncommitted data. 
+
+If auto commit is turned on for a connection, then Phoenix will, whenever possible, execute
the entire DML command through a coprocessor on the server-side, so performance will improve.
+
+Most commonly, an application will let HBase manage timestamps. However, under some circumstances,
an application needs to control the timestamps itself. In this case, a long-valued "CurrentSCN"
property may be specified at connection time to control timestamps for any DDL, DML, or query.
This capability may be used to run snapshot queries against prior row values, since Phoenix
uses the value of this connection property as the max timestamp of scans. However the SCN
feature is not supported with transactions. 
 
 ## Metadata ##
 The catalog of tables, their columns, primary keys, and types may be retrieved via the java.sql
metadata interfaces: `DatabaseMetaData`, `ParameterMetaData`, and `ResultSetMetaData`. For
retrieving schemas, tables, and columns through the DatabaseMetaData interface, the schema
pattern, table pattern, and column pattern are specified as in a LIKE expression (i.e. % and
_ are wildcards escaped through the \ character). The table catalog argument to the metadata
APIs deviates from a more standard relational database model, and instead is used to specify
a column family name (in particular to see all columns in a given column family).

Modified: phoenix/site/source/src/site/markdown/roadmap.md
URL: http://svn.apache.org/viewvc/phoenix/site/source/src/site/markdown/roadmap.md?rev=1728246&r1=1728245&r2=1728246&view=diff
==============================================================================
--- phoenix/site/source/src/site/markdown/roadmap.md (original)
+++ phoenix/site/source/src/site/markdown/roadmap.md Wed Feb  3 01:59:35 2016
@@ -2,9 +2,8 @@
 
 Our roadmap is driven by our user community. Below, in prioritized order, is the current
plan for Phoenix:
 
-1. **[Transaction Support](https://issues.apache.org/jira/browse/PHOENIX-1674)**. Support
transactions by integrating with [Tephra](https://github.com/continuuity/tephra). **See our
[txn branch](https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/txn)
to try this and track our progress.**
-2. **[Apache Calcite](https://calcite.incubator.apache.org/) Adapter**. Create a Phoenix
adapter for Calcite to increase the breadth of our SQL support, plug into a rich cost-based
optimizer framework, and enable potential interop with other adapters. **See our [calcite
branch](https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/calcite)
to try this and track our progress.**
-3. **[JSON Support](https://issues.apache.org/jira/browse/PHOENIX-628)**. Support a JSON
data type and implement the standard operators and built-in functions similar to Postgres.
**See our [json branch](https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/json)
to try this and track our progress.**
+1. **[Apache Calcite](https://calcite.incubator.apache.org/) Adapter**. Create a Phoenix
adapter for Calcite to increase the breadth of our SQL support, plug into a rich cost-based
optimizer framework, and enable potential interop with other adapters. **See our [calcite
branch](https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/calcite)
to try this and track our progress.**
+2. **[JSON Support](https://issues.apache.org/jira/browse/PHOENIX-628)**. Support a JSON
data type and implement the standard operators and built-in functions similar to Postgres.
**See our [json branch](https://git-wip-us.apache.org/repos/asf?p=phoenix.git;a=shortlog;h=refs/heads/json)
to try this and track our progress.**
 10. **[Monitoring and Management Improvements](https://issues.apache.org/jira/browse/PHOENIX-1121)**.
Though we support [tracing](tracing.html) now, there's more work to do to better _operationalize_
Phoenix.
 15. **[Cost-based Query Optimization]((https://issues.apache.org/jira/browse/PHOENIX-1177))**.
Enhance existing [statistics collection](update_statistics.html) by enabling further query
optmizations based on the size and cardinality of the data.
     * **[Generate histograms](https://issues.apache.org/jira/browse/PHOENIX-1178)** to drive
query optimization decisions such as secondary index usage and join ordering based on cardinalities
to produce the most efficient query plan.

Modified: phoenix/site/source/src/site/markdown/transactions.md
URL: http://svn.apache.org/viewvc/phoenix/site/source/src/site/markdown/transactions.md?rev=1728246&r1=1728245&r2=1728246&view=diff
==============================================================================
--- phoenix/site/source/src/site/markdown/transactions.md (original)
+++ phoenix/site/source/src/site/markdown/transactions.md Wed Feb  3 01:59:35 2016
@@ -1,9 +1,9 @@
 # Transactions (beta)
-Above and beyond the row-level transactional semantics of HBase, Phoenix adds cross row and
cross table transaction support with full ACID semantics by integrating with a transaction
library named [Tephra](http://tephra.io/).
+Above and beyond the row-level transactional semantics of HBase, Phoenix adds cross row and
cross table transaction support with full [ACID](https://en.wikipedia.org/wiki/ACID) semantics
by integrating with a transaction library named [Tephra](http://tephra.io/). Tephra provides
snapshot isolation of concurrent transactions by implementing multi-versioned concurrency
control.
 
 Setting up a system to use transactions in Phoenix requires two steps:
 
-1. Enabling them through a new configuration option:
+1. Add the following config to your client side <code>hbase-site.xml</code> file
to enable transactions:
 
     <pre>
     &lt;property&gt;
@@ -11,10 +11,29 @@ Setting up a system to use transactions
       &lt;value&gt;true&lt;/value&gt;
     &lt;/property&gt;
     </pre>
-2. Starting an additional component, the transaction manager:
+
+2. Add the following config to your server side <code>hbase-site.xml</code> file
to configure the transaction manager:
+   The "Transaction Server Configuration" section of [Tephra](https://github.com/caskdata/tephra)
describes the available configuration options.
+
+    <pre>
+    &lt;property&gt;
+      &lt;name&gt;data.tx.snapshot.dir&lt;/name&gt;
+      &lt;value&gt;/tmp/tephra/snapshots&lt;/value&gt;
+    &lt;/property&gt;
+    </pre>
+
+    Also set the transaction timeout (time after which open transactions become invalid)
to a reasonable value.
+
+    <pre>
+    &lt;property&gt;
+      &lt;name&gt;data.tx.timeout&lt;/name&gt;
+      &lt;value&gt;60&lt;/value&gt;
+    &lt;/property&gt;
+    </pre>
+
+3. Set $HBASE_HOME and start the transaction manager:
 
     <pre>
-    ./bin/tephra-env.sh
     ./bin/tephra
     </pre>
 
@@ -28,15 +47,44 @@ An existing table may also be altered to
 
     ALTER TABLE my_other_table SET TRANSACTIONAL=true;
 
-Indexes added to a transactional table are transactional as well with regard to their incremental
maintenance. For example, the following index added to my_table will be kept transactional
consistent with its data table as mutations are made:
-
-    CREATE INDEX  my_table (k BIGINT PRIMARY KEY, v VARCHAR) TRANSACTIONAL=true;
-
 A transaction is started implicitly through the execution of a statement on a transactional
table and then finished through either a commit or rollback. Once started, the statements
will not see any data committed by other transactions until the transaction is complete. They
will, however, see their own uncommitted data. For example:
 
     SELECT * FROM my_table; -- This will start a transaction
     UPSERT INTO my_table VALUES (1,'A');
     SELECT count(*) FROM my_table WHERE k=1; -- Will see uncommitted row
     DELETE FROM my_other_table WHERE k=2;
-    COMMIT; -- Other transactions will now see your updates and you will see theirs
+    !commit -- Other transactions will now see your updates and you will see theirs
+
+An exception is thrown if a transaction tries to commit a row that conflicts with other overlapping
transaction that already committed. For example:
+
+    UPSERT INTO my_table VALUES (1,'A');
+
+In a second transaction perform a commit for the same row.
+
+    UPSERT INTO my_table VALUES (1,'B');
+    !commit
+
+Now if you try to commit the first transaction you will get an exception
+
+    java.sql.SQLException: ERROR 523 (42900): Transaction aborted due to conflict with other
mutations. Conflict detected for transaction 1454112544975000000.
+
+Queries are only able to view commits that completed before the current transaction started
and are not able to view the in progress changes of other transactions.
+
+Indexes added to a transactional table are transactional as well with regard to their incremental
maintenance. For example, the following index added to my_table will be kept transactional
consistent with its data table as mutations are made:
+
+    CREATE INDEX  my_table (k BIGINT PRIMARY KEY, v VARCHAR) TRANSACTIONAL=true;
+
+During a commit, if either the index or data table write fails an exception is thrown and
the client can either rollback or retry. 
+If the commit fails both the index and data table rows are not visible.
+
+An external Tephra transaction that has already been started can be used with Phoenix by
setting the transaction context of the phoenix connection :
+
+<pre>setTransactionContext(TransactionContext txContext)</pre>
+
+##Limitations
+
+1. Starting a transaction on a connection with an SCN set is not allowed. 
+2. Setting the maximum number of versions property while creating a transactional table limits
the number of snapshots available for concurrent transactions. 
+3. When a transaction times out or if it cannot be rolled back by the client, it is added
to an invalid list. This list will can potentially grow if there are a lot of failed or timed
out transactions. 
+For now, now an adminstrator can manually clear transactions from this list. [TEPHRA-35](https://issues.cask.co/browse/TEPHRA-35)
describes ongoing work to automatically remove transactions from the invalid list once all
data associated with the transaction has been removed.
 



Mime
View raw message