mirror of https://github.com/apache/cassandra
354 lines
17 KiB
Thrift
354 lines
17 KiB
Thrift
#!/usr/local/bin/thrift --java --php --py
|
|
# Licensed to the Apache Software Foundation (ASF) under one
|
|
# or more contributor license agreements. See the NOTICE file
|
|
# distributed with this work for additional information
|
|
# regarding copyright ownership. The ASF licenses this file
|
|
# to you under the Apache License, Version 2.0 (the
|
|
# "License"); you may not use this file except in compliance
|
|
# with the License. You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
#
|
|
# Interface definition for Cassandra Service
|
|
#
|
|
|
|
namespace java org.apache.cassandra.service
|
|
namespace cpp org.apache.cassandra
|
|
namespace csharp Apache.Cassandra
|
|
namespace py cassandra
|
|
namespace php cassandra
|
|
namespace perl Cassandra
|
|
|
|
# Thrift.rb has a bug where top-level modules that include modules
|
|
# with the same name are not properly referenced, so we can't do
|
|
# Cassandra::Cassandra::Client.
|
|
namespace rb CassandraThrift
|
|
|
|
|
|
#
|
|
# constants
|
|
#
|
|
|
|
# for clients checking that server and it have same thrift definitions.
|
|
# no promises are made other than "if both are equal, you're good."
|
|
# in particular, don't try to parse numeric information out and assume
|
|
# that a "greater" version is a superset of a "smaller" one.
|
|
const string VERSION = "0.5-beta1"
|
|
|
|
|
|
#
|
|
# data structures
|
|
#
|
|
|
|
/** Basic unit of data within a ColumnFamily.
|
|
* @param name. A column name can act both as structure (a label) or as data (like value). Regardless, the name of the column
|
|
* is used as a key to its value.
|
|
* @param value. Some data
|
|
* @param timestamp. Used to record when data was sent to be written.
|
|
*/
|
|
struct Column {
|
|
1: required binary name,
|
|
2: required binary value,
|
|
3: required i64 timestamp,
|
|
}
|
|
|
|
/** A named list of columns.
|
|
* @param name. see Column.name.
|
|
* @param columns. A collection of standard Columns. The columns within a super column are defined in an adhoc manner.
|
|
* Columns within a super column do not have to have matching structures (similarly named child columns).
|
|
*/
|
|
struct SuperColumn {
|
|
1: required binary name,
|
|
2: required list<Column> columns,
|
|
}
|
|
|
|
/**
|
|
Methods for fetching rows/records from Cassandra will return either a single instance of ColumnOrSuperColumn or a list
|
|
of ColumnOrSuperColumns (get_slice()). If you're looking up a SuperColumn (or list of SuperColumns) then the resulting
|
|
instances of ColumnOrSuperColumn will have the requested SuperColumn in the attribute super_column. For queries resulting
|
|
in Columns, those values will be in the attribute column. This change was made between 0.3 and 0.4 to standardize on
|
|
single query methods that may return either a SuperColumn or Column.
|
|
|
|
@param column. The Column returned by get() or get_slice().
|
|
@param super_column. The SuperColumn returned by get() or get_slice().
|
|
*/
|
|
struct ColumnOrSuperColumn {
|
|
1: optional Column column,
|
|
2: optional SuperColumn super_column,
|
|
}
|
|
|
|
|
|
#
|
|
# Exceptions
|
|
# (note that internal server errors will raise a TApplicationException, courtesy of Thrift)
|
|
#
|
|
|
|
/** A specific column was requested that does not exist. */
|
|
exception NotFoundException {
|
|
}
|
|
|
|
/** Invalid request could mean keyspace or column family does not exist, required parameters are missing, or a parameter is malformed.
|
|
why contains an associated error message.
|
|
*/
|
|
exception InvalidRequestException {
|
|
1: required string why
|
|
}
|
|
|
|
/** Not all the replicas required could be created and/or read. */
|
|
exception UnavailableException {
|
|
}
|
|
|
|
/** RPC timeout was exceeded. either a node failed mid-operation, or load was too high, or the requested op was too large. */
|
|
exception TimedOutException {
|
|
}
|
|
|
|
|
|
#
|
|
# service api
|
|
#
|
|
/** 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 strongly consistent behavior; that is, readers will always see the most
|
|
* recent write. 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.
|
|
*
|
|
* Write:
|
|
* ZERO Ensure nothing. A write happens asynchronously in background
|
|
* 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 <code><ReplicationFactor></code> nodes before responding to the client.
|
|
*
|
|
* Read:
|
|
* ZERO Not supported, because it doesn't make sense.
|
|
* ONE Will return the record returned by the first node 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 'read repair'.)
|
|
* QUORUM Will query all storage nodes and return the record with the most recent timestamp once it has at least a
|
|
* majority of replicas reported. Again, the remaining replicas will be checked in the background.
|
|
* ALL Not yet supported, but we plan to eventually.
|
|
*/
|
|
enum ConsistencyLevel {
|
|
ZERO = 0,
|
|
ONE = 1,
|
|
QUORUM = 2,
|
|
DCQUORUM = 3,
|
|
DCQUORUMSYNC = 4,
|
|
ALL = 5,
|
|
}
|
|
|
|
/**
|
|
ColumnParent is used when selecting groups of columns from the same ColumnFamily. In directory structure terms, imagine
|
|
ColumnParent as ColumnPath + '/../'.
|
|
|
|
See also <a href="cassandra.html#Struct_ColumnPath">ColumnPath</a>
|
|
*/
|
|
struct ColumnParent {
|
|
3: required string column_family,
|
|
4: optional binary super_column,
|
|
}
|
|
|
|
/** The ColumnPath is the path to a single column in Cassandra. It might make sense to think of ColumnPath and
|
|
* ColumnParent in terms of a directory structure.
|
|
*
|
|
* ColumnPath is used to looking up a single column.
|
|
*
|
|
* @param column_family. The name of the CF of the column being looked up.
|
|
* @param super_column. The super column name.
|
|
* @param column. The column name.
|
|
*/
|
|
struct ColumnPath {
|
|
3: required string column_family,
|
|
4: optional binary super_column,
|
|
5: optional binary column,
|
|
}
|
|
|
|
/**
|
|
A slice range is a structure that stores basic range, ordering and limit information for a query that will return
|
|
multiple columns. It could be thought of as Cassandra's version of LIMIT and ORDER BY
|
|
|
|
@param start. The column name to start the slice with. This attribute is not required, though there is no default value,
|
|
and can be safely set to '', i.e., an empty byte array, to start with the first column name. Otherwise, it
|
|
must a valid value under the rules of the Comparator defined for the given ColumnFamily.
|
|
@param finish. The column name to stop the slice at. This attribute is not required, though there is no default value,
|
|
and can be safely set to an empty byte array to not stop until 'count' results are seen. Otherwise, it
|
|
must also be a value value to the ColumnFamily Comparator.
|
|
@param reversed. Whether the results should be ordered in reversed order. Similar to ORDER BY blah DESC in SQL.
|
|
@param count. How many keys to return. Similar to LIMIT 100 in SQL. May be arbitrarily large, but Thrift will
|
|
materialize the whole result into memory before returning it to the client, so be aware that you may
|
|
be better served by iterating through slices by passing the last value of one call in as the 'start'
|
|
of the next instead of increasing 'count' arbitrarily large.
|
|
*/
|
|
struct SliceRange {
|
|
1: required binary start,
|
|
2: required binary finish,
|
|
3: required bool reversed=0,
|
|
4: required i32 count=100,
|
|
}
|
|
|
|
/**
|
|
A SlicePredicate is similar to a mathematic predicate (see http://en.wikipedia.org/wiki/Predicate_(mathematical_logic)),
|
|
which is described as "a property that the elements of a set have in common."
|
|
|
|
SlicePredicate's in Cassandra are described with either a list of column_names or a SliceRange. If column_names is
|
|
specified, slice_range is ignored.
|
|
|
|
@param column_name. A list of column names to retrieve. This can be used similar to Memcached's "multi-get" feature
|
|
to fetch N known column names. For instance, if you know you wish to fetch columns 'Joe', 'Jack',
|
|
and 'Jim' you can pass those column names as a list to fetch all three at once.
|
|
@param slice_range. A SliceRange describing how to range, order, and/or limit the slice.
|
|
*/
|
|
struct SlicePredicate {
|
|
1: optional list<binary> column_names,
|
|
2: optional SliceRange slice_range,
|
|
}
|
|
|
|
/**
|
|
A KeySlice is key followed by the data it maps to. A collection of KeySlice is returned by the get_range_slice operation.
|
|
|
|
@param key. a row key
|
|
@param columns. List of data represented by the key. Typically, the list is pared down to only the columns specified by
|
|
a SlicePredicate.
|
|
*/
|
|
struct KeySlice {
|
|
1: required string key,
|
|
2: required list<ColumnOrSuperColumn> columns,
|
|
}
|
|
|
|
service Cassandra {
|
|
# retrieval methods
|
|
|
|
/**
|
|
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.)
|
|
*/
|
|
ColumnOrSuperColumn get(1:required string keyspace,
|
|
2:required string key,
|
|
3:required ColumnPath column_path,
|
|
4:required ConsistencyLevel consistency_level=1)
|
|
throws (1:InvalidRequestException ire, 2:NotFoundException nfe, 3:UnavailableException ue, 4:TimedOutException te),
|
|
|
|
/**
|
|
Get the group of columns contained by column_parent (either a ColumnFamily name or a ColumnFamily/SuperColumn name
|
|
pair) specified by the given SlicePredicate. If no matching values are found, an empty list is returned.
|
|
*/
|
|
list<ColumnOrSuperColumn> get_slice(1:required string keyspace,
|
|
2:required string key,
|
|
3:required ColumnParent column_parent,
|
|
4:required SlicePredicate predicate,
|
|
5:required ConsistencyLevel consistency_level=1)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
map<string,ColumnOrSuperColumn> multiget(1:required string keyspace,
|
|
2:required list<string> keys,
|
|
3:required ColumnPath column_path,
|
|
4:required ConsistencyLevel consistency_level=1)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
/**
|
|
Performs a get_slice for column_parent and predicate for the given keys in parallel.
|
|
*/
|
|
map<string,list<ColumnOrSuperColumn>> multiget_slice(1:required string keyspace,
|
|
2:required list<string> keys,
|
|
3:required ColumnParent column_parent,
|
|
4:required SlicePredicate predicate,
|
|
5:required ConsistencyLevel consistency_level=1)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
/**
|
|
returns the number of columns for a particular <code>key</code> and <code>ColumnFamily</code> or <code>SuperColumn</code>.
|
|
*/
|
|
i32 get_count(1:required string keyspace,
|
|
2:required string key,
|
|
3:required ColumnParent column_parent,
|
|
4:required ConsistencyLevel consistency_level=1)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
/** @deprecated; use get_range_slice instead */
|
|
list<string> get_key_range(1:required string keyspace,
|
|
2:required string column_family,
|
|
3:required string start="",
|
|
4:required string finish="",
|
|
5:required i32 count=100,
|
|
6:required ConsistencyLevel consistency_level=1)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
/**
|
|
returns a subset of columns for a range of keys.
|
|
*/
|
|
list<KeySlice> get_range_slice(1:required string keyspace,
|
|
2:required ColumnParent column_parent,
|
|
3:required SlicePredicate predicate,
|
|
4:required string start_key="",
|
|
5:required string finish_key="",
|
|
6:required i32 row_count=100,
|
|
7:required ConsistencyLevel consistency_level=1)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
# modification methods
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
void insert(1:required string keyspace,
|
|
2:required string key,
|
|
3:required ColumnPath column_path,
|
|
4:required binary value,
|
|
5:required i64 timestamp,
|
|
6:required ConsistencyLevel consistency_level=0)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
void batch_insert(1:required string keyspace,
|
|
2:required string key,
|
|
3:required map<string, list<ColumnOrSuperColumn>> cfmap,
|
|
4:required ConsistencyLevel consistency_level=0)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
/**
|
|
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.
|
|
*/
|
|
void remove(1:required string keyspace,
|
|
2:required string key,
|
|
3:required ColumnPath column_path,
|
|
4:required i64 timestamp,
|
|
5:ConsistencyLevel consistency_level=0)
|
|
throws (1:InvalidRequestException ire, 2:UnavailableException ue, 3:TimedOutException te),
|
|
|
|
|
|
// Meta-APIs -- APIs to get information about the node or cluster,
|
|
// rather than user data. The nodeprobe program provides usage examples.
|
|
|
|
/** get property whose value is of type string. */
|
|
string get_string_property(1:required string property),
|
|
|
|
/** get property whose value is list of strings. */
|
|
list<string> get_string_list_property(1:required string property),
|
|
|
|
/** describe specified keyspace */
|
|
map<string, map<string, string>> describe_keyspace(1:required string keyspace)
|
|
throws (1:NotFoundException nfe),
|
|
}
|
|
|