What’s New in Cassandra 2.2: JSON Support

By Tyler Hobbs -  June 15, 2015 | 5 Comments

One of the several improvements in Cassandra 2.2 is the extension of CQL to make it easier to work with JSON documents. The SELECT and INSERT statements now include a JSON-focused variant, and two new native functions have been added to convert to and from JSON.

JSON != Schemaless

When designing this feature, we wanted to ensure that users would continue to work with data in a type-safe, schema-enforced way. For that reason, working through JSON does not allow you to bypass Cassandra’s schema. All data is still validated against the same types, and the schema must be manually defined up-front with a normal CREATE TABLE statement.


The INSERT statement now accepts a JSON variant. Suppose we have a table defined like this:

    id text PRIMARY KEY,
    age int,
    state text

Normally we would insert a row like this:

INSERT INTO users (id, age, state) VALUES ('user123', 42, 'TX');

The JSON version looks like this:

INSERT INTO users JSON '{"id": "user123", "age": 42, "state": "TX"}';

The JSON-encoded map is simply a CQL string literal that is a JSON encoding of a map where keys are column names and values are column values. This means that drivers don’t need to do anything special to support INSERT JSON. For example, with the python driver, you could prepare and execute the statement like so:

insert_statment = session.prepare('INSERT INTO users JSON ?')
json_values = '{"id": "user123", "age": 42, "state": "TX"}'
session.execute(insert_statement, [json_values])

This should work nicely with existing JSON libraries, making it easy to load documents:

import json

prepared = session.prepare('INSERT INTO users JSON ?')

while True:
    user = {'id': get_username(user_input),
            'age': get_age(user_input),
            'state': get_state(user_input) or 'TX'}

    session.execute(prepared, [json.dumps(user)])

Type Interpretation

When Cassandra types have a sensible native JSON equivalent, such as ints, floats, booleans, and lists, those native types are accepted. For Cassandra types that don’t have a clear JSON equivalent, such as UUIDs, a string representation matching the normal CQL literal format should be used.

For example, in CQL you can represent a UUID with a literal like this:

INSERT INTO uuid_map (id, theuuid) VALUES (10, 994FF312-111E-11E5-9FDE-E0B9A54A6D93);

When using INSERT JSON, you should use a string with the same format to represent the UUID:

INSERT INTO uuid_map JSON '{"id": 10, "theuuid": "994FF312-111E-11E5-9FDE-E0B9A54A6D93"}';

Lists, sets, and tuples can all be represented by JSON lists:

