{"id":21658546,"url":"https://github.com/monzo/gocassa","last_synced_at":"2025-07-17T21:31:16.445Z","repository":{"id":28455012,"uuid":"31970594","full_name":"monzo/gocassa","owner":"monzo","description":"A high level Cassandra library in Go, on top of gocql","archived":false,"fork":true,"pushed_at":"2024-03-05T09:32:42.000Z","size":734,"stargazers_count":39,"open_issues_count":5,"forks_count":13,"subscribers_count":39,"default_branch":"master","last_synced_at":"2024-08-14T10:29:21.738Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"gocassa/gocassa","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monzo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-10T17:11:36.000Z","updated_at":"2024-08-04T14:24:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"e836ab89-0d65-4bcc-9520-afaf2b1f6d09","html_url":"https://github.com/monzo/gocassa","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monzo%2Fgocassa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monzo%2Fgocassa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monzo%2Fgocassa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monzo%2Fgocassa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monzo","download_url":"https://codeload.github.com/monzo/gocassa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226304782,"owners_count":17603680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-25T09:29:26.932Z","updated_at":"2024-11-25T09:29:38.929Z","avatar_url":"https://github.com/monzo.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"gocassa\n=======\n\n[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg \"GoDoc\")](http://godoc.org/github.com/monzo/gocassa)\n[![Build Status](https://img.shields.io/travis/monzo/gocassa/master.svg \"Build Status\")](https://travis-ci.org/monzo/gocassa)\n\nGocassa is a high-level library on top of [gocql](https://github.com/gocql/gocql).\n\nCurrent version: v2.0.2\n\nCompared to gocql it provides query building, adds data binding, and provides easy-to-use \"recipe\" tables for common query use-cases. Unlike [cqlc](https://github.com/relops/cqlc), it does not use code generation.\n\nFor docs, see: [https://godoc.org/github.com/monzo/gocassa](https://godoc.org/github.com/monzo/gocassa)\n\n## Usage\n\nBelow 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.\n\n```go\npackage main\n\nimport(\n    \"fmt\"\n    \"time\"\n\n    \"github.com/monzo/gocassa\"\n)\n\ntype Sale struct {\n    Id          string\n    CustomerId  string\n    SellerId    string\n    Price       int\n    Created     time.Time\n}\n\nfunc main() {\n    keySpace, err := gocassa.ConnectToKeySpace(\"test\", []string{\"127.0.0.1\"}, \"\", \"\")\n    if err != nil {\n        panic(err)\n    }\n    salesTable := keySpace.Table(\"sale\", \u0026Sale{}, gocassa.Keys{\n        PartitionKeys: []string{\"Id\"},\n    })\n\n    err = salesTable.Set(Sale{\n        Id: \"sale-1\",\n        CustomerId: \"customer-1\",\n        SellerId: \"seller-1\",\n        Price: 42,\n        Created: time.Now(),\n    }).Run()\n    if err != nil {\n        panic(err)\n    }\n\n    result := Sale{}\n    if err := salesTable.Where(gocassa.Eq(\"Id\", \"sale-1\")).ReadOne(\u0026result).Run(); err != nil {\n        panic(err)\n    }\n    fmt.Println(result)\n}\n```\n\n[link to this example](https://github.com/monzo/gocassa/blob/master/examples/table1/table1.go)\n\nYou 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.\n\n```go\nerr := salesTable.List(\"seller-1\", nil, 0, \u0026results).WithOptions(gocassa.Options{\n    ClusteringOrder: []ClusteringOrderColumn{\n        {DESC, \"Name\"},\n    },\n    Limit: 100,\n}).Run()\n```\n\n### Running the tests\n\nAs a prerequisite for the tests, you need to have cassandra running locally. To\ndownload and install open-source Cassandra, see [Apache\nCassandra](https://cassandra.apache.org/) documentation. On a macOS, you simply\ninstall using `brew install cassandra`.\n\nThen you can run all the unit tests with the following command-\n```go\ngo test ./...\n```\n\n### Table Types\n\nGocassa provides multiple table types with their own unique interfaces:\n- a raw CQL table called simply `Table` - this lets you do pretty much any query imaginable\n- 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\n\n#### Table\n\n```go\n    salesTable := keySpace.Table(\"sale\", \u0026Sale{}, gocassa.Keys{\n        PartitionKeys: []string{\"Id\"},\n    })\n    result := Sale{}\n    err := salesTable.Where(gocassa.Eq(\"Id\", \"sale-1\")).ReadOne(\u0026result).Run()\n```\n[link to this example](https://github.com/hailocab/gocassa/blob/master/examples/table1/table1.go)\n\n#### MapTable\n\n`MapTable` provides only very simple [CRUD](http://en.wikipedia.org/wiki/Create,_read,_update_and_delete) functionality:\n\n```go\n    // …\n    salesTable := keySpace.MapTable(\"sale\", \"Id\", \u0026Sale{})\n    result := Sale{}\n    salesTable.Read(\"sale-1\", \u0026result).Run()\n}\n```\n[link to this example](https://github.com/monzo/gocassa/blob/master/examples/map_table1/map_table1.go)\n\nRead, Set, Update, and Delete all happen by \"Id\".\n\n#### MultimapTable\n\n`MultimapTable` can list rows filtered by equality of a single field (eg. list sales based on their `sellerId`):\n\n```go\n    salesTable := keySpace.MultimapTable(\"sale\", \"SellerId\", \"Id\", \u0026Sale{})\n    // …\n    results := []Sale{}\n    err := salesTable.List(\"seller-1\", nil, 0, \u0026results).Run()\n```\n[link to this example](https://github.com/monzo/gocassa/blob/master/examples/multimap_table1/multimap_table1.go)\n\nFor examples on how to do pagination or Update with this table, refer to the example (linked under code snippet).\n\n#### TimeSeriesTable\n\n`TimeSeriesTable` provides an interface to list rows within a time interval:\n\n```go\n    salesTable := keySpace.TimeSeriesTable(\"sale\", \"Created\", \"Id\", \u0026Sale{}, 24 * time.Hour)\n    //...\n    results := []Sale{}\n    err := salesTable.List(yesterdayTime, todayTime, \u0026results).Run()\n```\n\n#### MultiTimeSeriesTable\n\n`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:\n\n```go\n    salesTable := keySpace.MultiTimeSeriesTable(\"sale\", \"SellerId\", \"Created\", \"Id\", \u0026Sale{}, 24 * time.Hour)\n    //...\n    results := []Sale{}\n    err := salesTable.List(\"seller-1\", yesterdayTime, todayTime, \u0026results).Run()\n```\n\n#### MultiMapMultiKeyTable\n\n`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):\n\n```go\n    salePartitionKeys := []string{\"City\"}\n    saleClusteringKeys := []string{\"SellerId\",\"Id\"}\n    salesTable := keySpace.MultimapMultiKeyTable(\"sale\", salePartitionKeys, saleClusteringKeys, Sale{})\n    // …\n    result := Sale{}\n    saleFieldCity = salePartitionKeys[0]\n    saleFieldSellerId = saleClusteringKeys[0]\n    saleFieldSaleId = saleClusteringKeys[1]\n\n    field := make(map[string]interface{})\n    id := make(map[string]interface{})\n\n\n    field[saleFieldCity] = \"London\"\n    id[saleFieldSellerId] = \"141-dasf1-124\"\n    id[saleFieldSaleId] = \"512hha232\"\n\n    err := salesTable.Read(field, id , \u0026result).Run()\n```\n\n## Encoding/Decoding data structures\n\nWhen setting `structs` in gocassa the library first converts your value to a map. Each exported field is added to the map unless\n\n- the field's tag is \"-\", or\n- the field is empty and its tag specifies the \"omitempty\" option\n\nEach 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:\n\n```go\n// Field is ignored by this package.\nField int `cql:\"-\"`\n// Field appears as key \"myName\".\nField int `cql:\"myName\"`\n// Field appears as key \"myName\" and\n// the field is omitted from the object if its value is empty,\n// as defined above.\nField int `cql:\"myName,omitempty\"`\n// Field appears as key \"Field\" (the default), but\n// the field is skipped if empty.\n// Note the leading comma.\nField int `cql:\",omitempty\"`\n// All fields in the EmbeddedType are squashed into the parent type.\nEmbeddedType `cql:\",squash\"`\n```\n\nWhen 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).\n\n## Troubleshooting\n\n### Too long table names\n\nIn case you get the following error:\n\n```\nColumn family names shouldn't be more than 48 characters long (got \"somelongishtablename_multitimeseries_start_id_24h0m0s\")\n```\n\nYou can use the TableName options to override the default internal ones:\n\n```go\ntbl = tbl.WithOptions(Options{TableName: \"somelongishtablename_mts_start_id_24h0m0s\"})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonzo%2Fgocassa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonzo%2Fgocassa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonzo%2Fgocassa/lists"}