Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 156 lines (107 sloc) 6.071 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 use...
authored
9 https://github.com/pomack/thrift4go
f787ee0 @carloscm some initial ideas
authored
10
aa138a6 @carloscm update to Go 1
authored
11 Installing thrift4go under GOPATH in Go 1:
a6601cc @carloscm start Cursor interface
authored
12
aa138a6 @carloscm update to Go 1
authored
13 ```
14 1) cd lib/go/src
15 2) cp -R thrift $GOPATH/src
16 3) go install thrift
17 ```
8a65b1b @carloscm nicer readme
authored
18
39cfa7f @carloscm struct mapping cleanup
authored
19
8a65b1b @carloscm nicer readme
authored
20 # Installing
21
2a50747 @carloscm doc updates
authored
22 There is no need to generate a Cassandra Thrift biding, I am providing one with Gossie (and the whole point is not to have to use it!)
8a65b1b @carloscm nicer readme
authored
23
a6601cc @carloscm start Cursor interface
authored
24 For application usage copy the sources to your $GOPATH/src and issue a go install to build and copy the libraries:
aa138a6 @carloscm update to Go 1
authored
25
26 ```
27 1) cp -R src/* $GOPATH/src
28 2) go install cassandra gossie
29 ```
30
31 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
32
aa138a6 @carloscm update to Go 1
authored
33 ```
34 # locally install inside a pkg folder the depedencies, ie the cassandra bindings
35 GOPATH=$GOPATH:`pwd` go test -i gossie
36 # actually build and run the gossie tests
37 GOPATH=$GOPATH:`pwd` go test gossie
38 ```
8a65b1b @carloscm nicer readme
authored
39
40
41 # Running the tests
42
43 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.
44
39cfa7f @carloscm struct mapping cleanup
authored
45
2a50747 @carloscm doc updates
authored
46 # Quickstart
47
48 ### Connection pooling
49
50 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.
51
52 ```Go
e49f29d @carloscm fix readme
authored
53 pool := gossie.NewConnectionPool([]string{"localhost:9160"}, "Example", PoolOptions{Size: 50, Timeout: 3000})
2a50747 @carloscm doc updates
authored
54 ````
55
56 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.
57
58 ### Low level queries
59
8391fb7 @carloscm doc update
authored
60 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
61
62 ```Go
8391fb7 @carloscm doc update
authored
63 err = pool.Writer().Insert("MyColumnFamily", row).Run()
64 row, err = pool.Reader().Cf("MyColumnFamily").Get(id)
65 rows, err = pool.Reader().Cf("MyColumnFamily").Where([]byte("MyIndexedColumn"), EQ, []byte("hi!")).IndexedGet(&IndexedRange{Count: 1000})
2a50747 @carloscm doc updates
authored
66 ````
67
68 ### Type marshaling
69
70 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.
71
8391fb7 @carloscm doc update
authored
72 ### Struct mapping
2a50747 @carloscm doc updates
authored
73
8391fb7 @carloscm doc update
authored
74 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. NewSparse() returns a Mapping for the new CQL 3.0 pattern of composite "primary keys":
2a50747 @carloscm doc updates
authored
75
76 ```Go
77 /*
78 In CQL 3.0:
39cfa7f @carloscm struct mapping cleanup
authored
79 CREATE TABLE Timeline (
80 UserID varchar,
81 TweetID bigint,
82 Author varchar,
83 Body varchar,
84 PRIMARY KEY (UserID, TweetID)
2a50747 @carloscm doc updates
authored
85 );
86 */
87
88 // In Gossie:
8391fb7 @carloscm doc update
authored
89 type Tweet struct {
90 UserID string
a6601cc @carloscm start Cursor interface
authored
91 TweetID int64
2a50747 @carloscm doc updates
authored
92 Author string
93 Body string
94 }
95
8391fb7 @carloscm doc update
authored
96 mapping := gossie.NewSparse("Timeline", "UserID", "TweetID")
97 row, err = mapping.Map(&Tweet{"userid", 10000000000004, "Author Name", "Hey this thing rocks!"})
8ea771c @carloscm working Cursor Read/Write
authored
98 err = pool.Mutation().Insert("Timeline", row).Run()
2a50747 @carloscm doc updates
authored
99 ````
8a65b1b @carloscm nicer readme
authored
100
8391fb7 @carloscm doc update
authored
101 When calling Mapping.Map() you can tag your struct fiels with `name` and `type`. 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.
39cfa7f @carloscm struct mapping cleanup
authored
102
8391fb7 @carloscm doc update
authored
103 ### Query and Result interfaces (planned)
39cfa7f @carloscm struct mapping cleanup
authored
104
8391fb7 @carloscm doc update
authored
105 High level queries with transparent paging and buffering. This is still WIP, a possible example:
a6601cc @carloscm start Cursor interface
authored
106
107 ```Go
8391fb7 @carloscm doc update
authored
108 query := pool.Query(gossie.NewSparse("Timeline", "UserID", "TweetID"))
109
110 // a single tweet, since we pass the row key and all possible composite values
111 result, err := query.Get("username", 10000000000004)
112
113 // all tweets for a given user
114 result, err := query.Get("username")
8a65b1b @carloscm nicer readme
authored
115
8391fb7 @carloscm doc update
authored
116 // all tweets for a given user, starting at a certain TweetID
117 result, err := query.Where("TweetID", ">=", 10000000000004).Get("username")
118
119 // iterating over results
120 for var t Tweet; err := result.Next(&t); err != nil {
121 ...
122 }
123 ````
39cfa7f @carloscm struct mapping cleanup
authored
124
125 # Planned features
126
8391fb7 @carloscm doc update
authored
127 - Query: range reads for composites with buffering and paging
128 - Query: secondary index read with buffering and paging
129 - Query: multiget reads with buffering and paging
130 - A higher level abstraction for writes (Batch interface)
39cfa7f @carloscm struct mapping cleanup
authored
131 - High level mapping for Go slices
132 - High level mapping for Go maps
6d6d7b4 @carloscm nicer readme
authored
133
134
135 # License
136
137 Copyright (C) 2012 by Carlos Carrasco
138
139 Permission is hereby granted, free of charge, to any person obtaining a copy
140 of this software and associated documentation files (the "Software"), to deal
141 in the Software without restriction, including without limitation the rights
142 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
143 copies of the Software, and to permit persons to whom the Software is
144 furnished to do so, subject to the following conditions:
145
146 The above copyright notice and this permission notice shall be included in
147 all copies or substantial portions of the Software.
148
149 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
150 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
151 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
152 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
153 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
154 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
155 THE SOFTWARE.
Something went wrong with that request. Please try again.