Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 161 lines (112 sloc) 6.086 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
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!"})
0631369 @carloscm doc update
authored
98 err = pool.Writer().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
98df0e9 @carloscm doc update
authored
120 for {
121 var t Tweet
122 err := result.Next(&t)
123 if err != nil {
124 break
125 }
8391fb7 @carloscm doc update
authored
126 ...
127 }
128 ````
39cfa7f @carloscm struct mapping cleanup
authored
129
130 # Planned features
131
8391fb7 @carloscm doc update
authored
132 - Query: range reads for composites with buffering and paging
133 - Query: secondary index read with buffering and paging
134 - Query: multiget reads with buffering and paging
135 - A higher level abstraction for writes (Batch interface)
39cfa7f @carloscm struct mapping cleanup
authored
136 - High level mapping for Go slices
137 - High level mapping for Go maps
6d6d7b4 @carloscm nicer readme
authored
138
139
140 # License
141
142 Copyright (C) 2012 by Carlos Carrasco
143
144 Permission is hereby granted, free of charge, to any person obtaining a copy
145 of this software and associated documentation files (the "Software"), to deal
146 in the Software without restriction, including without limitation the rights
147 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
148 copies of the Software, and to permit persons to whom the Software is
149 furnished to do so, subject to the following conditions:
150
151 The above copyright notice and this permission notice shall be included in
152 all copies or substantial portions of the Software.
153
154 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
155 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
156 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
157 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
158 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
159 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
160 THE SOFTWARE.
Something went wrong with that request. Please try again.