You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by Apache Wiki <wi...@apache.org> on 2011/11/03 23:48:48 UTC
[Cassandra Wiki] Update of "API" by JorisvanderWel
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 JorisvanderWel:
http://wiki.apache.org/cassandra/API?action=diff&rev1=28&rev2=29
Comment:
Moved API10 to here
- ## page was renamed from API07
- ## page was copied from API
== Overview ==
- The Cassandra Thrift API changed between [[API03|0.3]], [[API04|0.4]], [[API05|0.5]], [[API06|0.6]], and 0.7; this document explains the 0.7 version.
+ The Cassandra Thrift API changed between [[API03|0.3]], [[API04|0.4]], [[API05|0.5]], [[API06|0.6]], and [[API07|0.7]]; this document explains the 1.0 version.
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.
@@ -24, +22 @@
TApplicationException:: Internal server error or invalid Thrift method (possible if you are using an older version of a Thrift client with a newer build of the Cassandra server).
AuthenticationException:: Invalid authentication request (user does not exist or credentials invalid)
AuthorizationException:: Invalid authorization request (user does not have access to keyspace)
+ SchemaDisagreementException:: Schemas are not in agreement across all nodes
== Structures ==
=== ConsistencyLevel ===
@@ -35, +34 @@
||'''Level''' ||'''Behavior''' ||
||`ANY` ||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. ||
+ ||`TWO` ||Ensure that the write has been written to at least 2 replica's before responding to the client. ||
+ ||`THREE` ||Ensure that the write has been written to at least 3 replica's before responding to the client. ||
||`QUORUM` ||Ensure that the write has been written to `N / 2 + 1` replicas before responding to the client. ||
||`LOCAL_QUORUM` ||Ensure that the write has been written to `<ReplicationFactor>` / 2 + 1 nodes, within the local datacenter (requires `NetworkTopologyStrategy`) ||
||`EACH_QUORUM` ||Ensure that the write has been written to `<ReplicationFactor>` / 2 + 1 nodes in each datacenter (requires `NetworkTopologyStrategy`) ||
@@ -45, +46 @@
||'''Level''' ||'''Behavior''' ||
||`ANY` ||Not supported. You probably want ONE instead. ||
||`ONE` ||Will return the record returned by the first replica to respond. A consistency check is always done in a background thread to fix any consistency issues when `ConsistencyLevel.ONE` is used. This means subsequent calls will have correct data even if the initial read gets an older value. (This is called ReadRepair) ||
+ ||`TWO` ||Will query 2 replicas and return the record with the most recent timestamp. Again, the remaining replicas will be checked in the background. ||
+ ||`THREE` ||Will query 2 replicas and return the record with the most recent timestamp. ||
||`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. ||
||`LOCAL_QUORUM` ||Returns the record with the most recent timestamp once a majority of replicas within the local datacenter have replied. ||
||`EACH_QUORUM` ||Returns the record with the most recent timestamp once a majority of replicas within each datacenter have replied. ||
@@ -60, +63 @@
||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' ||
||`column` ||`Column` ||n/a ||N ||The `Column` if this `ColumnOrSuperColumn` is aggregating a `Column`. ||
||`super_column` ||`SuperColumn` ||n/a ||N ||The `SuperColumn` if this `ColumnOrSuperColumn` is aggregating a `SuperColumn` ||
-
+ ||`counter_column` ||`CounterColumn` ||n/a ||N ||The `CounterColumn` if this `ColumnOrSuperColumn` is aggregating a `CounterColumn`. ||
+ ||`counter_super_column` ||`CounterSuperColumn` ||n/a ||N ||The `CounterSuperColumn` if this `ColumnOrSuperColumn` is aggregating a `CounterSuperColumn` ||
=== Column ===
- The `Column` is a triplet of a name, value and timestamp. As described above, `Column` names are unique within a row. Timestamps are arbitrary - they can be any integer you specify, however they must be consistent across your application. It is recommended to use a timestamp value with a fine granularity, such as milliseconds since the UNIX epoch. See DataModel for more information.
+ The `Column` is a triplet of a name, value and timestamp. As described above, `Column` names are unique within a row. Timestamps are arbitrary - they can be any integer you specify, however they must be consistent across your application. It is recommended to use a timestamp value with a fine granularity, such as milliseconds since the UNIX epoch (the CLI uses microseconds). See DataModel for more information.
||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' ||
||`name` ||`binary` ||n/a ||Y ||The name of the `Column`. ||
||`value` ||`binary` ||n/a ||Y ||The value of the `Column`. ||
||`timestamp` ||`i64` ||n/a ||Y ||The timestamp of the `Column`. ||
-
+ ||`ttl` ||`i32` ||n/a ||N ||An optional, positive delay (in seconds) after which the `Column` will be automatically deleted. ||
@@ -80, +84 @@
||`name` ||`binary` ||n/a ||Y ||The name of the `SuperColumn`. ||
||`columns` ||`list<Column>` ||n/a ||Y ||The `Columns` within the `SuperColumn`. ||
+
+
+ === CounterColumn ===
+ A `CounterColumn` only allows for addition and subtraction. See [[Counters|Counters]] for more information.
+ ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' ||
+ ||`name` ||`binary` ||n/a ||Y ||The name of the `Column`. ||
+ ||`value` ||`binary` ||n/a ||Y ||The value of the `Column`. ||
+
+
+
+ === CounterSuperColumn ===
+ A `CounterSuperColumn` contains no data itself, but instead stores another level of `CounterColumn` below the key.
+ ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' ||
+ ||`name` ||`binary` ||n/a ||Y ||The name of the `SuperColumn`. ||
+ ||`columns` ||`list<CounterColumn>` ||n/a ||Y ||The `CounterColumns` within the `CounterSuperColumn`. ||
@@ -203, +222 @@
=== Deletion ===
A `Deletion` encapsulates an operation that will delete all columns less than the specified `timestamp` and matching the `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''' ||
- ||`timestamp` ||`i64` ||n/a ||Y ||The timestamp of the delete operation. ||
+ ||`timestamp` ||`i64` ||n/a ||N ||The timestamp of the delete operation. Must only be unset in the case of counter deletions. ||
||`super_column` ||`binary` ||n/a ||N ||The super column to delete the column(s) from. ||
||`predicate` ||`SlicePredicate` ||n/a ||N ||A predicate to match the column(s) to be deleted from the key/super column. ||
-
-
=== AuthenticationRequest ===
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''' ||
||`credentials` ||`map<string, string>` ||n/a ||Y ||A map of named credentials. ||
+ === IndexType ===
+ ||'''Type''' ||'''Behavior''' ||
+ ||KEYS ||A `ColumnFamily` backed index. ||
+
+ === ColumnDef ===
+ Describes a column in a column family.
+ ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||'''Description''' ||
+ ||`name` ||`binary` ||n/a ||Y ||The column name ||
+ ||`validation_class` ||`string` ||n/a ||Y ||The validation_class of the column as a class name ||
+ ||`index_type` ||`IndexType` ||n/a ||N ||The type of index ||
+ ||`index_name` ||`string` ||n/a ||N ||Name for the index. Both an index name and type must be specified. ||
+
+
+ === CfDef ===
+ Describes a column family
+ ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||
+ ||`keyspace` ||`string` ||n/a ||Y ||
+ ||`name` ||`string` ||n/a ||Y ||
+ ||`column_type` ||`string` ||`Standard` ||N ||
+ ||`comparator_type` ||`string` ||`BytesType` ||N ||
+ ||`subcomparator_type` ||`string` ||n/a ||N ||
+ ||`comment` ||`string` ||n/a ||N ||
+ ||`row_cache_size` ||`double` ||0 ||N ||
+ ||`key_cache_size` ||`double` ||200000 ||N ||
+ ||`read_repair_chance` ||`double` ||1.0||N ||
+ ||`column_metadata` ||`list<ColumnDef>` ||n/a ||N ||
+ ||`gc_grace_seconds` ||`i32` ||n/a ||N ||
+ ||`default_validation_class` ||`string` ||n/a ||N ||
+ ||`id` ||`i32` ||n/a ||N ||
+ ||`min_compaction_threshold` ||`i32` ||n/a ||N ||
+ ||`max_compaction_threshold` ||`i32` ||n/a ||N ||
+ ||`row_cache_save_period_in_seconds` ||`i32` ||n/a ||N ||
+ ||`key_cache_save_period_in_seconds` ||`i32` ||n/a ||N ||
+ ||`memtable_flush_after_mins` ||`i32` ||n/a ||N ||
+ ||`memtable_throughput_in_mb` ||`i32` ||n/a ||N ||
+ ||`memtable_operations_in_millions` ||`double` ||n/a ||N ||
+ ||`replicate_on_write` ||`bool` ||n/a ||N ||
+ ||`merge_shards_chance` ||`double` ||n/a ||N ||
+ ||`key_validation_class` ||`string` ||n/a ||N ||
+ ||`row_cache_provider` ||`string` ||`org.apache.cassandra.cache.ConcurrentLinkedHashCacheProvider` ||N ||
+ ||`key_alias` ||`binary` ||n/a ||N ||
+
+ === KsDef ===
+ Describes a keyspace.
+ ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||
+ ||`name` ||`string` ||n/a ||Y ||
+ ||`strategy_class` ||`string` ||n/a ||Y ||
+ ||`strategy_options` ||`map<string,string>` ||n/a ||N ||
+ ||`cf_defs` ||`list<CfDef>` ||n/a ||Y ||
+ ||`durable_writes` ||`bool` ||true ||N ||
+
+
+ === Compression ===
+ ||'''Type''' ||
+ ||`GZIP` ||
+ ||`NONE` ||
+
+ === CqlResultType ===
+ ||'''Type''' ||
+ ||`ROWS` ||
+ ||`VOID` ||
+ ||`INT` ||
+
+
+ === CqlRow ===
+ Row returned from a CQL query.
+ ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||
+ ||`key` ||`binary` ||n/a ||Y ||
+ ||`columns` ||`list<Column>` ||n/a ||Y ||
+
+
+ === CqlRow ===
+ Result returned from a CQL query.
+ ||'''Attribute''' ||'''Type''' ||'''Default''' ||'''Required''' ||
+ ||`type` ||`CqlResultType` ||n/a ||Y ||
+ ||`rows` ||`list<CqlRow>` ||n/a ||N ||
+ ||`num` ||`i32` ||n/a ||N ||
== Method calls ==
=== login ===
- . `void login(keyspace, auth_request)`
+ . `void login(AuthenticationRequest 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.
+ Authenticates with the cluster 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.
+
+ === set_keyspace ===
+ . `void set_keyspace(string keyspace)`
+
+ Set the keyspace to use for subsequent requests. Throws InvalidRequestException for an unknown keyspace.
=== get ===
- . `ColumnOrSuperColumn get(key, column_path, consistency_level)`
+ . `ColumnOrSuperColumn get(binary key, ColumnPath column_path, ConsistencyLevel consistency_level)`
Get the `Column` or `SuperColumn` at the given `column_path`. If no value is present, `NotFoundException` is thrown. (This is the only method that can throw an exception under non-failure conditions.)
=== get_slice ===
- . `list<ColumnOrSuperColumn> get_slice(key, column_parent, predicate, consistency_level)`
+ . `list<ColumnOrSuperColumn> get_slice(binary key, ColumnParent column_parent, SlicePredicate predicate, ConsistencyLevel consistency_level)`
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_slice ===
- . `map<string,list<ColumnOrSuperColumn>> multiget_slice(keys, column_parent, predicate, consistency_level)`
+ . `map<string,list<ColumnOrSuperColumn>> multiget_slice(list<binary> keys, ColumnParent column_parent, SlicePredicate predicate, ConsistencyLevel consistency_level)`
Retrieves slices for `column_parent` and `predicate` on each of the given keys in parallel. Keys are a `list<string> of the keys to get slices for.
This is similar to `get_range_slices`, except it operates on a set of non-contiguous keys instead of a range of keys.
=== get_count ===
- . `i32 get_count(key, column_parent, predicate, consistency_level)`
+ . `i32 get_count(binary key, ColumnParent column_parent, SlicePredicate predicate, ConsistencyLevel consistency_level)`
Counts the columns present in `column_parent` within the `predicate.`
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.
=== multiget_count ===
- . `map<string, i32> multiget_count(keys, column_parent, predicate, consistency_level)`
+ . `map<string, i32> multiget_count(list<binary> keys, ColumnParent column_parent, SlicePredicate predicate, ConsistencyLevel consistency_level)`
A combination of `multiget_slice `and` get_count.`
=== get_range_slices ===
- . `list<KeySlice> get_range_slices(column_parent, predicate, range, consistency_level)`
+ . `list<KeySlice> get_range_slices(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. Note that when using RandomPartitioner, keys are stored in the order of their MD5 hash, making it impossible to get a meaningful range of keys between two endpoints.
=== get_indexed_slices ===
- . `list<KeySlice> get_indexed_slices(column_parent, index_clause, predicate, consistency_level)`
+ . `list<KeySlice> get_indexed_slices(ColumnParent column_parent, IndexClause index_clause, SlicePredicate predicate, ConsistencyLevel consistency_level)`
Like `get_range_slices`, returns a list of slices, but uses `IndexClause` instead of `KeyRange`. To use this method, the underlying `ColumnFamily` of the `ColumnParent` must have been configured with a column_metadata attribute, specifying at least the name and index_type attributes. See `CfDef` and `ColumnDef` above for the list of attributes. Note: the `IndexClause` must contain one `IndexExpression` with an `EQ` operator on a configured index column. Other `IndexExpression` structs may be added to the `IndexClause` for non-indexed columns to further refine the results of the `EQ` expression.
=== insert ===
- . `insert(key, column_path, column, consistency_level)`
+ . `insert(binary key, ColumnParent column_parent, Column column, ConsistencyLevel consistency_level)`
- Insert a `Column` consisting of (`name`, `value`, `timestamp`) at the given `column_path.column_family` and optional `column_path.super_column`. Note that a !SuperColumn cannot directly contain binary values -- it can only contain sub-Columns. Only one sub-Column may be inserted at a time, as well.
+ Insert a `Column` consisting of (`name`, `value`, `timestamp`, `ttl`) at the given ColumnParent. Note that a !SuperColumn cannot directly contain binary values -- it can only contain sub-Columns. Only one sub-Column may be inserted at a time, as well.
=== batch_mutate ===
- . `batch_mutate(mutation_map, consistency_level)`
+ . `batch_mutate(map<binary, map<string, list<Mutation>>> mutation_map, ConsistencyLevel consistency_level)`
Executes the specified mutations on the keyspace. `mutation_map` is a `map<string, map<string, vector<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, vector<Mutation>>>`. To be more specific, the outer map key is a row key, the inner map key is the column family name.
A `Mutation` specifies either columns to insert or columns to delete. See `Mutation` and `Deletion` above for more details.
+ === add ===
+ . `add(binary key, ColumnParent column_parent, CounterColumn column, ConsistencyLevel consistency_level)`
+
+ Increments a `CounterColumn` consisting of (`name`, `value`) at the given ColumnParent. Note that a !SuperColumn cannot directly contain binary values -- it can only contain sub-Columns.
+
=== remove ===
- . `remove(key, column_path, timestamp, consistency_level)`
+ . `remove(binary key, ColumnPath column_path, i64 timestamp, ConsistencyLevel consistency_level)`
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.
+
+ === remove_counter ===
+ . `remove_counter(binary key, ColumnPath column_path, ConsistencyLevel consistency_level)`
+
+ Remove a counter from the row specified by `key` at the granularity specified by `column_path`. 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 counters have limited support for deletes: if you remove a counter, you must wait to issue any following update until the delete has reached all the nodes and all of them have been fully compacted.
=== truncate ===
. `truncate(string column_family)`
@@ -290, +399 @@
Gets the name of the cluster.
+ === describe_schema_versions ===
+ . `map<string, list<string>> describe_schema_versions`
+
+ For each schema version present in the cluster, returns a list of nodes at that version. Hosts that do not respond will be under the key DatabaseDescriptor.INITIAL_VERSION. The cluster is all on the same version if the size of the map is 1.
+
=== describe_keyspace ===
. `KsDef describe_keyspace(string keyspace)`
@@ -340, +454 @@
Drops a keyspace. Creates a snapshot and then submits a 'graveyard' compaction during which the abandoned files will be deleted. Returns the new schema version ID.
+ === system_update_keyspace ===
+ . `string system_update_keyspace(KsDef ks_def)`
+
+ Updates properties of a keyspace. returns the new schema id.
+
+ === system_update_column_family ===
+ . `string system_update_column_family(CfDef cf_def)`
+
+ === execute_cql_query ===
+ . `CqlResult execute_cql_query(binary query, Compression compression)`
+
+ Executes a CQL (Cassandra Query Language) statement and returns a CqlResult containing the results.
+ Throws InvalidRequestException, UnavailableException, TimedOutException, SchemaDisagreementException.
+
== Examples ==
[[http://wiki.apache.org/cassandra/ClientExamples|There are a few examples on this page over here.]]