A high level Cassandra library in Go, on top of gocql
Clone or download
Pull request Compare This branch is 5 commits behind gocassa:master.
John Worrell and dancannon Fix broken mock (gocassa#149)
* Add broken test - demonstrates Delete(...) on mock is broken

* and now fix it by fixing the mock
Latest commit d3c840d May 4, 2016
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Improved the struct reflection code (based on encoding/json) Oct 16, 2015
.travis.yml REmove sleep in test Nov 25, 2015
CHANGELOG.md Fix tests Apr 27, 2016
README.md Correct version Apr 27, 2016
compare.go Fix missing package Oct 27, 2015
connection.go Add a way to close a connection Feb 24, 2016
errors.go Better error messages Apr 10, 2015
filter.go Refactor Op to be more of a "real" interface (remove type assertions) Aug 12, 2015
flextimeseries_table_test.go Correct version Apr 27, 2016
generate.go Implemented ORDER BY and tidied up documentation, fixes gocassa#137 Dec 22, 2015
interfaces.go Merge pull request gocassa#143 from hectorj/connection_closing Apr 27, 2016
keyspace.go Correct version Apr 27, 2016
map_table.go Remove last gettable reference Oct 22, 2015
map_table_test.go fix vet, and test errors Mar 10, 2015
mock.go Fix broken mock (gocassa#149) May 4, 2016
mock_test.go Fix broken mock (gocassa#149) May 4, 2016
modifiers.go Table and statement level options Mar 30, 2015
multimap_table.go Remove the GetTable method Oct 22, 2015
multiop.go Support logged batches Aug 25, 2015
multitimeseries_table.go Correct version Apr 27, 2016
multitimeseries_table_test.go Added checks on table names in case changes change them Apr 26, 2016
op.go Correct version Apr 27, 2016
op_test.go Add documentation and tests Oct 27, 2015
options.go Implemented ORDER BY and tidied up documentation, fixes gocassa#137 Dec 22, 2015
query_test.go Fixed order by tests Dec 22, 2015
relation.go Fix missing package Oct 27, 2015
table.go Fixed bug caused by type-sensitive keys Nov 27, 2015
table_test.go Fix tests Apr 27, 2016
timeseries_table.go Remove the GetTable method Oct 22, 2015



GoDoc Build Status

Gocassa is a high-level library on top of gocql.

Current version: v1.3.0

Compared to gocql it provides query building, adds data binding, and provides easy-to-use "recipe" tables for common query use-cases. Unlike cqlc, it does not use code generation.

For docs, see: https://godoc.org/github.com/hailocab/gocassa


Below is a basic example showing how to connect to a Cassandra cluster and setup a simple table. For more advanced examples see the "Table Types" section below.

package main


type Sale struct {
    Id          string
    CustomerId  string
    SellerId    string
    Price       int
    Created     time.Time

func main() {
    keySpace, err := gocassa.ConnectToKeySpace("test", []string{""}, "", "")
    if err != nil {
    salesTable := keySpace.Table("sale", &Sale{}, gocassa.Keys{
        PartitionKeys: []string{"Id"},

    err = salesTable.Set(Sale{
        Id: "sale-1",
        CustomerId: "customer-1",
        SellerId: "seller-1",
        Price: 42,
        Created: time.Now(),
    if err != nil {

    result := Sale{}
    if err := salesTable.Where(gocassa.Eq("Id", "sale-1")).ReadOne(&result).Run(); err != nil {

You can pass additional options to a gocassa Op to further configure your queries, for example the following query orders the results by the field "Name" in descending order and limits the results to a total of 100.

err := salesTable.List("seller-1", nil, 0, &results).WithOptions(gocassa.Options{
    ClusteringOrder: []ClusteringOrderColumn{
        {DESC, "Name"},
    Limit: 100,

Table Types

Gocassa provides multiple table types with their own unique interfaces:

  • a raw CQL table called simply Table - this lets you do pretty much any query imaginable
  • and a number of single purpose 'recipe' tables (Map, Multimap, TimeSeries, MultiTimeSeries, MultiMapMultiKey), which aims to help the user by having a simplified interface tailored to a given common query use case


    salesTable := keySpace.Table("sale", &Sale{}, gocassa.Keys{
        PartitionKeys: []string{"Id"},
    result := Sale{}
    err := salesTable.Where(gocassa.Eq("Id", "sale-1")).ReadOne(&result).Run()

link to this example


MapTable provides only very simple CRUD functionality:

    salesTable := keySpace.MapTable("sale", "Id", &Sale{})
    result := Sale{}
    salesTable.Read("sale-1", &result).Run()

link to this example

Read, Set, Update, and Delete all happen by "Id".


MultimapTable can list rows filtered by equality of a single field (eg. list sales based on their sellerId):

    salesTable := keySpace.MultimapTable("sale", "SellerId", "Id", &Sale{})
    results := []Sale{}
    err := salesTable.List("seller-1", nil, 0, &results).Run()

link to this example

For examples on how to do pagination or Update with this table, refer to the example (linked under code snippet).


TimeSeriesTable provides an interface to list rows within a time interval:

    salesTable := keySpace.TimeSeriesTable("sale", "Created", "Id", &Sale{}, 24 * time.Hour)
    results := []Sale{}
    err := salesTable.List(yesterdayTime, todayTime, &results).Run()


MultiTimeSeriesTable is like a cross between MultimapTable and TimeSeriesTable. It can list rows within a time interval, and filtered by equality of a single field. The following lists sales in a time interval, by a certain seller:

    salesTable := keySpace.MultiTimeSeriesTable("sale", "SellerId", "Created", "Id", &Sale{}, 24 * time.Hour)
    results := []Sale{}
    err := salesTable.List("seller-1", yesterdayTime, todayTime, &results).Run()


MultiMapMultiKeyTable can perform CRUD operations on rows filtered by equality of multiple fields (eg. read a sale based on their city , sellerId and Id of the sale):

    salePartitionKeys := []Sale{"City"}
    saleClusteringKeys := []Sale{"SellerId","Id"}
    salesTable := keySpace.MultimapMultiKeyTable("sale", salePartitionKeys, saleClusteringKeys, Sale{})
    result := Sale{}
    saleFieldCity = salePartitionKeys[0]
    saleFieldSellerId = saleClusteringKeys[0]
    saleFieldSaleId = saleClusteringKeys[1]

    field := make(map[string]interface{})
    id := make(map[string]interface{})

    field[saleFieldCity] = "London"
    id[saleFieldSellerId] = "141-dasf1-124"
    id[saleFieldSaleId] = "512hha232"

    err := salesTable.Read(field, id , &result).Run()

Encoding/Decoding data structures

When setting structs in gocassa the library first converts your value to a map. Each exported field is added to the map unless

  • the field's tag is "-", or
  • the field is empty and its tag specifies the "omitempty" option

Each fields default name in the map is the field name but can be specified in the struct field's tag value. The "cql" key in the struct field's tag value is the key name, followed by an optional comma and options. Examples:

// Field is ignored by this package.
Field int `cql:"-"`
// Field appears as key "myName".
Field int `cql:"myName"`
// Field appears as key "myName" and
// the field is omitted from the object if its value is empty,
// as defined above.
Field int `cql:"myName,omitempty"`
// Field appears as key "Field" (the default), but
// the field is skipped if empty.
// Note the leading comma.
Field int `cql:",omitempty"`
// All fields in the EmbeddedType are squashed into the parent type.
EmbeddedType `cql:",squash"`

When encoding maps with non-string keys the key values are automatically converted to strings where possible, however it is recommended that you use strings where possible (for example map[string]T).


Too long table names

In case you get the following error:

Column family names shouldn't be more than 48 characters long (got "somelongishtablename_multitimeseries_start_id_24h0m0s")

You can use the TableName options to override the default internal ones:

tbl = tbl.WithOptions(Options{TableName: "somelongishtablename_mts_start_id_24h0m0s"})