I added some support for composite columns to libQtCassandra 0.4.3.

This allows one to read and write columns with composite names. This just means a way to read a column with optimized comparisons (i.e. if you include a 32 bit number, it uses 4 bytes in the table, whereas, using a name with a 32 bit number converted to hexadecimal would be 8 bytes, not counting posssible separators and potential for the separators to not allow easy constant sorting.)

Contrary to belief, the different part of a composite column name are not separated by colons. This is only in the CLI and many 4th generation languages (i.e. PHP, Ruby, etc.) The lower level implementation expects an array of names defined as follow:

<size><name><terminator>

Where the <size> parameter is an unsigned short (2 bytes) number written in big endian (i.e. a size of 0x0005 is written as 0x00 first and then 0x05 in the stream of bytes.)

The <name> is whatever the column expects at that position. You must make sure it matches the type of the column. If UTF-8 then you must have a valid UTF-8 string (i.e. no 0xFF characters written as is!) If Integer then you must pass the integer as a big endian number on a number of bytes that correspond to the Integer (i.e. a Long is expected to be exactly 8 bytes.)

The <terminator> may be -1, 0, or 1 depending on the need and where or when the value is passed down to Cassandra. When just reading or writing a cell in a row, you want to use zero. If you are querying, then -1 and 1 can be used too. The -1 means this value excluded. The 1 means end of column names. Obviously, the zero and 1 means this value included. The fact that you can end the list means you can query rows with a limited number of composite column names instead of all of them. (To insert or read a specific cell you must always have all the names so zero is always used; for a query, however, the idea is to use 0 when you want to have an exact match including that value, and -1 excluding that value.)

Let see an example for inserting a new value in Cassandra:

• Say you have a composite column definition as follow:

CompositeColumn(UTF8, Integer, ASCII)

• Inserting a new value with composite key: "ŒIL:12994:SNAP"

The first character in the key is Π(O and E glued together, which is called a diagraph, ligature, or grapheme) must be translated to proper UTF-8. This means 0xC5 and 0x92. The resulting string is 4 bytes. Therefore the size is 0x00 0x04. The final string of bytes looks like this:

"ŒIL" -- 0x00 0x04 0xC5 0x92 0x49 0x4C 0x00

"12994" -- 0x00 0x04 0x00 0x00 0x32 0xC2 0x00

"SNAP" -- 0x00 0x04 0x53 0x4E 0x41 0x50 0x00

So we send all those bytes to the Cassandra server via Thrift as the column key:

00:04:C5:92:49:4c:00:00:04:00:00:32:C2:00:00:04:53:4E:41:50:00

(Note: the fact that all 3 composite keys are 4 bytes is just due to my poor choice of column names.)

As we can see, the integer is sent as an integer (in big endian). This means we do NOT have to convert the integer to ASCII and then back to an integer before sending it to the Cassandra server. Instead, we use a set of QCassandraValue objects and no conversions takes place1

Note that if some names are missing, the system can send a NULL name. To do so, the system uses three zeros (size of zero, no data, and the null terminator):

0x00 0x00 0x00

A NULL name is perfectly valid, but it may add complexities when querying your columns.

• Read a specific value back

This is exactly the same as the Insert function. The column names are all terminated with 0x00 and they all should include all the names as defined in the insert.

• Querying a range of columns2

Querying is very similar to inserting and direct reading only the number of columns specified can be 1 to n, n being the total number defined when creating the table. For this reason, you must terminate the list of column names with a one. From the same example, it would look like one of these:

00:04:C5:92:49:4c:01
00:04:C5:92:49:4c:00:00:04:00:00:32:C2:01
00:04:C5:92:49:4c:00:00:04:00:00:32:C2:00:00:04:53:4E:41:50:01

The <terminator> can also be set to -1 to retrieve columns with a name larger than the specified value (instead of larger or equal.)

To start querying from the very beginning, use a completely empty key ("").

• 1. I know that converting integers to and from ASCII is not that bad. It is rather fast. Now just think about doing such 1 million time a minute and you can imagine how much computation time you save! But to take it further, the computer would have to determine the column type in order to convert anything... that would also be somewhat slow, although it could be done once and cached. Next you'd have to also convert floating points and that is not only much slower than integers, it generally is not a good idea for you are likely to lose a few bits in the process!
• 2. At the time of writing, I did not yet implement this part, although the encoding is for sure exactly the same, the terminator of -1 versus 0 needs to be tested to ensure the encoding is indeed working as documented.