Cassandra Data Model and Operations
This page was created by someone trying to understand Cassandra. Until it is reviewed & blessed by someone who really knows you read it at your own risk...
This page is an alternate attempt at capturing the Cassandra data model and its operations. The descriptions below show the original Thrift API (as of 0.3) as well as a simplified notation borrowed from the Bright Yellow Cow blog entry
, i.e. using [] to mean 'list of' and ( , ) for tuple construction.
Simple Column families
A column family has a name and an arbitrary number of columns, each column is a name, value, and timestamp tuple. Columns may be name sorted or time sorted, which affects range operations on them. In pseudo-notation:
family -> [(name, value, timestamp)]
Since each (top-level) row has an arbitrary set of columns in each column family, we can really think of this as a two dimensional map:
family -> [(key1, key2, value, timestamp)]
In the Thrift API all this is defined as:
struct column_t {
1: string columnName,
2: binary value,
3: i64 timestamp,
}
typedef map< string, list<column_t> > column_family_map
insert
Insert a column.
insert(family, key1, key2, value, timestamp)
I believe the block_for parameter is to wait for N replicas to ACK the write. From the Thrift API:
void insert(1:string tablename, 2:string key, 3:string columnFamily_column, 4:binary cellData,
5:i64 timestamp, 6:i32 block_for=0)
throws (1: InvalidRequestException ire, 2: UnavailableException ue),
remove
Remove a column
remove(family, key1, key2, timestamp)
The timestamp specifies exactly which insertion is removed (the column could have been re-inserted "later"). From the Thrift API:
void remove(1:string tablename, 2:string key, 3:string columnFamily_column, 4:i64 timestamp,
5:i32 block_for=0)
throws (1: InvalidRequestException ire, 2: UnavailableException ue),
get_column
Retrieve a specific column for a key.
get_column(family, key1, key2) -> (key2, value, timestamp)
From the Thrift API:
column_t get_column(1:string tablename, 2:string key, 3:string columnFamily_column) throws (1: InvalidRequestException ire, 2: NotFoundException nfe),
get_slice
Retrieve all columns for a key:
get_slice(family, key1) -> [(key2, value, timestamp)]
plus start/count parameters allow pagination of the results. From the Thrift API:
list<column_t> get_slice(1:string tablename, 2:string key, 3:string columnFamily_column,
4:i32 start=-1, 5:i32 count=-1)
throws (1: InvalidRequestException ire, 2: NotFoundException nfe),
get_slice_by_name_range
Retrieve a range of columns for a key:
get_slice(family, key1, key2_start, key2_end) -> [(key2, value, timestamp)]
plus a count parameter allows limiting the result. From the Thrift API:
list<column_t> get_slice_by_name_range(1:string tablename, 2:string key, 3:string columnFamily,
4:string start, 5:string end, 6:i32 count=-1)
throws (1: InvalidRequestException ire, 2: NotFoundException nfe),
get_slice_by_names
Retrieve a specific set of columns for a key:
get_slice_by_names(family, key1, [key2_1, key2_2, ..., key2_N]) -> [(key2, value, timestamp)]
From the Thrift API:
list<column_t> get_slice_by_names(1:string tablename, 2:string key, 3:string columnFamily, 4:list<string> columnNames) throws (1: InvalidRequestException ire, 2: NotFoundException nfe),
get_slice_from
Retrieve columns for a key starting from a specific column.
get_slice_from(family, key1, key2_start) -> [(key, value, timestamp)]
plus an ascending/descending flag and a count determine the direction and limit of the enumeration. From the Thrift API:
list<column_t> get_slice_from(1:string tablename, 2:string key, 3:string columnFamily_column,
4:bool isAscending, 5:i32 count)
throws (1: InvalidRequestException ire, 2: NotFoundException nfe),
get_columns_since
Retrieves columns for a key starting from a specific timestamp.
get_columns_since(family, key1, key2, timestamp) -> [(key, value, timestamp)]
From the Thrift API:
list<column_t> get_columns_since(1:string tablename, 2:string key, 3:string columnFamily_column, 4:i64 timeStamp) throws (1: InvalidRequestException ire, 2: NotFoundException nfe),
get_column_count
Return the number of columns for a key.
get_column_count(family, key1, key2) -> count
From the Thrift API:
i32 get_column_count(1:string tablename, 2:string key, 3:string columnFamily_column) throws (1: InvalidRequestException ire),
batch_insert
Insert a batch of columns for a key.
batch_insert(family, key1, [(key2, value, timestamp)])
From the Thrift API:
struct batch_mutation_t {
1: string table,
2: string key,
3: column_family_map cfmap,
}
void batch_insert(1: batch_mutation_t batchMutation, 2:i32 block_for=0)
throws (1: InvalidRequestException ire, 2: UnavailableException ue),
Super Column
A super column family has a name and an arbitrary number of super columns, each super column has an arbitrary number of columns. "Currently" supercolumns are always name-sorted, and their subcolumns are always time-sorted. In pseudo-notation:
super_family -> [(super_column, [(column_name, value, timestamp)])]
It is tempting but inaccurate to think of this as a three dimensional map:
super_family -> [(key1, key2, key3, value, timestamp)]
What's more accurate is to continue thinking of this as a two-dimensional map, just like regular column families, but where the values are really sets of name-value pairs (plus timestamps to be accurate). So it's really like this:
Simple column families: column_family -> [(key1, key2, value, timestamp)] Super column families: column_family -> [(key1, key2, [(key3, value, timestamp)])]
In the Thrift API all this is defined as:
struct superColumn_t {
1: string name,
2: list<column_t> columns,
}
typedef map< string, list<superColumn_t> > superColumn_family_map
get_superColumn
Retrieves a super column from a column family for a key.
get_superColumn(super_family, key1, key2) -> (key2, [(key3, value, timestamp)])
From the Thrift API:
superColumn_t get_superColumn(1:string tablename, 2:string key, 3:string columnFamily) throws (1: InvalidRequestException ire, 2: NotFoundException nfe),
Note that the 3rd argument should really be called columnFamily_superColumnName
get_slice_super
Retrieve the super columns in a super column family for a key.
get_slice_super(super_family, key1) -> [(key2, [(key3, value, timestamp)])]
The start/count parameters allow pagination of the results. From the Thrift API:
list<superColumn_t> get_slice_super(1:string tablename, 2:string key, 3:string columnFamily_superColumnName,
4:i32 start=-1, 5:i32 count=-1)
throws (1: InvalidRequestException ire),
Note that the 3rd argument should really be called columnFamily
get_slice_super_by_names
Retrieve a set of super columns in a super column family.
get_slice_super_by_names(family, key1, [key2_1, key2_2, ..., key2_N]) -> [(key2, [(key3, value, timestamp)])]
From the Thrift API:
list<superColumn_t> get_slice_super_by_names(1:string tablename, 2:string key, 3:string columnFamily,
4:list<string> superColumnNames)
throws (1: InvalidRequestException ire),
batch_insert_superColumn
Insert a super column.
batch_insert_superColumn(family, key1, key2, [(key3, value, timestamp)])
From the Thrift API:
struct batch_mutation_super_t {
1: string table,
2: string key,
3: superColumn_family_map cfmap,
}
void batch_insert_superColumn(1:batch_mutation_super_t batchMutationSuper, 2:i32 block_for=0)
throws (1: InvalidRequestException ire, 2: UnavailableException ue),
Other operations
get_key_range
Retrieve the list of keys that exist in a range. A key exists if at least on column in one column family exists for the key. A list of column families can be passed into the call to reduce the search to columns in those families.
get_key_range(family, key1_start, key1_end, [key2_1, key2_2, ..., key2_N]) -> [key1_1, key1_2, ..., key1_M]
From the Thrift API:
# range query: returns matching keys
list<string> get_key_range(1:string tablename, 2:list<string> columnFamilies=[], 3:string startWith="", 4:string stopAt="",
5:i32 maxResults=1000)
throws (1: InvalidRequestException ire),
touch
Intended to force index information for the key into cache, but is buggy and to be deprecated.
touch(key1)
From the Thrift API:
oneway void touch(1:string key, 2:bool fData),