gocassa

package module
v0.0.0-...-b8b5728 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 9, 2015 License: MIT Imports: 11 Imported by: 0

README

gocassa

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

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

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), which aims to help the user by having a simplified interface tailored to a given common query use case
Table
package main

import(
    "fmt"
    "time"
    
    "github.com/hailocab/gocassa"
)

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

func main() {
    keySpace, err := gocassa.ConnectToKeySpace("test", []string{"127.0.0.1"}, "", "")
    if err != nil {
        panic(err)
    }
    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(),
    }).Run()
    if err != nil {
        panic(err)
    }

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

link to this example

MapTable

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

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

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

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

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{})
    //...
    results := []Sale{}
    err := salesTable.List("seller-1", yesterdayTime, todayTime, &results).Run()

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Connection

type Connection interface {
	CreateKeySpace(name string) error
	DropKeySpace(name string) error
	KeySpace(name string) KeySpace
}

Connection exists because one can not connect to a keyspace if it does not exist, thus having a Create on KeySpace is not possible. Use ConnectToKeySpace to acquire an instance of KeySpace without getting a Connection.

func Connect

func Connect(nodeIps []string, username, password string) (Connection, error)

Connect to a cluster.

func NewConnection

func NewConnection(q QueryExecutor) Connection

NewConnection creates a Connection with a custom query executor. This is mostly useful for testing/mocking purposes. Use `Connect` if you just want to talk to Cassandra.

type Filter

type Filter interface {
	// Selection modifiers
	Query() Query
	// Updates does a partial update. Use this if you don't want to overwrite your whole row, but you want to modify fields atomically.
	Update(m map[string]interface{}) Op // Probably this is danger zone (can't be implemented efficiently) on a selectuinb with more than 1 document
	// UpdateWithOptions is the same as Update but with extra options.
	UpdateWithOptions(m map[string]interface{}, opts Options) Op
	// Delete all rows matching the filter.
	Delete() Op
}

Filter is a subset of a Table, filtered by Relations. You can do writes or reads on a filter.

type KeySpace

type KeySpace interface {
	MapTable(tableName, id string, row interface{}) MapTable
	MultimapTable(tableName, fieldToIndexBy, uniqueKey string, row interface{}) MultimapTable
	TimeSeriesTable(tableName, timeField, uniqueKey string, bucketSize time.Duration, row interface{}) TimeSeriesTable
	MultiTimeSeriesTable(tableName, fieldToIndexByField, timeField, uniqueKey string, bucketSize time.Duration, row interface{}) MultiTimeSeriesTable
	Table(tableName string, row interface{}, keys Keys) Table
	// DebugMode enables/disables debug mode depending on the value of the input boolean.
	// When DebugMode is enabled, all built CQL statements are printe to stdout.
	DebugMode(bool)
}

KeySpace is used to obtain tables from.

func ConnectToKeySpace

func ConnectToKeySpace(keySpace string, nodeIps []string, username, password string) (KeySpace, error)

Connect to a certain keyspace directly. Same as using Connect().KeySpace(keySpaceName)

type Keys

type Keys struct {
	PartitionKeys     []string
	ClusteringColumns []string
}

Keys is used with the raw CQL Table type. It is implicit when using recipe tables.

type MapTable

type MapTable interface {
	SetWithOptions(v interface{}, opts Options) Op
	Set(v interface{}) Op
	UpdateWithOptions(id interface{}, m map[string]interface{}, opts Options) Op
	Update(id interface{}, m map[string]interface{}) Op
	Delete(id interface{}) Op
	Read(id, pointer interface{}) Op
	MultiRead(ids []interface{}, pointerToASlice interface{}) Op
	TableChanger
}

MapTable gives you basic CRUD functionality. If you need fancier ways to query your data set have a look at the other tables.

type MultiTimeSeriesTable

type MultiTimeSeriesTable interface {
	// timeField and idField must be present
	SetWithOptions(v interface{}, opts Options) Op
	Set(v interface{}) Op
	UpdateWithOptions(v interface{}, timeStamp time.Time, id interface{}, m map[string]interface{}, opts Options) Op
	Update(v interface{}, timeStamp time.Time, id interface{}, m map[string]interface{}) Op
	Delete(v interface{}, timeStamp time.Time, id interface{}) Op
	Read(v interface{}, timeStamp time.Time, id, pointer interface{}) Op
	List(v interface{}, start, end time.Time, pointerToASlice interface{}) Op
	TableChanger
}

MultiTimeSeriesTable is a cross between TimeSeries and Multimap tables.

type MultimapTable

