[Cassandra Wiki] Update of "API" by EldonStegall

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cassandra Wiki" for change notification.

The "API" page has been changed by EldonStegall.
http://wiki.apache.org/cassandra/API?action=diff&rev1=73&rev2=74

--------------------------------------------------

  == Overview ==
- 
  '''NOTE:''' This documents the low-level wire protocol used to communicate with Cassandra. This is not intended to be used directly in applications; rather it is highly recommended that application developers use one of the higher-level clients that are linked to from ClientOptions. That said, this page may still be useful for application developers wanting to better understand the data model or the underlying operations that are available.
  
  The Cassandra Thrift API changed substantially after [[API03|0.3]], with minor, backwards-compatible changes for [[API04|0.4]], 0.5 and [[API06|0.6]]; this document explains the 0.5 version with annotations for the changes in 0.6 and 0.7.
@@ -30, +29 @@

  === ConsistencyLevel ===
  The `ConsistencyLevel` is an `enum` that controls both read and write behavior based on `<ReplicationFactor>` in your `storage-conf.xml`. The different consistency levels have different meanings, depending on if you're doing a write or read operation.  Note that if `W` + `R` > `ReplicationFactor`, where W is the number of nodes to block for on write, and R the number to block for on reads, you will have the most consistent behavior (* see below). Of these, the most interesting is to do `QUORUM` reads and writes, which gives you consistency while still allowing availability in the face of node failures up to half of `ReplicationFactor`.  Of course if latency is more important than consistency then you can use lower values for either or both.
  
- * Because the repair replication process only requires a write to reach a single node to propagate, a write which 'fails' to meet consistency requirements will still appear eventually so long at it was written to at least one node. With W and R both using QUORUM, the best consistency we can achieve is the guarantee that we will receive the same value regardless of which nodes we read from. However, we can still peform a W=QUORUM that "fails" but reaches one server, perform a R=QUORUM that reads the old value, and then sometime later perform a R=QUORUM that reads the new value. 
+ * Because the repair replication process only requires a write to reach a single node to propagate, a write which 'fails' to meet consistency requirements will still appear eventually so long at it was written to at least one node. With W and R both using QUORUM, the best consistency we can achieve is the guarantee that we will receive the same value regardless of which nodes we read from. However, we can still peform a W=QUORUM that "fails" but reaches one server, perform a R=QUORUM that reads the old value, and then sometime later perform a R=QUORUM that reads the new value.
  
  Terminology: "N" is the ReplicationFactor; "replicas" are the `N` nodes that are directly responsible for the data; "nodes" are any/all nodes in the cluster, including HintedHandoff participants.
  
