1 #!/usr/local/bin/thrift --java --php --py
2 # Licensed to the Apache Software Foundation (ASF) under one
3 # or more contributor license agreements. See the NOTICE file
4 # distributed with this work for additional information
5 # regarding copyright ownership. The ASF licenses this file
6 # to you under the Apache License, Version 2.0 (the
7 # "License"); you may not use this file except in compliance
8 # with the License. You may obtain a copy of the License at
10 # http://www.apache.org/licenses/LICENSE-2.0
12 # Unless required by applicable law or agreed to in writing, software
13 # distributed under the License is distributed on an "AS IS" BASIS,
14 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 # See the License for the specific language governing permissions and
16 # limitations under the License.
18 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
19 # *** PLEASE REMEMBER TO EDIT THE VERSION CONSTANT WHEN MAKING CHANGES ***
20 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23 # Interface definition for Cassandra Service
26 namespace netcore Apache.Cassandra.Test
28 # Thrift.rb has a bug where top-level modules that include modules
29 # with the same name are not properly referenced, so we can't do
30 # Cassandra::Cassandra::Client.
31 namespace rb CassandraThrift
33 # The API version (NOT the product version), composed as a dot delimited
34 # string with major, minor, and patch level components.
36 # - Major: Incremented for backward incompatible changes. An example would
37 # be changes to the number or disposition of method arguments.
38 # - Minor: Incremented for backward compatible changes. An example would
39 # be the addition of a new (optional) method.
40 # - Patch: Incremented for bug fixes. The patch level should be increased
41 # for every edit that doesn't result in a change to major/minor.
43 # See the Semantic Versioning Specification (SemVer) http://semver.org.
44 const string VERSION = "19.24.0"
51 /** Basic unit of data within a ColumnFamily.
52 * @param name, the name by which this column is set and retrieved. Maximum 64KB long.
53 * @param value. The data associated with the name. Maximum 2GB long, but in practice you should limit it to small numbers of MB (since Thrift must read the full value into memory to operate on it).
54 * @param timestamp. The timestamp is used for conflict detection/resolution when two columns with same name need to be compared.
55 * @param ttl. An optional, positive delay (in seconds) after which the column will be automatically deleted.
58 1: required binary name,
59 2: optional binary value,
60 3: optional i64 timestamp,
64 /** A named list of columns.
65 * @param name. see Column.name.
66 * @param columns. A collection of standard Columns. The columns within a super column are defined in an adhoc manner.
67 * Columns within a super column do not have to have matching structures (similarly named child columns).
70 1: required binary name,
71 2: required list<Column> columns,
74 struct CounterColumn {
75 1: required binary name,
79 struct CounterSuperColumn {
80 1: required binary name,
81 2: required list<CounterColumn> columns
85 Methods for fetching rows/records from Cassandra will return either a single instance of ColumnOrSuperColumn or a list
86 of ColumnOrSuperColumns (get_slice()). If you're looking up a SuperColumn (or list of SuperColumns) then the resulting
87 instances of ColumnOrSuperColumn will have the requested SuperColumn in the attribute super_column. For queries resulting
88 in Columns, those values will be in the attribute column. This change was made between 0.3 and 0.4 to standardize on
89 single query methods that may return either a SuperColumn or Column.
91 If the query was on a counter column family, you will either get a counter_column (instead of a column) or a
92 counter_super_column (instead of a super_column)
94 @param column. The Column returned by get() or get_slice().
95 @param super_column. The SuperColumn returned by get() or get_slice().
96 @param counter_column. The Counterolumn returned by get() or get_slice().
97 @param counter_super_column. The CounterSuperColumn returned by get() or get_slice().
99 struct ColumnOrSuperColumn {
100 1: optional Column column,
101 2: optional SuperColumn super_column,
102 3: optional CounterColumn counter_column,
103 4: optional CounterSuperColumn counter_super_column
109 # (note that internal server errors will raise a TApplicationException, courtesy of Thrift)
112 /** A specific column was requested that does not exist. */
113 exception NotFoundException {
116 /** Invalid request could mean keyspace or column family does not exist, required parameters are missing, or a parameter is malformed.
117 why contains an associated error message.
119 exception InvalidRequestException {
120 1: required string why
123 /** Not all the replicas required could be created and/or read. */
124 exception UnavailableException {
127 /** RPC timeout was exceeded. either a node failed mid-operation, or load was too high, or the requested op was too large. */
128 exception TimedOutException {
131 /** invalid authentication request (invalid keyspace, user does not exist, or credentials invalid) */
132 exception AuthenticationException {
133 1: required string why
136 /** invalid authorization request (user does not have access to keyspace) */
137 exception AuthorizationException {
138 1: required string why
141 /** schemas are not in agreement across all nodes */
142 exception SchemaDisagreementException {
150 * The ConsistencyLevel is an enum that controls both read and write
151 * behavior based on the ReplicationFactor of the keyspace. The
152 * different consistency levels have different meanings, depending on
153 * if you're doing a write or read operation.
155 * If W + R > ReplicationFactor, where W is the number of nodes to
156 * block for on write, and R the number to block for on reads, you
157 * will have strongly consistent behavior; that is, readers will
158 * always see the most recent write. Of these, the most interesting is
159 * to do QUORUM reads and writes, which gives you consistency while
160 * still allowing availability in the face of node failures up to half
161 * of <ReplicationFactor>. Of course if latency is more important than
162 * consistency then you can use lower values for either or both.
164 * Some ConsistencyLevels (ONE, TWO, THREE) refer to a specific number
165 * of replicas rather than a logical concept that adjusts
166 * automatically with the replication factor. Of these, only ONE is
167 * commonly used; TWO and (even more rarely) THREE are only useful
168 * when you care more about guaranteeing a certain level of
169 * durability, than consistency.
171 * Write consistency levels make the following guarantees before reporting success to the client:
172 * ANY Ensure that the write has been written once somewhere, including possibly being hinted in a non-target node.
173 * ONE Ensure that the write has been written to at least 1 node's commit log and memory table
174 * TWO Ensure that the write has been written to at least 2 node's commit log and memory table
175 * THREE Ensure that the write has been written to at least 3 node's commit log and memory table
176 * QUORUM Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes
177 * LOCAL_QUORUM Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes, within the local datacenter (requires NetworkTopologyStrategy)
178 * EACH_QUORUM Ensure that the write has been written to <ReplicationFactor> / 2 + 1 nodes in each datacenter (requires NetworkTopologyStrategy)
179 * ALL Ensure that the write is written to <code><ReplicationFactor></code> nodes before responding to the client.
181 * Read consistency levels make the following guarantees before returning successful results to the client:
182 * ANY Not supported. You probably want ONE instead.
183 * ONE Returns the record obtained from a single replica.
184 * TWO Returns the record with the most recent timestamp once two replicas have replied.
185 * THREE Returns the record with the most recent timestamp once three replicas have replied.
186 * QUORUM Returns the record with the most recent timestamp once a majority of replicas have replied.
187 * LOCAL_QUORUM Returns the record with the most recent timestamp once a majority of replicas within the local datacenter have replied.
188 * EACH_QUORUM Returns the record with the most recent timestamp once a majority of replicas within each datacenter have replied.
189 * ALL Returns the record with the most recent timestamp once all replicas have replied (implies no replica may be down)..
191 enum ConsistencyLevel {
203 ColumnParent is used when selecting groups of columns from the same ColumnFamily. In directory structure terms, imagine
204 ColumnParent as ColumnPath + '/../'.
206 See also <a href="cassandra.html#Struct_ColumnPath">ColumnPath</a>
208 struct ColumnParent {
209 3: required string column_family,
210 4: optional binary super_column,
213 /** The ColumnPath is the path to a single column in Cassandra. It might make sense to think of ColumnPath and
214 * ColumnParent in terms of a directory structure.
216 * ColumnPath is used to looking up a single column.
218 * @param column_family. The name of the CF of the column being looked up.
219 * @param super_column. The super column name.
220 * @param column. The column name.
223 3: required string column_family,
224 4: optional binary super_column,
225 5: optional binary column,
229 A slice range is a structure that stores basic range, ordering and limit information for a query that will return
230 multiple columns. It could be thought of as Cassandra's version of LIMIT and ORDER BY
232 @param start. The column name to start the slice with. This attribute is not required, though there is no default value,
233 and can be safely set to '', i.e., an empty byte array, to start with the first column name. Otherwise, it
234 must a valid value under the rules of the Comparator defined for the given ColumnFamily.
235 @param finish. The column name to stop the slice at. This attribute is not required, though there is no default value,
236 and can be safely set to an empty byte array to not stop until 'count' results are seen. Otherwise, it
237 must also be a valid value to the ColumnFamily Comparator.
238 @param reversed. Whether the results should be ordered in reversed order. Similar to ORDER BY blah DESC in SQL.
239 @param count. How many columns to return. Similar to LIMIT in SQL. May be arbitrarily large, but Thrift will
240 materialize the whole result into memory before returning it to the client, so be aware that you may
241 be better served by iterating through slices by passing the last value of one call in as the 'start'
242 of the next instead of increasing 'count' arbitrarily large.
245 1: required binary start,
246 2: required binary finish,
247 3: required bool reversed=0,
248 4: required i32 count=100,
252 A SlicePredicate is similar to a mathematic predicate (see http://en.wikipedia.org/wiki/Predicate_(mathematical_logic)),
253 which is described as "a property that the elements of a set have in common."
255 SlicePredicate's in Cassandra are described with either a list of column_names or a SliceRange. If column_names is
256 specified, slice_range is ignored.
258 @param column_name. A list of column names to retrieve. This can be used similar to Memcached's "multi-get" feature
259 to fetch N known column names. For instance, if you know you wish to fetch columns 'Joe', 'Jack',
260 and 'Jim' you can pass those column names as a list to fetch all three at once.
261 @param slice_range. A SliceRange describing how to range, order, and/or limit the slice.
263 struct SlicePredicate {
264 1: optional list<binary> column_names,
265 2: optional SliceRange slice_range,
276 struct IndexExpression {
277 1: required binary column_name,
278 2: required IndexOperator op,
279 3: required binary value,
283 1: required list<IndexExpression> expressions
284 2: required binary start_key,
285 3: required i32 count=100,
289 The semantics of start keys and tokens are slightly different.
290 Keys are start-inclusive; tokens are start-exclusive. Token
291 ranges may also wrap -- that is, the end token may be less
292 than the start one. Thus, a range from keyX to keyX is a
293 one-element range, but a range from tokenY to tokenY is the
297 1: optional binary start_key,
298 2: optional binary end_key,
299 3: optional string start_token,
300 4: optional string end_token,
301 5: required i32 count=100
305 A KeySlice is key followed by the data it maps to. A collection of KeySlice is returned by the get_range_slice operation.
307 @param key. a row key
308 @param columns. List of data represented by the key. Typically, the list is pared down to only the columns specified by
312 1: required binary key,
313 2: required list<ColumnOrSuperColumn> columns,
317 1: required binary key,
318 2: required i32 count
322 * Note that the timestamp is only optional in case of counter deletion.
325 1: optional i64 timestamp,
326 2: optional binary super_column,
327 3: optional SlicePredicate predicate,
331 A Mutation is either an insert (represented by filling column_or_supercolumn) or a deletion (represented by filling the deletion attribute).
332 @param column_or_supercolumn. An insert to a column or supercolumn (possibly counter column or supercolumn)
333 @param deletion. A deletion of a column or supercolumn
336 1: optional ColumnOrSuperColumn column_or_supercolumn,
337 2: optional Deletion deletion,
340 struct EndpointDetails {
342 2: string datacenter,
343 3: optional string rack
347 A TokenRange describes part of the Cassandra ring, it is a mapping from a range to
348 endpoints responsible for that range.
349 @param start_token The first token in the range
350 @param end_token The last token in the range
351 @param endpoints The endpoints responsible for the range (listed by their configured listen_address)
352 @param rpc_endpoints The endpoints responsible for the range (listed by their configured rpc_address)
355 1: required string start_token,
356 2: required string end_token,
357 3: required list<string> endpoints,
358 4: optional list<string> rpc_endpoints
359 5: optional list<EndpointDetails> endpoint_details,
363 Authentication requests can contain any data, dependent on the IAuthenticator used
365 struct AuthenticationRequest {
366 1: required map<string, string> credentials
374 /* describes a column in a column family. */
376 1: required binary name,
377 2: required string validation_class,
378 3: optional IndexType index_type,
379 4: optional string index_name,
380 5: optional map<string,string> index_options
384 /* describes a column family. */
386 1: required string keyspace,
387 2: required string name,
388 3: optional string column_type="Standard",
389 5: optional string comparator_type="BytesType",
390 6: optional string subcomparator_type,
391 8: optional string comment,
392 12: optional double read_repair_chance=1.0,
393 13: optional list<ColumnDef> column_metadata,
394 14: optional i32 gc_grace_seconds,
395 15: optional string default_validation_class,
397 17: optional i32 min_compaction_threshold,
398 18: optional i32 max_compaction_threshold,
399 24: optional bool replicate_on_write,
400 25: optional double merge_shards_chance,
401 26: optional string key_validation_class,
402 28: optional binary key_alias,
403 29: optional string compaction_strategy,
404 30: optional map<string,string> compaction_strategy_options,
405 32: optional map<string,string> compression_options,
406 33: optional double bloom_filter_fp_chance,
409 /* describes a keyspace. */
411 1: required string name,
412 2: required string strategy_class,
413 3: optional map<string,string> strategy_options,
416 4: optional i32 replication_factor,
418 5: required list<CfDef> cf_defs,
419 6: optional bool durable_writes=1,
422 /** CQL query compression */
434 /** Row returned from a CQL query */
436 1: required binary key,
437 2: required list<Column> columns
441 1: required map<binary,string> name_types,
442 2: required map<binary,string> value_types,
443 3: required string default_name_type,
444 4: required string default_value_type
448 1: required CqlResultType type,
449 2: optional list<CqlRow> rows,
451 4: optional CqlMetadata schema
454 struct CqlPreparedResult {
455 1: required i32 itemId,
456 2: required i32 count
462 void login(1: required AuthenticationRequest auth_request) throws (1:AuthenticationException authnx, 2:AuthorizationException authzx),
465 void set_keyspace(1: required string keyspace) throws (1:InvalidRequestException ire),
470 Get the Column or SuperColumn at the given column_path. If no value is present, NotFoundException is thrown. (This is
471 the only method that can throw an exception under non-failure conditions.)
473 ColumnOrSuperColumn get(1:required binary key,
474 2:required ColumnPath column_path,
475 3:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
476 throws (1:InvalidRequestException ire, 2:NotFoundException nfe, 3:UnavailableException ue, 4:TimedOutException te),
479 Get the group of columns contained by column_parent (either a ColumnFamily name or a ColumnFamily/SuperColumn name
480 pair) specified by the given SlicePredicate. If no matching values are found, an empty list is returned.
482 list<ColumnOrSuperColumn> get_slice(1:required binary key,
483 2:required ColumnParent column_parent,
484 3:required SlicePredicate predicate,
485 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
486 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
489 returns the number of columns matching <code>predicate</code> for a particular <code>key</code>,
490 <code>ColumnFamily</code> and optionally <code>SuperColumn</code>.
492 i32 get_count(1:required binary key,
493 2:required ColumnParent column_parent,
494 3:required SlicePredicate predicate,
495 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
496 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
499 Performs a get_slice for column_parent and predicate for the given keys in parallel.
501 map<binary,list<ColumnOrSuperColumn>> multiget_slice(1:required list<binary> keys,
502 2:required ColumnParent column_parent,
503 3:required SlicePredicate predicate,
504 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
505 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
508 Perform a get_count in parallel on the given list<binary> keys. The return value maps keys to the count found.
510 map<binary, i32> multiget_count(1:required list<binary> keys,
511 2:required ColumnParent column_parent,
512 3:required SlicePredicate predicate,
513 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
514 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
517 returns a subset of columns for a contiguous range of keys.
519 list<KeySlice> get_range_slices(1:required ColumnParent column_parent,
520 2:required SlicePredicate predicate,
521 3:required KeyRange range,
522 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
523 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
525 /** Returns the subset of columns specified in SlicePredicate for the rows matching the IndexClause */
526 list<KeySlice> get_indexed_slices(1:required ColumnParent column_parent,
527 2:required IndexClause index_clause,
528 3:required SlicePredicate column_predicate,
529 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
530 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
532 # modification methods
535 * Insert a Column at the given column_parent.column_family and optional column_parent.super_column.
537 void insert(1:required binary key,
538 2:required ColumnParent column_parent,
539 3:required Column column,
540 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
541 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
544 * Increment or decrement a counter.
546 void add(1:required binary key,
547 2:required ColumnParent column_parent,
548 3:required CounterColumn column,
549 4:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
550 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
553 Remove data from the row specified by key at the granularity specified by column_path, and the given timestamp. Note
554 that all the values in column_path besides column_path.column_family are truly optional: you can remove the entire
555 row by just specifying the ColumnFamily, or you can remove a SuperColumn or a single Column by specifying those levels too.
557 void remove(1:required binary key,
558 2:required ColumnPath column_path,
559 3:required i64 timestamp,
560 4:ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
561 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
564 * Remove a counter at the specified location.
565 * Note that counters have limited support for deletes: if you remove a counter, you must wait to issue any following update
566 * until the delete has reached all the nodes and all of them have been fully compacted.
568 void remove_counter(1:required binary key,
569 2:required ColumnPath path,
570 3:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
571 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
575 Mutate many columns or super columns for many row keys. See also: Mutation.
577 mutation_map maps key to column family to a list of Mutation objects to take place at that scope.
579 void batch_mutate(1:required map<binary, map<string, list<Mutation>>> mutation_map,
580 2:required ConsistencyLevel consistency_level=ConsistencyLevel.ONE)
581 throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
584 Truncate will mark and entire column family as deleted.
585 From the user's perspective a successful call to truncate will result complete data deletion from cfname.
586 Internally, however, disk space will not be immediatily released, as with all deletes in cassandra, this one
587 only marks the data as deleted.
588 The operation succeeds only if all hosts in the cluster at available and will throw an UnavailableException if
591 void truncate(1:required string cfname)
592 throws (1: InvalidRequestException ire, 2: UnavailableException ue, 3: TimedOutException te),
596 // Meta-APIs -- APIs to get information about the node or cluster,
597 // rather than user data. The nodeprobe program provides usage examples.
600 * for each schema version present in the cluster, returns a list of nodes at that version.
601 * hosts that do not respond will be under the key DatabaseDescriptor.INITIAL_VERSION.
602 * the cluster is all on the same version if the size of the map is 1.
604 map<string, list<string>> describe_schema_versions()
605 throws (1: InvalidRequestException ire),
607 /** list the defined keyspaces in this cluster */
608 list<KsDef> describe_keyspaces()
609 throws (1:InvalidRequestException ire),
611 /** get the cluster name */
612 string describe_cluster_name(),
614 /** get the thrift api version */
615 string describe_version(),
617 /** get the token ring: a map of ranges to host addresses,
618 represented as a set of TokenRange instead of a map from range
619 to list of endpoints, because you can't use Thrift structs as
621 https://issues.apache.org/jira/browse/THRIFT-162
623 for the same reason, we can't return a set here, even though
624 order is neither important nor predictable. */
625 list<TokenRange> describe_ring(1:required string keyspace)
626 throws (1:InvalidRequestException ire),
628 /** returns the partitioner used by this cluster */
629 string describe_partitioner(),
631 /** returns the snitch used by this cluster */
632 string describe_snitch(),
634 /** describe specified keyspace */
635 KsDef describe_keyspace(1:required string keyspace)
636 throws (1:NotFoundException nfe, 2:InvalidRequestException ire),
638 /** experimental API for hadoop/parallel query support.
639 may change violently and without warning.
641 returns list of token strings such that first subrange is (list[0], list[1]],
642 next is (list[1], list[2]], etc. */
643 list<string> describe_splits(1:required string cfName,
644 2:required string start_token,
645 3:required string end_token,
646 4:required i32 keys_per_split)
647 throws (1:InvalidRequestException ire),
649 /** adds a column family. returns the new schema id. */
650 string system_add_column_family(1:required CfDef cf_def)
651 throws (1:InvalidRequestException ire, 2:SchemaDisagreementException sde),
653 /** drops a column family. returns the new schema id. */
654 string system_drop_column_family(1:required string column_family)
655 throws (1:InvalidRequestException ire, 2:SchemaDisagreementException sde),
657 /** adds a keyspace and any column families that are part of it. returns the new schema id. */
658 string system_add_keyspace(1:required KsDef ks_def)
659 throws (1:InvalidRequestException ire, 2:SchemaDisagreementException sde),
661 /** drops a keyspace and any column families that are part of it. returns the new schema id. */
662 string system_drop_keyspace(1:required string keyspace)
663 throws (1:InvalidRequestException ire, 2:SchemaDisagreementException sde),
665 /** updates properties of a keyspace. returns the new schema id. */
666 string system_update_keyspace(1:required KsDef ks_def)
667 throws (1:InvalidRequestException ire, 2:SchemaDisagreementException sde),
669 /** updates properties of a column family. returns the new schema id. */
670 string system_update_column_family(1:required CfDef cf_def)
671 throws (1:InvalidRequestException ire, 2:SchemaDisagreementException sde),
674 * Executes a CQL (Cassandra Query Language) statement and returns a
675 * CqlResult containing the results.
677 CqlResult execute_cql_query(1:required binary query, 2:required Compression compression)
678 throws (1:InvalidRequestException ire,
679 2:UnavailableException ue,
680 3:TimedOutException te,
681 4:SchemaDisagreementException sde)
685 * Prepare a CQL (Cassandra Query Language) statement by compiling and returning
686 * - the type of CQL statement
687 * - an id token of the compiled CQL stored on the server side.
688 * - a count of the discovered bound markers in the statement
690 CqlPreparedResult prepare_cql_query(1:required binary query, 2:required Compression compression)
691 throws (1:InvalidRequestException ire)
695 * Executes a prepared CQL (Cassandra Query Language) statement by passing an id token and a list of variables
696 * to bind and returns a CqlResult containing the results.
698 CqlResult execute_prepared_cql_query(1:required i32 itemId, 2:required list<string> values)
699 throws (1:InvalidRequestException ire,
700 2:UnavailableException ue,
701 3:TimedOutException te,
702 4:SchemaDisagreementException sde)