From 7e870018dc2b1b78cf1754056c260c77379d5b47 Mon Sep 17 00:00:00 2001
From: Tyler Hobbs <tyler@datastax.com>
Date: Wed, 19 Mar 2014 11:37:09 -0500
Subject: [PATCH] Add UNLOGGED, COUNTER options to BATCH docs

patch by Tyler Hobbs; reviewed by Sylvain Lebresne for CASSANDRA-6816
---
 CHANGES.txt          |  1 +
 doc/cql3/CQL.textile | 19 +++++++++++++++----
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index f88345d075..960b0e9862 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,4 +1,5 @@
 1.2.16
+ * Add UNLOGGED, COUNTER options to BATCH documentation (CASSANDRA-6816)
  * add extra SSL cipher suites (CASSANDRA-6613)
  * fix nodetool getsstables for blob PK (CASSANDRA-6803)
  * Add CMSClassUnloadingEnabled JVM option (CASSANDRA-6541)
diff --git a/doc/cql3/CQL.textile b/doc/cql3/CQL.textile
index ecd3b7e814..91e2625ec7 100644
--- a/doc/cql3/CQL.textile
+++ b/doc/cql3/CQL.textile
@@ -536,7 +536,7 @@ h3(#batchStmt). BATCH
 __Syntax:__
 
 bc(syntax).. 
-<batch-stmt> ::= BEGIN BATCH
+<batch-stmt> ::= BEGIN ( UNLOGGED | COUNTER ) BATCH
                  ( USING <option> ( AND <option> )* )?
                     <modification-stmt> ( ';' <modification-stmt> )*
                  APPLY BATCH
@@ -557,11 +557,22 @@ BEGIN BATCH
   DELETE name FROM users WHERE userid = 'user1';
 APPLY BATCH;
 
-The @BATCH@ statement group multiple modification statements (insertions/updates and deletions) into a single statement. It mainly serves two purposes:
-# it saves network round-trips between the client and the server (and sometimes between the server coordinator and the replicas) when batching multiple updates.
-# all updates in a @BATCH@ belonging to a given partition key are performed atomically and in isolation
+The @BATCH@ statement group multiple modification statements (insertions/updates and deletions) into a single statement. It serves several purposes:
+# It saves network round-trips between the client and the server (and sometimes between the server coordinator and the replicas) when batching multiple updates.
+# All updates in a @BATCH@ belonging to a given partition key are performed in isolation.
+# By default, all operations in the batch are performed atomically.  See the notes on "@UNLOGGED@":#unloggedBatch for more details.
 Note however that the @BATCH@ statement only allows @UPDATE@, @INSERT@ and @DELETE@ statements and is _not_ a full analogue for SQL transactions.
 
+h4(#unloggedBatch). @UNLOGGED@
+
+By default, Cassandra uses a batch log to ensure all operations in a batch are applied atomically. (Note that the operations are still only isolated within a single partition.)
+
+There is a performance penalty for batch atomicity when a batch spans multiple partitions. If you do not want to incur this penalty, you can tell Cassandra to skip the batchlog with the @UNLOGGED@ option. If the @UNLOGGED@ option is used, operations are only atomic within a single partition.
+
+h4(#counterBatch). @COUNTER@
+
+Use the @COUNTER@ option for batched counter updates.  Unlike other updates in Cassandra, counter updates are not idempotent.
+
 h4(#batchOptions). @<option>@
 
 @BATCH@ supports both the @TIMESTAMP@ option, with similar semantic to the one described in the "@UPDATE@":#updateOptions statement (the timestamp applies to all the statement inside the batch). However, if used, @TIMESTAMP@ *must not* be used in the statements within the batch.