Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 172 lines (116 sloc) 7.015 kb
8a65b1b @carloscm nicer readme
authored
1 # About
f787ee0 @carloscm some initial ideas
authored
2
39cfa7f @carloscm struct mapping cleanup
authored
3 Gossie is a Go library for Apache Cassandra. It includes a wrapper for the Cassandra 1.0 Thrift bindings with utilities for connection pooling, primitive type marshaling and easy query building. It also includes a higher level layer that allows mapping structs to Cassandra column famlilies, with support for advanced features like composite column names.
4
8a65b1b @carloscm nicer readme
authored
5
6 # Requeriments
7
8 The official Apache Thrift libraries for Go are outdated and buggy. For now the active development happens in thrift4go:
84fa211 @carloscm the official thrift4go is now ready, remove the local copy and point …
authored
9 https://github.com/pomack/thrift4go
f787ee0 @carloscm some initial ideas
authored
10
feca03d @carloscm simplify installation, update docs
authored
11 Install thrift4go:
a6601cc @carloscm start Cursor interface
authored
12
aa138a6 @carloscm update to Go 1
authored
13 ```
feca03d @carloscm simplify installation, update docs
authored
14 go get "github.com/pomack/thrift4go/lib/go/src/thrift"
aa138a6 @carloscm update to Go 1
authored
15 ```
8a65b1b @carloscm nicer readme
authored
16
39cfa7f @carloscm struct mapping cleanup
authored
17
8a65b1b @carloscm nicer readme
authored
18 # Installing
19
f63f556 @carloscm doc updates
authored
20 There is no need to generate a Cassandra Thrift binding, I am providing one with Gossie (and the whole point is not to have to use it!).
8a65b1b @carloscm nicer readme
authored
21
feca03d @carloscm simplify installation, update docs
authored
22 For application usage issue two `go get` commands, one for the bindings and another for Gossie
aa138a6 @carloscm update to Go 1
authored
23
24 ```
feca03d @carloscm simplify installation, update docs
authored
25 go get "github.com/carloscm/gossie/src/cassandra"
26 go get "github.com/carloscm/gossie/src/gossie"
aa138a6 @carloscm update to Go 1
authored
27 ```
28
29 If you want to fork and do development on Gossie itself the main command you need to run is something like (from the root of the Gossie folder):
8a65b1b @carloscm nicer readme
authored
30
aa138a6 @carloscm update to Go 1
authored
31 ```
32 GOPATH=$GOPATH:`pwd` go test gossie
33 ```
8a65b1b @carloscm nicer readme
authored
34
35
36 # Running the tests
37
38 Launch a Cassandra instance in localhost:9160, create a keyspace named TestGossie, and execute the provided schema-test.txt to create the test column families. Now you can run the Gossie tests.
39
39cfa7f @carloscm struct mapping cleanup
authored
40
2a50747 @carloscm doc updates
authored
41 # Quickstart
42
f63f556 @carloscm doc updates
authored
43 ### Import
44
e452bb2 @carloscm fix query composite builder, add GetBetween, more query tests
authored
45 Gossie follows the Go 1.0 packaging conventions. Import Gossie into your code like this:
f63f556 @carloscm doc updates
authored
46
47 ```Go
48 import (
49 "github.com/carloscm/gossie/src/gossie"
50 )
51 ````
52
2a50747 @carloscm doc updates
authored
53 ### Connection pooling
54
55 To create a connection use the method NewConnectionPool, passing a list of nodes, the desired keyspace, and a PoolOptions with the various connection options you can tune.
56
57 ```Go
e49f29d @carloscm fix readme
authored
58 pool := gossie.NewConnectionPool([]string{"localhost:9160"}, "Example", PoolOptions{Size: 50, Timeout: 3000})
2a50747 @carloscm doc updates
authored
59 ````
60
61 The pool uses a simple randomized rule for connecting to the passed nodes, always keeping the total number of connections under PoolOptions.Size but without any guarantees on the number of connections per host. It has automatic failover and retry of operations.
62
63 ### Low level queries
64
8391fb7 @carloscm doc update
authored
65 The Reader and Writer interfaces allow for low level queries to Cassandra and they follow the semantics of the native Thrift operations, but wrapped with much easier to use functions based on method chaining.
2a50747 @carloscm doc updates
authored
66
67 ```Go
8391fb7 @carloscm doc update
authored
68 err = pool.Writer().Insert("MyColumnFamily", row).Run()
69 row, err = pool.Reader().Cf("MyColumnFamily").Get(id)
70 rows, err = pool.Reader().Cf("MyColumnFamily").Where([]byte("MyIndexedColumn"), EQ, []byte("hi!")).IndexedGet(&IndexedRange{Count: 1000})
2a50747 @carloscm doc updates
authored
71 ````
72
73 ### Type marshaling
74
75 The low level interface is based on passing []byte values for everything, mirroring the Thrift API. For this reason the functions Marshal and Unmarshal provide for type conversion between native Go types and native Cassandra types.
76
8391fb7 @carloscm doc update
authored
77 ### Struct mapping
2a50747 @carloscm doc updates
authored
78
6e03459 @carloscm add some public marshalling to mappings, built-in mappings again requ…
authored
79 The Mapping interface and its implementations allow to convert Go structs into Rows, and they have support of advanced features like composites or overriding column names and types. Built-in NewMapping() returns a Mapping implementation that can map and unmap Go structs from Cassandra rows, serialized in classic key/value rows or in composited column names, with support for both sparse and compact storage. For example:
2a50747 @carloscm doc updates
authored
80
81 ```Go
82 /*
83 In CQL 3.0:
39cfa7f @carloscm struct mapping cleanup
authored
84 CREATE TABLE Timeline (
85 UserID varchar,
86 TweetID bigint,
87 Author varchar,
88 Body varchar,
89 PRIMARY KEY (UserID, TweetID)
2a50747 @carloscm doc updates
authored
90 );
91 */
92
93 // In Gossie:
8391fb7 @carloscm doc update
authored
94 type Tweet struct {
6e03459 @carloscm add some public marshalling to mappings, built-in mappings again requ…
authored
95 UserID string `cf:"Timeline" key:"UserID" cols:"TweetID"`
a6601cc @carloscm start Cursor interface
authored
96 TweetID int64
2a50747 @carloscm doc updates
authored
97 Author string
98 Body string
99 }
100
6e03459 @carloscm add some public marshalling to mappings, built-in mappings again requ…
authored
101 mapping := gossie.NewMapping(&Tweet{})
8391fb7 @carloscm doc update
authored
102 row, err = mapping.Map(&Tweet{"userid", 10000000000004, "Author Name", "Hey this thing rocks!"})
0631369 @carloscm doc update
authored
103 err = pool.Writer().Insert("Timeline", row).Run()
2a50747 @carloscm doc updates
authored
104 ````
8a65b1b @carloscm nicer readme
authored
105
6e03459 @carloscm add some public marshalling to mappings, built-in mappings again requ…
authored
106 When calling NewMapping() you can tag your struct fiels with `name`, `type` and `skip`. The `name` field tag will change the column name to its value when the field it appears on is (un)marhsaled to/from a Cassandra row column. The `type` field tag allows to override the default type Go<->Cassandra type mapping used by Gossie for the field it appears on. If `skip:"true"` is present the field will be ignored by Gossie.
4baea69 @carloscm mapping from tags, compact mappings
authored
107
e452bb2 @carloscm fix query composite builder, add GetBetween, more query tests
authored
108 The tags `mapping`, `cf`, `key`, `cols` and `value` can be used in any field in the struct to document a mapping. `mapping` is optional and can have a value of `sparse` (the default) or `compact`. See [CQL3.0](http://www.datastax.com/dev/blog/whats-new-in-cql-3-0) for more information. `cf` is the column family name. `key` is the field name in the struct that stores the Cassandra row key value. `cols` is optional and it is a list of struct fiels that build up the composite column name, if there is any. `value` is the field that stores the column value for compact storage rows, and it is ignored in sparse storage rows.
39cfa7f @carloscm struct mapping cleanup
authored
109
b23d895 @carloscm sane query and result interfaces
authored
110 ### Query and Result
39cfa7f @carloscm struct mapping cleanup
authored
111
b23d895 @carloscm sane query and result interfaces
authored
112 Query allows to look up mapped structs over Cassandra rows. Pass to `Query.Get` the row key, followed by zero or more composite keys, to get a Result. `Result.Next` reads a single struct from the Cassandra row, and returns `Done` when no more structs can be read.
a6601cc @carloscm start Cursor interface
authored
113
114 ```Go
4baea69 @carloscm mapping from tags, compact mappings
authored
115 query := pool.Query(TweetMapping)
8391fb7 @carloscm doc update
authored
116
117 // a single tweet, since we pass the row key and all possible composite values
118 result, err := query.Get("username", 10000000000004)
119
120 // all tweets for a given user
121 result, err := query.Get("username")
8a65b1b @carloscm nicer readme
authored
122
8391fb7 @carloscm doc update
authored
123 // iterating over results
98df0e9 @carloscm doc update
authored
124 for {
b23d895 @carloscm sane query and result interfaces
authored
125 t := &Tweet{}
126 err := result.Next(t)
98df0e9 @carloscm doc update
authored
127 if err != nil {
128 break
129 }
8391fb7 @carloscm doc update
authored
130 }
131 ````
39cfa7f @carloscm struct mapping cleanup
authored
132
feca03d @carloscm simplify installation, update docs
authored
133
39cfa7f @carloscm struct mapping cleanup
authored
134 # Planned features
135
b23d895 @carloscm sane query and result interfaces
authored
136 - Error passing overhaul, to be based on typing
137 - Query: secondary index read with buffering
138 - Query: multiget reads with buffering
8391fb7 @carloscm doc update
authored
139 - A higher level abstraction for writes (Batch interface)
39cfa7f @carloscm struct mapping cleanup
authored
140 - High level mapping for Go slices
141 - High level mapping for Go maps
feca03d @carloscm simplify installation, update docs
authored
142 - Add low level interface for CQL 3.0 with prepared statement support
143
144
145 # Not planned
146
147 - Supercolumns
148 - Dynamic composite comparator
6d6d7b4 @carloscm nicer readme
authored
149
150
151 # License
152
153 Copyright (C) 2012 by Carlos Carrasco
154
155 Permission is hereby granted, free of charge, to any person obtaining a copy
156 of this software and associated documentation files (the "Software"), to deal
157 in the Software without restriction, including without limitation the rights
158 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
159 copies of the Software, and to permit persons to whom the Software is
160 furnished to do so, subject to the following conditions:
161
162 The above copyright notice and this permission notice shall be included in
163 all copies or substantial portions of the Software.
164
165 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
166 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
167 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
168 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
169 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
170 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
171 THE SOFTWARE.
Something went wrong with that request. Please try again.