Dear Wiki user, You have subscribed to a wiki page or wiki category on "Cassandra Wiki" for change notification.
The "API06" page has been changed by HubertChang. http://wiki.apache.org/cassandra/API06?action=diff&rev1=52&rev2=53 -------------------------------------------------- ## page was copied from API == Overview == - The Cassandra Thrift API changed between 0.3, 0.4, 0.5 and 0.6; this document explains the 0.5 version with annotations for the changes in 0.6. The [[API03|0.3 API]] and [[API04|0.4 API]] are archived for reference. + The Cassandra Thrift API changed between 0.3, 0.4, 0.5 and 0.6; this document explains the 0.6 version. The references for the previous version are [[API03|0.3 API]] , [[API04|0.4 API]] and [[API|0.5 API with 0.6 change annotations]]. Cassandra's client API is built entirely on top of Thrift. It should be noted that these documents mention default values, but these are not generated in all of the languages that Thrift supports. Full examples of using Cassandra from Thrift, including setup boilerplate, are found on ThriftExamples. Higher-level clients are linked from ClientOptions. @@ -33, +33 @@ ==== Write ==== ||'''Level''' ||'''Behavior''' || ||`ZERO` ||Ensure nothing. A write happens asynchronously in background || - ||`ANY` ||(Requires 0.6) Ensure that the write has been written to at least 1 node, including hinted recipients. || + ||`ANY` ||Ensure that the write has been written to at least 1 node, including hinted recipients. || ||`ONE` ||Ensure that the write has been written to at least 1 node's commit log and memory table before responding to the client. || ||`QUORUM` ||Ensure that the write has been written to `<ReplicationFactor> / 2 + 1` nodes before responding to the client. || ||`ALL` ||Ensure that the write is written to all `<ReplicationFactor>` nodes before responding to the client. Any unresponsive nodes will fail the operation. || @@ -48, +48 @@ ||`ALL` ||Will query all nodes and return the record with the most recent timestamp once all nodes have replied. Any unresponsive nodes 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. + '''Note: '''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. === ColumnOrSuperColumn === Due to the lack of inheritance in Thrift, `Column` and `SuperColumn` structures are aggregated by the `ColumnOrSuperColumn` structure. This is used wherever either a `Column` or `SuperColumn` would normally be expected. @@ -124, +124 @@ === KeyRange === - '''''Requires Cassandra 0.6''''' - A `KeyRange` is used by `get_range_slices` to define the range of keys to get the slices for. The semantics of start keys and tokens are slightly different. Keys are start-inclusive; tokens are start-exclusive. Token ranges may also wrap -- that is, the end token may be less than the start one. Thus, a range from keyX to keyX is a one-element range, but a range from tokenY to tokenY is the full ring. @@ -140, +138 @@ === KeySlice === - '''''Requires Cassandra 0.6''''' A `KeySlice` encapsulates a mapping of a key to the slice of columns for it as returned by the get_range_slices operation. Normally, when slicing a single key, a `list<ColumnOrSuperColumn>` of the slice would be returned. When slicing multiple or a range of keys, a `list<KeySlice>` is instead returned so that each slice can be mapped to their key. ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' || @@ -151, +148 @@ === TokenRange === - '''''Requires Cassandra 0.6''''' A structure representing structural information about the cluster provided by the `describe` utility methods detailed below. ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' || @@ -163, +159 @@ === Mutation === - '''''Requires Cassandra 0.6''''' A `Mutation` encapsulates either a column to insert, or a deletion to execute for a key. Like `ColumnOrSuperColumn`, the two properties are mutually exclusive - you may only set one on a Mutation. ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' || @@ -174, +169 @@ === Deletion === - '''''Requires Cassandra 0.6''''' A `Deletion` encapsulates an operation that will delete all columns matching the specified `timestamp` and `predicate`. If `super_column` is specified, the `Deletion` will operate on columns within the `SuperColumn` - otherwise it will operate on columns in the top-level of the key. ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' || @@ -186, +180 @@ === AuthenticationRequest === - '''''Requires Cassandra 0.6''''' A structure that encapsulates a request for the connection to be authenticated. The authentication credentials are arbitrary - this structure simply provides a mapping of credential name to credential value. ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' || @@ -197, +190 @@ == Method calls == === login === - ''Requires Cassandra 0.6'' - . `void login(keyspace, auth_request)` Authenticates with the cluster for operations on the specified keyspace using the specified `AuthenticationRequest` credentials. Throws `AuthenticationException` if the credentials are invalid or `AuthorizationException` if the credentials are valid, but not for the specified keyspace. @@ -213, +204 @@ Get the group of columns contained by `column_parent` (either a `ColumnFamily` name or a `ColumnFamily/SuperColumn` name pair) specified by the given `SlicePredicate` struct. - === multiget === - ''Deprecated in 0.6 - use `multiget_slice` instead'' - - . `map<string,ColumnOrSuperColumn> multiget(keyspace, keys, column_path, consistency_level)` - - Perform a `get` for `column_path` in parallel on the given `list<string> keys`. The return value maps keys to the `ColumnOrSuperColumn` found. If no value corresponding to a key is present, the key will still be in the map, but both the `column` and `super_column` references of the `ColumnOrSuperColumn` object it maps to will be null. - === multiget_slice === . `map<string,list<ColumnOrSuperColumn>> multiget_slice(keyspace, keys, column_parent, predicate, consistency_level)` @@ -234, +218 @@ The method is not O(1). It takes all the columns from disk to calculate the answer. The only benefit of the method is that you do not need to pull all the columns over Thrift interface to count them. - === get_range_slice === - ''Deprecated in 0.6 - use `get_range_slices` instead'' - - . `list<KeySlice> get_range_slice(keyspace, column_parent, predicate, start_key, finish_key, row_count=100, consistency_level)` - - Replaces `get_key_range`. Returns a list of slices, sorted by row key, starting with start, ending with finish (both inclusive) and at most count long. The empty string ("") can be used as a sentinel value to get the first/last existing key (or first/last column in the column predicate parameter). Unlike get_key_range, this applies the given predicate to all keys in the range, not just those with undeleted matching data. This method is only allowed when using an order-preserving partitioner. - === get_range_slices === - ''Requires Cassandra 0.6'' - . `list<KeySlice> get_range_slices(keyspace, column_parent, predicate, range, 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. This method is only allowed when using an order-preserving partitioner. - - === get_key_range === - ''Deprecated in 0.5 - use `get_range_slice` instead'' - - ''Removed in 0.6 - use `get_range_slices` instead'' - - . `list<string> get_key_range(keyspace, column_family, start, finish, count=100, consistency_level)` - - Returns a list of keys starting with `start`, ending with `finish` (both inclusive), and at most `count` long. The empty string ("") can be used as a sentinel value to get the first/last existing key. (The semantics are similar to the corresponding components of `SliceRange`.) This method is only allowed when using an order-preserving partitioner. === insert === . `insert(keyspace, key, column_path, value, timestamp, consistency_level)` Insert a `Column` consisting of (`column_path.column`, `value`, `timestamp`) at the given `column_path.column_family` and optional `column_path.super_column`. Note that `column_path.column` is here required, since a !SuperColumn cannot directly contain binary values -- it can only contain sub-Columns. - === batch_insert === - ''Deprecated in 0.6 - use `batch_mutate` instead'' - - . `batch_insert(keyspace, key, batch_mutation, consistency_level)` - - Insert Columns or SuperColumns across different Column Families for the same row key. `batch_mutation` is a `map<string, list<ColumnOrSuperColumn>>` -- a map which pairs column family names with the relevant `ColumnOrSuperColumn` objects to insert. - === batch_mutate === - ''Requires Cassandra 0.6'' - . `batch_mutate(keyspace, mutation_map, consistency_level)` Executes the specified mutations on the keyspace. `mutation_map` is a `map<string, map<string, list<Mutation>>>`; the outer map maps the key to the inner map, which maps the column family to the `Mutation`; can be read as: `map<key : string, map<column_family : string, list<Mutation>>>`. To be more specific, the outer map key is a row key, the inner map key is the column family name. @@ -284, +241 @@ Remove data from the row specified by `key` at the granularity specified by `column_path`, and the given `timestamp`. Note that all the values in `column_path` besides `column_path.column_family` are truly optional: you can remove the entire row by just specifying the !ColumnFamily, or you can remove a !SuperColumn or a single Column by specifying those levels too. Note that the `timestamp` is needed, so that if the commands are replayed in a different order on different nodes, the same result is produced. === describe_keyspaces === - ''Requires Cassandra 0.6'' - . `set<string> describe_keyspaces()` Gets a list of all the keyspaces configured for the cluster. === describe_cluster_name === - ''Requires Cassandra 0.6'' - . `string describe_cluster_name()` Gets the name of the cluster. === describe_version === - ''Requires Cassandra 0.6'' - . `string describe_version()` Gets the Thrift API version. === describe_ring === - ''Requires Cassandra 0.6'' - . `list<TokenRange> describe_ring(keyspace)` Gets the token ring; a map of ranges to host addresses. Represented as a set of `TokenRange` instead of a map from range to list of endpoints, because you can't use Thrift structs as map keys: https://issues.apache.org/jira/browse/THRIFT-162 for the same reason, we can't return a set here, even though order is neither important nor predictable. === describe_keyspace === - ''Requires Cassandra 0.6'' - . `map<string, map<string, string>> describe_keyspace(keyspace)` Gets information about the specified keyspace.
