You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@phoenix.apache.org by td...@apache.org on 2016/02/03 02:59:35 UTC
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
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>
<property>
<name>phoenix.transactions.enabled</name>
<value>true</value>
</property>
-</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>
+<property>
+ <name>data.tx.snapshot.dir</name>
+ <value>/tmp/tephra/snapshots</value>
+</property>
+</pre>
+ </div> <p>Also set the transaction timeout (time after which open transactions become invalid) to a reasonable value.</p>
+ <div>
+ <pre>
+<property>
+ <name>data.tx.timeout</name>
+ <value>60</value>
+</property>
+</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>
<property>
@@ -11,10 +11,29 @@ Setting up a system to use transactions
<value>true</value>
</property>
</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>
+ <property>
+ <name>data.tx.snapshot.dir</name>
+ <value>/tmp/tephra/snapshots</value>
+ </property>
+ </pre>
+
+ Also set the transaction timeout (time after which open transactions become invalid) to a reasonable value.
+
+ <pre>
+ <property>
+ <name>data.tx.timeout</name>
+ <value>60</value>
+ </property>
+ </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.