CREATE TABLE example (
    id int PRIMARY KEY,
    tupleval tuple<int, text>,
    numbers set<int>,
    words list<text>

INSERT INTO example JSON '{"id": 0, "tupleval": [1, "abc"], "numbers": [1, 2, 3], "letters": ["a", "b", "c"]}';

User-defined types are represented by JSON maps:

CREATE TYPE address (number int, street text);

    id int PRIMARY KEY,
    street_address frozen<address>

INSERT INTO users JSON '{"id": 0, "street_address": {"number": 123, "street": "Main St."}}';

Please refer to the CQL documentation for full details on the accepted JSON formats for each Cassandra type.

Omitted Columns

Columns which are omitted from the JSON value map are treated as a null insert (which results in an existing value being deleted, if one is present).

Non-text Map Keys

The JSON specification does not allow for non-text map keys. However, Cassandra’s map type does support non-text keys. In order to support non-text keys, Cassandra will accept JSON-encoded string representations of any type as a map key [1].

For example, suppose we have a table like this:

CREATE TABLE comments (
    id int PRIMARY KEY,
    int_map map<int, text>

The map keys are ints, so we need to JSON encode them:

INSERT INTO comments JSON '{"id": 10, "int_map": {"1": "foo", "2": "bar"}}';

We do the same thing for more complex key types, such as set<text>:

    id int PRIMARY KEY,
    tags map<frozen<set<text>>, text>
INSERT INTO tags JSON '{"id": 10, "tags": {"[\"tag1\", \"tag2\"]": "details"}}';

Note that the map key is a JSON encoding of the list, not a normal CQL string literal, so double-quotes are used to surround the text items (and need to be escaped).

Case-sensitive Column Names

The INSERT JSON value map uses column names for the top-level keys. As with normal CQL, these column names are case-insensitive. So, for example, if you have a table like this:

    id text PRIMARY KEY,
    age int,
    state text

The following INSERT would work just fine:

INSERT INTO users JSON '{"ID": "user123", "Age": 42, "StAtE": "TX"}';

On the other hand, if your table is declared with case-sensitive column names, you will need to use slightly special column names in your JSON value map. Suppose our table is instead defined like this:

    id text PRIMARY KEY,
    "Age" int,
    "State" text

The "Age" and "Stage" columns are case-sensitive. In the JSON value map, you must match the capitalization and add an extra set of double-quotes to the column names:

INSERT INTO users JSON '{"id": "user123", "\"Age\"": 42, "\"State\"": "TX"}';


The SELECT statement has also be extended to support retrieval of rows in a JSON-encoded map format. The results for SELECT JSON will only include a single column named [json]. This column will contain the same JSON-encoded map representation of a row that is used for INSERT JSON. For example, if we have a table like the following:

    id text PRIMARY KEY,
    age int,
    state text

And we execute the following query:


The results will look like this in cqlsh:

{"id": "user123", "age": 42, "state": "TX"}

It’s also fine to use any normal selection clause. The map keys will match what the result column names would be for an equivalent non-JSON SELECT statement. For example:

SELECT JSON id, writetime(age), ttl(state) as ttl FROM users;

Will return:

{"id": "user123", "writetime(age)": 1434135381782986, "ttl": null}

The results of SELECT JSON are designed to be usable in an INSERT JSON statement without any modifications, so all of the same rules about non-text map keys and case-sensitive column names apply.

fromJson() and toJson()

INSERT JSON and SELECT JSON are designed to work with entire rows. When you only need to use JSON for a single column, the new toJson() and fromJson() functions can be used. These behave the same as INSERT JSON and SELECT JSON, but are limited to a single value or column.


The fromJson() function converts a single JSON-encoded string to a normal Cassandra value. For example, this can be used when performing an update:

UPDATE users SET age = fromJson('42') WHERE id = fromJson('"user123"');

The only place where fromJson() cannot be used is the selection clause of SELECT statements. (This is because Cassandra can’t know in advance what type the result will be.)


The toJson() function is the inverse of fromJson(). It can be used to convert any column to a JSON representation. For example:

SELECT id, toJson(tags) as tags FROM tags;

will return:

id | tags
10 | {"[\"tag1\", \"tag2\"]": "details"}

The toJson() function can only be used in the selection clause of SELECT statements.


Cassandra 2.2 makes it easier to work with JSON documents without sacrificing the benefits of schema enforcement. Try it out and let us know what you think!


[1]: For the sake of consistency, it will accept string representations of types anywhere, not just in map keys. However, for clarity and performance reasons I don’t suggest using this unless you need to.


  1. SRAVYA says:

    I want to know bout the Cassandra-XML support because i want to insert and retrieve data from cassandra using xml format

  2. Darwin Airola says:

    Is there any way to update an existing row with a JSON value?

    1. Tyler Hobbs Tyler Hobbs says:

      You would typically use the fromJson() function. For example: UPDATE mytable SET data = fromJson(?) WHERE id = ?

      If you’re overwriting the entire row, you can of course just use the normal INSERT JSON syntax. There’s also a Cassandra ticket to support “unset” values for columns that are omitted from INSERT JSON, which would make it easier to partially update a row in some cases.

  3. Marcel Villet says:

    When doing upserts from say a C# application, how does the overhead/performance of sending JSON compare to using bind variables against a prepared statement (assuming the JSON insert is also done using a prepared statement)?

    In other words:

    INSERT INTO mytable JSON {…}


    INSERT INTO mytable (col1, col2) VALUES (?, ?)

    1. Tyler Hobbs Tyler Hobbs says:

      The performance difference should be pretty minimal, but I encourage you to benchmark it for yourself if you’re looking to execute these at very high volumes.


Your email address will not be published. Required fields are marked *

Subscribe for newsletter:

© 2017 DataStax, All rights reserved. Tel. +1 (408) 933-3120 sales@datastax.com Offices

DataStax is a registered trademark of DataStax, Inc. and its subsidiaries in the United States and/or other countries.
Apache Cassandra, Apache, Tomcat, Lucene, Solr, Hadoop, Spark, TinkerPop, and Cassandra are trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries.