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.