@@ -39, +38 @@

  ||`ZERO` ||Ensure nothing. A write happens asynchronously in background. Until [[https://issues.apache.org/jira/browse/CASSANDRA-685|CASSANDRA-685]] is fixed: If too many of these queue up, buffers will explode and bad things will happen. ||
  ||`ANY` ||(Requires 0.6) Ensure that the write has been written to at least 1 node, including HintedHandoff recipients. ||
  ||`ONE` ||Ensure that the write has been written to at least 1 replica's commit log and memory table before responding to the client. ||
- ||`QUORUM` || Ensure that the write has been written to `N / 2 + 1` replicas before responding to the client. ||
+ ||`QUORUM` ||Ensure that the write has been written to `N / 2 + 1` replicas before responding to the client. ||
- ||`DCQUORUM` || (No longer in 0.7) Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes, within the local datacenter (requires NetworkTopologyStrategy) ||
+ ||`DCQUORUM` ||(No longer in 0.7) Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes, within the local datacenter (requires NetworkTopologyStrategy) ||
- ||`LOCAL_QUORUM` || (Requires 0.7) Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes, within the local datacenter (requires NetworkTopologyStrategy) ||
+ ||`LOCAL_QUORUM` ||(Requires 0.7) Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes, within the local datacenter (requires NetworkTopologyStrategy) ||
- ||`EACH_QUORUM`  || (Requires 0.7) Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes in each datacenter (requires NetworkTopologyStrategy) ||
+ ||`EACH_QUORUM` ||(Requires 0.7) Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes in each datacenter (requires NetworkTopologyStrategy) ||
  ||`ALL` ||Ensure that the write is written to all `N` replicas before responding to the client.  Any unresponsive replicas will fail the operation. ||
  
  
@@ -54, +53 @@

  ||`QUORUM` ||Will query all replicas and return the record with the most recent timestamp once it has at least a majority of replicas (`N / 2 + 1`) reported.  Again, the remaining replicas will be checked in the background. ||
  ||`DCQUORUM` ||(No longer in 0.7) When using rack aware placement strategy reads are keept within a data center. See https://issues.apache.org/jira/browse/CASSANDRA-492 ||
  ||`LOCAL_QUORUM` ||(Requires 0.7) Returns the record with the most recent timestamp once a majority of replicas within the local datacenter have replied. ||
- ||`EACH_QUORUM` || (Requires 0.7) Returns the record with the most recent timestamp once a majority of replicas within each datacenter have replied. ||
+ ||`EACH_QUORUM` ||(Requires 0.7) Returns the record with the most recent timestamp once a majority of replicas within each datacenter have replied. ||
  ||`ALL` ||Will query all replicas and return the record with the most recent timestamp once all replicas have replied.  Any unresponsive replicas will fail the operation. ||
+ 
  
  '''Note: '''Thrift prior to version 0.6 defaults to a Write Consistency Level of ZERO. Different language toolkits may have their own Consistency Level defaults as well. To ensure the desired Consistency Level, you should always explicitly set the Consistency Level.
  
@@ -229, +229 @@

  ||`replication_factor` ||`integer` ||None ||Yes ||Number of data replicas ||
  ||`cf_defs` ||`list<CfDef>` ||None ||Yes ||list of column family definitions. Can be empty, but not null ||
  
+ 
  ''Requires Cassandra 0.7 beta 2''
  
  ==== IndexExpression ====
  ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' ||
- ||`column_name` || `binary` || None || Yes || The name of the column to perform the operand on ||
+ ||`column_name` ||`binary` ||None ||Yes ||The name of the column to perform the operand on ||
- ||`op`|| `IndexOperator` || None || Yes || The IndexOperator to apply||
+ ||`op` ||`IndexOperator` ||None ||Yes ||The IndexOperator to apply ||
- || `value` || `binary` || None || Yes || The value to use in the comparison||
+ ||`value` ||`binary` ||None ||Yes ||The value to use in the comparison ||
+ 
  
  ==== IndexClause ====
  ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' ||
- ||`expressions` || `list<IndexExpression>` || None || Yes || The list of IndexExpressions to AND together. Semantics from the client work similar to boolean logical operand && or SQL 'AND' ||
+ ||`expressions` ||`list<IndexExpression>` ||None ||Yes ||The list of IndexExpressions to AND together. Semantics from the client work similar to boolean logical operand && or SQL 'AND' ||
- ||`start_key`|| `binary` || None || Yes || Start key range to begin searching on ||
+ ||`start_key` ||`binary` ||None ||Yes ||Start key range to begin searching on ||
- || `count` || `i32` || 100 || No || The maximum rows to return||
+ ||`count` ||`i32` ||100 ||No ||The maximum rows to return ||
  
  
  == Method calls ==
@@ -285, +287 @@

  
  === get_indexed_slices ===
  ''Requires Cassandra 0.7 beta 2''
+ 
-   .  ` list<KeySlice> get_indexed_slices(ColumnParent column_parent, IndexClause index_clause, SlicePredicate column_predicate, ConsistencyLevel consistency_level)`
+  . ` list<KeySlice> get_indexed_slices(ColumnParent column_parent, IndexClause index_clause, SlicePredicate column_predicate, ConsistencyLevel consistency_level)`
  
  Returns a list of key slices that meed the IndexClause critera.  Note that index clause must contain at least a single EQ operation.  The columns specified in the IndexExpressions will also need to be specified as indexed when the CF is created.
  
@@ -299, +302 @@

  === get_range_slices ===
  ''Requires Cassandra 0.6''
  
+ ''In'''' Cassandra 0.7, first parameter "keyspace" is omitted, since the connection should already be authenticated to a keyspace.''
+ 
   . `list<KeySlice> get_range_slices(string keyspace, ColumnParent column_parent, SlicePredicate predicate, KeyRange range, ConsistencyLevel consistency_level)`
  
  Replaces `get_range_slice`. Returns a list of slices for the keys within the specified `KeyRange`. Unlike get_key_range, this applies the given predicate to all keys in the range, not just those with undeleted matching data.