Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 254 lines (181 sloc) 7.626 kb
7bdd44c Russ Bradberry rename
devdazed authored
1 # Helenus
d9d37c6 Russ Bradberry initial commit
devdazed authored
2
58b320c Russ Bradberry Update Readme.md
devdazed authored
3
c85a6e8 Russ Bradberry Update Readme.md
devdazed authored
4 ### This driver uses the old Thrift protocol, if you are using Cassandra 1.2 or higher and you are using CQL, please consider using [node-cassandra-cql](https://github.com/jorgebay/node-cassandra-cql). While I will continue to fix bugs with this driver, feature development is frozen as many new features coming out will not be supported by Thrift.
5
58b320c Russ Bradberry Update Readme.md
devdazed authored
6
d9d37c6 Russ Bradberry initial commit
devdazed authored
7 NodeJS Bindings for Cassandra
c519047 Russ Bradberry add build status
devdazed authored
8
e400bfc Russ Bradberry update docs
devdazed authored
9 Currently the driver has full CQL support and a growing support for thrift (non-cql) commands.
10 If you would like to contribute, please contact Russ Bradberry <rbradberry@simplereach.com>
94cc7ce Eric Lubow Updated README
elubow authored
11
3bbfa6f Russ Bradberry updated readme
devdazed authored
12 If you have any questions regarding the driver, please visit our [google group](https://groups.google.com/forum/?fromgroups#!forum/helenus)
13
14
c519047 Russ Bradberry add build status
devdazed authored
15 ### Build Status
16
17 [![Build Status](https://secure.travis-ci.org/simplereach/helenus.png)](http://travis-ci.org/simplereach/helenus)
18
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
19 ## Installation
d9d37c6 Russ Bradberry initial commit
devdazed authored
20
94cc7ce Eric Lubow Updated README
elubow authored
21 npm install helenus
c519047 Russ Bradberry add build status
devdazed authored
22
e400bfc Russ Bradberry update docs
devdazed authored
23 ## Running Tests
24
25 Ensure cassandra is running on localhost:9160.
c519047 Russ Bradberry add build status
devdazed authored
26
e400bfc Russ Bradberry update docs
devdazed authored
27 make test
c519047 Russ Bradberry add build status
devdazed authored
28
e400bfc Russ Bradberry update docs
devdazed authored
29 For coverage
c519047 Russ Bradberry add build status
devdazed authored
30
e400bfc Russ Bradberry update docs
devdazed authored
31 make test-cov
94cc7ce Eric Lubow Updated README
elubow authored
32
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
33 ## Usage
34
e400bfc Russ Bradberry update docs
devdazed authored
35 ## CQL
36
805b4c1 Russ Bradberry docs
devdazed authored
37 ```javascript
7bdd44c Russ Bradberry rename
devdazed authored
38 var helenus = require('helenus'),
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
39 pool = new helenus.ConnectionPool({
40 hosts : ['localhost:9160'],
41 keyspace : 'helenus_test',
42 user : 'test',
43 password : 'test1233',
44 timeout : 3000
df0296b Christoph Tavan Account for CQL3 changes in Readme, see #42
ctavan authored
45 //cqlVersion : '3.0.0' // specify this if you're using Cassandra 1.1 and want to use CQL 3
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
46 });
805b4c1 Russ Bradberry docs
devdazed authored
47
ef951b2 Russ Bradberry update readme
devdazed authored
48 //optionally you can supply the 'getHost' parameter to the connection pool options which will
49 // allow you to override the default random host decision
50
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
51 //if you don't listen for error, it will bubble up to `process.uncaughtException`
3bbfa6f Russ Bradberry updated readme
devdazed authored
52 //pools act just like connection objects, so you don't have to worry about api
e400bfc Russ Bradberry update docs
devdazed authored
53 //differences when using either the pool or the connection
805b4c1 Russ Bradberry docs
devdazed authored
54 pool.on('error', function(err){
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
55 console.error(err.name, err.message);
805b4c1 Russ Bradberry docs
devdazed authored
56 });
57
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
58 //makes a connection to the pool, this will return once there is at least one
59 //valid connection, other connections may still be pending
60 pool.connect(function(err, keyspace){
805b4c1 Russ Bradberry docs
devdazed authored
61 if(err){
62 throw(err);
94cc7ce Eric Lubow Updated README
elubow authored
63 } else {
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
64 //to use cql, access the pool object once connected
65 //the first argument is the CQL string, the second is an `Array` of items
66 //to interpolate into the format string, the last is the callback
67 //for formatting specific see `http://nodejs.org/docs/latest/api/util.html#util.format`
68 //results is an array of row objects
e3031e1 Russ Bradberry update readme
devdazed authored
69
df0296b Christoph Tavan Account for CQL3 changes in Readme, see #42
ctavan authored
70 pool.cql("SELECT col FROM cf_one WHERE key = ?", ['key123'], function(err, results){
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
71 console.log(err, results);
c519047 Russ Bradberry add build status
devdazed authored
72 });
e3031e1 Russ Bradberry update readme
devdazed authored
73
74 //NOTE:
7adac77 Christoph Tavan Disallow usage of placeholders for ColumnFamily-names, closes #42
ctavan authored
75 //- You can always skip quotes around placeholders, they are added automatically.
df0296b Christoph Tavan Account for CQL3 changes in Readme, see #42
ctavan authored
76 //- In CQL 3 you cannot use placeholders for ColumnFamily names or Column names.
805b4c1 Russ Bradberry docs
devdazed authored
77 }
78 });
79 ```
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
80
e400bfc Russ Bradberry update docs
devdazed authored
81 ## Thrift
82
83 If you do not want to use CQL, you can make calls using the thrift driver
84
85 ```javascript
86 pool.connect(function(err, keyspace){
87 if(err){
88 throw(err);
c519047 Russ Bradberry add build status
devdazed authored
89 }
90
b0778a1 Russ Bradberry update docs
devdazed authored
91 //first retreive the column family from the server
92 //helenus will cache column families it has already seen
93 keyspace.get('my_cf', function(err, cf){
94 if(err){
95 throw(err);
96 }
c519047 Russ Bradberry add build status
devdazed authored
97
b0778a1 Russ Bradberry update docs
devdazed authored
98 //insert something into the column family
99 cf.insert('foo', {'bar':'baz'}, function(err){
e400bfc Russ Bradberry update docs
devdazed authored
100 if(err){
101 throw(err);
102 }
c519047 Russ Bradberry add build status
devdazed authored
103
b0778a1 Russ Bradberry update docs
devdazed authored
104 //get what we just put in
154790c Russ Bradberry Fixed invalid examples
devdazed authored
105 //the driver will return a helenus.Row object just like CQL
bfd9ab2 Sergii Rudenko Fix Thrift readme example
Rudeg authored
106 cf.get('foo', {consistency:helenus.ConsistencyLevel.ONE}, function(err, row){
e400bfc Russ Bradberry update docs
devdazed authored
107 if(err){
108 throw(err);
109 }
c519047 Russ Bradberry add build status
devdazed authored
110
111 row.get('bar').value // => baz
112 });
e400bfc Russ Bradberry update docs
devdazed authored
113 });
b0778a1 Russ Bradberry update docs
devdazed authored
114 });
115
e400bfc Russ Bradberry update docs
devdazed authored
116 });
117 ```
118
119 ### Thrift Support
120
121 Currently Helenus supports the following command for the thrift side of the driver:
122
123 * connection.createKeyspace
124 * connection.dropKeyspace
125 * keyspace.createColumnFamily
126 * keyspace.dropColumnFamily
127 * columnFamily.insert
128 * columnFamily.get
aaca844 Russ Bradberry added getIndexed to columnfamily
devdazed authored
129 * columnFamily.getIndexed
8d97e14 Russ Bradberry bump version
devdazed authored
130 * columnFamily.remove
dd23c1f Russ Bradberry - Bump to 0.5.0 \n - Updated coverage \n - Updated docs
devdazed authored
131 * columnFamily.truncate
c519047 Russ Bradberry add build status
devdazed authored
132
e400bfc Russ Bradberry update docs
devdazed authored
133 The following support is going to be added in later releases:
134
135 * columnFamily.rowCount
136 * columnFamily.columnCount
137 * columnfamily.increment
138 * SuperColumns
139 * CounterColumns
140 * Better composite support
141
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
142 ## Row
143
c519047 Russ Bradberry add build status
devdazed authored
144 The Helenus Row object acts like an array but contains some helper methods to
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
145 make your life a bit easier when dealing with dynamic columns in Cassandra
146
147 ### row.count
148
149 Returns the number of columns in the row
150
151 ### row[N]
152
153 This will return the column at index N
154
155 results.forEach(function(row){
156 //gets the 5th column of each row
157 console.log(row[5]);
158 });
c519047 Russ Bradberry add build status
devdazed authored
159
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
160 ### row.get(name)
161
162 This will return the column with a specific name
163
164 results.forEach(function(row){
165 //gets the column with the name 'foo' of each row
166 console.log(row.get('foo'));
167 });
168
2a10f94 Samal Gorai Updated readme to list row.forEach wrapper function
samal authored
169 ### row.forEach()
170
171 This is wrapper function of Array.forEach which return name,value,ts,ttl of column from row as callback params.
172
b37f775 Jean-Charles Nadé typo: foreach => forEach
jcnade authored
173 results.forEach(function(row){
2a10f94 Samal Gorai Updated readme to list row.forEach wrapper function
samal authored
174 //all row of result
93eadf6 Russ Bradberry fixed typo in readmin [ closes #58 ]
devdazed authored
175 row.forEach(function(name,value,ts,ttl){
2a10f94 Samal Gorai Updated readme to list row.forEach wrapper function
samal authored
176 //all column of row
177 console.log(name,value,ts,ttl);
178 });
93eadf6 Russ Bradberry fixed typo in readmin [ closes #58 ]
devdazed authored
179
2a10f94 Samal Gorai Updated readme to list row.forEach wrapper function
samal authored
180 });
93eadf6 Russ Bradberry fixed typo in readmin [ closes #58 ]
devdazed authored
181
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
182 ### row.slice(start, finish)
183
c519047 Russ Bradberry add build status
devdazed authored
184 Slices columns in the row based on their numeric index, this allows you to get
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
185 columns x through y, it returns a Helenus row object of columns that match the slice.
186
187 results.forEach(function(row){
188 //gets the first 5 columns of each row
189 console.log(row.slice(0,5));
190 });
191
192 ### row.nameSlice(start, finish)
193
154790c Russ Bradberry Fixed invalid examples
devdazed authored
194 Slices the columns based on part of their column name. returns a Helenus row of columns
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
195 that match the slice
196
197 results.forEach(function(row){
198 //gets all columns that start with a, b, c, or d
ca11b76 Russ Bradberry update docs
devdazed authored
199 console.log(row.nameSlice('a','e'));
deda649 Russ Bradberry Full CQL Support, Proper Serialization/Deserialization of Types, bump to...
devdazed authored
200 });
201
e400bfc Russ Bradberry update docs
devdazed authored
202 ## Column
203
204 Columns are returned as objects with the following structure:
205
206 ```javascript
207 {
208 name: 'Foo', //The column name
209 value: 'bar', //The column value
210 timestamp: Date(), //The date object of the timestamp for the column
211 ttl: 123456 //The ttl (in milliseconds) for the columns
212 }
213 ```
214
15761e5 Calvin French-Owen Updating thrift options and exposing consistency level
calvinfo authored
215 ## ConsistencyLevel
216
217 Helenus supports using a custom consistency level. By default, when using the thrift client reads and writes will both use `QUORUM`. When using the thrift driver, you simply pass a custom level in the options:
218
219 ```javascript
154790c Russ Bradberry Fixed invalid examples
devdazed authored
220 cf.insert(key, values, {consistency : helenus.ConsistencyLevel.ANY}, callback);
15761e5 Calvin French-Owen Updating thrift options and exposing consistency level
calvinfo authored
221 ```
222
223
8d97e14 Russ Bradberry bump version
devdazed authored
224 ## Contributors
225
891d6b9 Russ Bradberry readme updates
devdazed authored
226 * Russell Bradberry - @devdazed
227 * Matthias Eder - @matthiase
228 * Christoph Tavan - @ctavan
8d97e14 Russ Bradberry bump version
devdazed authored
229
94cc7ce Eric Lubow Updated README
elubow authored
230 ## License
d9d37c6 Russ Bradberry initial commit
devdazed authored
231
232 (The MIT License)
233
805b4c1 Russ Bradberry docs
devdazed authored
234 Copyright (c) 2011 SimpleReach <rbradberry@simplereach.com>
d9d37c6 Russ Bradberry initial commit
devdazed authored
235
236 Permission is hereby granted, free of charge, to any person obtaining
237 a copy of this software and associated documentation files (the
238 'Software'), to deal in the Software without restriction, including
239 without limitation the rights to use, copy, modify, merge, publish,
240 distribute, sublicense, and/or sell copies of the Software, and to
241 permit persons to whom the Software is furnished to do so, subject to
242 the following conditions:
243
244 The above copyright notice and this permission notice shall be
245 included in all copies or substantial portions of the Software.
246
247 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
248 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
249 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
250 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
251 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
252 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
94cc7ce Eric Lubow Updated README
elubow authored
253 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.