type MultimapTable interface {
	SetWithOptions(v interface{}, opts Options) Op
	Set(v interface{}) Op
	UpdateWithOptions(v, id interface{}, m map[string]interface{}, opts Options) Op
	Update(v, id interface{}, m map[string]interface{}) Op
	Delete(v, id interface{}) Op
	DeleteAll(v interface{}) Op
	List(v, startId interface{}, limit int, pointerToASlice interface{}) Op
	Read(v, id, pointer interface{}) Op
	MultiRead(v interface{}, ids []interface{}, pointerToASlice interface{}) Op
	TableChanger
}

MultimapTable lets you list rows based on a field equality, eg. 'list all sales where seller id = v'.

type Op

type Op interface {
	// Run the operation.
	Run() error
	// You do not need this in 95% of the use cases, use Run!
	// Using atmoic batched writes (logged batches in Cassandra terminolohu) comes at a high performance cost!
	RunAtomically() error
	// Add an other Op to this one.
	Add(...Op) Op
}

Op is returned by both read and write methods, you have to run them explicitly to take effect. It represents one or more operations.

type Options

type Options struct {
	// TTL specifies a duration over which data is valid. It will be truncated to second precision upon statement
	// execution.
	TTL time.Duration
}

Options allows specification of (optional, hah) query parameters.

type Query

type Query interface {
	// Read the results. Make sure you pass in a pointer to a slice.
	Read(pointerToASlice interface{}) Op
	// Read one result. Make sure you pass in a pointer.
	ReadOne(pointer interface{}) Op
	// Limit the number of rows to be returned.
	Limit(int) Query
}

Query is a subset of a Table intended to be read

type QueryExecutor

type QueryExecutor interface {
	// Query executes a query and returns the results
	Query(stmt string, params ...interface{}) ([]map[string]interface{}, error)
	// Execute executes a DML query
	Execute(stmt string, params ...interface{}) error
	// ExecuteAtomically executs multiple DML queries with a logged batch
	ExecuteAtomically(stmt []string, params [][]interface{}) error
}

QueryExecutor actually executes the queries - this is mostly useful for testing/mocking purposes, ignore this otherwise. This library is using github.com/gocql/gocql as the query executor by default.

type Relation

type Relation struct {
	// contains filtered or unexported fields
}

func Eq

func Eq(key string, term interface{}) Relation

func GT

func GT(key string, term interface{}) Relation

func GTE

func GTE(key string, term interface{}) Relation

func In

func In(key string, terms ...interface{}) Relation

func LT

func LT(key string, term interface{}) Relation

func LTE

func LTE(key string, term interface{}) Relation

type RowNotFoundError

type RowNotFoundError struct {
	// contains filtered or unexported fields
}

RowNotFoundError is returned by Reads if the Row is not found.

func (RowNotFoundError) Error

func (r RowNotFoundError) Error() string

type Table

type Table interface {
	// Set Inserts, or Replaces your row with the supplied struct. Be aware that what is not in your struct
	// will be deleted. To only overwrite some of the fields, use Query.Update.
	Set(v interface{}) Op
	// SetWithOptions is the same as set, but with Options, like TTL, see the Options type for details
	SetWithOptions(v interface{}, opts Options) Op
	// Where accepts a bunch of realtions and returns a filter. See the documentation for Relation and Filter to understand what that means.
	Where(relations ...Relation) Filter // Because we provide selections
	// Name returns the underlying table name, as stored in C*
	Name() string
	TableChanger
}

Table is the only non-recipe table, it is the "raw CQL table", it lets you do pretty much whatever you want with the downside that you have to know what you are doing - eg. you have to know what queries can you make on a certain partition key - clustering column combination.

type TableChanger

type TableChanger interface {
	// Create creates the table in the keySpace, but only if it does not exist already.
	// If the table already exists, it returns an error.
	Create() error
	// CreateStatement returns you the CQL query which can be used to create the tably manually in cqlsh
	CreateStatement() (string, error)
	// Recreate drops the table if exists and creates it again.
	// This is useful for test purposes only.
	Recreate() error
}

Danger zone! Do not use this interface unless you really know what you are doing

type TimeSeriesTable

type TimeSeriesTable interface {
	// timeField and idField must be present
	SetWithOptions(v interface{}, opts Options) Op
	Set(v interface{}) Op
	UpdateWithOptions(timeStamp time.Time, id interface{}, m map[string]interface{}, opts Options) Op
	Update(timeStamp time.Time, id interface{}, m map[string]interface{}) Op
	Delete(timeStamp time.Time, id interface{}) Op
	Read(timeStamp time.Time, id, pointer interface{}) Op
	List(start, end time.Time, pointerToASlice interface{}) Op
	TableChanger
}

TimeSeriesTable lets you list rows which have a field value between two date ranges.

Directories

Path Synopsis
This package generates all kind of CQL statements
This package generates all kind of CQL statements
This package provides some punk-rock reflection which is not in the stdlib.
This package provides some punk-rock reflection which is not in the stdlib.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL