Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 140 lines (102 sloc) 4.699 kB
4dc0cd5 @ostinelli added readme and refactored example code
authored
1 ## ErlCassa
6487122 @ostinelli initial commit
authored
2
4dc0cd5 @ostinelli added readme and refactored example code
authored
3 ErlCassa is an Erlang client to the Cassandra Query Language (CQL). This is an alpha library which should not be used in production.
4
5 ## About CQL
6
7 [Cassandra](http://cassandra.apache.org/) originally went with a Thrift RPC-based API as a way to provide a common denominator that more idiomatic clients could build upon independently. However, this worked poorly in practice: raw Thrift is too low-level to use productively, and keeping pace with new API methods to support (for example) indexes in 0.7 or distributed counters in 0.8 is too much for many maintainers to keep pace with.
8
9 CQL, the Cassandra Query Language, addresses this by pushing all implementation details to the server; all the client has to know for any operation is how to interpret “resultset” objects. So adding a feature like counters just requires teaching the CQL parser to understand “column + N” notation; no client-side changes are necessary.
10
11 CQL specification can be read here: (http://github.com/apache/cassandra/blob/trunk/doc/cql/CQL.textile)
12
13 ## Install Dependencies
14
15 * You will need [Apache Thrift](http://thrift.apache.org/download/) > 0.80.
16
17 ### Note for OSX developers
18
19 The easiest way to install Thrift on your system is to:
20
21 * [install MacPorts](http://www.macports.org/install.php);
22 * Download and install Thrift dependencies using MacPorts by issuing the command:
23
24 ```bash
25 $ sudo port install boost libevent pkgconfig
26 ```
27
28 * [Download Apache Thrift](http://thrift.apache.org/download/), then compile and install it:
29
30 ```bash
31 $ ./configure --prefix=/usr/local/ --with-boost=/opt/local --with-libevent=/opt/local \
32 --without-csharp --without-ruby --without-perl --without-haskell
33 $ make
34 $ sudo make install
35 ```
36
37 ## Quick Start
38
39 ### Connecting to Cassandra
40
41 ```erlang
42 {ok, C} = erlcassa_client:connect("localhost", 9160).
43 ```
44
45 ### Creating a Key Space
46
47 ```erlang
48 {result, ok} = erlcassa_client:cql_execute(C,
49 "CREATE KEYSPACE test1 WITH strategy_class = SimpleStrategy AND strategy_options:replication_factor = 1;"
50 ).
51 ```
52
53 ### Using a Key Space
54
55 ```erlang
56 erlcassa_client:cql_execute(C, "USE test1;").
57 ```
58
59 ### Creating a Column Family
60
61 ```erlang
62 {result, ok} = erlcassa_client:cql_execute(C, "
63 CREATE COLUMNFAMILY testdata (
64 KEY int PRIMARY KEY,
65 text_field text,
66 ascii_field ascii,
67 bigint_field bigint,
68 blob_field blob,
69 boolean_field boolean,
70 counter_field counter,
71 decimal_field decimal,
72 double_field double,
73 float_field float,
74 timestamp_field timestamp,
75 uuid_field uuid,
76 varchar_field varchar,
77 varint_field varint);
78 ").
79 ```
80
81 ### Inserting an entry in a Column Family
82
83 ```erlang
84 {result, ok} = erlcassa_client:cql_execute(C, "
85 INSERT INTO testdata (
86 KEY, text_field, ascii_field, bigint_field, blob_field, boolean_field,
87 decimal_field, double_field, float_field, timestamp_field, uuid_field,
88 varchar_field, varint_field
89 ) VALUES (
90 123, 'text', 'ascii', 1234567890, 'aaaaaa', true,
91 42, 1.3513535135, 1.2345, 1324244361517000, 'f47ac10b-58cc-4372-a567-0e02b2c3d479',
92 'encoded', 13
93 );
94 ").
95 ```
96
97 ### Getting rows from a Column Family, as proplist (dict is the other possible return value format)
98
99 ```erlang
100 {result, {rows, Rows}} = erlcassa_client:cql_execute(C, "SELECT * FROM testdata", proplist).
101 ```
102
103 ### Returning an entire Column from an individual Row
104
105 ```erlang
106 Column = erlcassa_client:get_column("KEY", Row).
107 ```
108
109 ### Dropping a Column Family
110
111 ```erlang
112 {result, ok} = erlcassa_client:cql_execute(C, "DROP COLUMNFAMILY testdata;").
113 ```
114
115 ### Dropping a Keyspace
116
117 ```erlang
118 {result, ok} = erlcassa_client:cql_execute(C, "DROP KEYSPACE test1;").
119 ```
120
121 ## License
122
123 The MIT License (MIT)
124
125 Copyright (c) 2011, Roberto Ostinelli
126
127 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
128 associated documentation files (the "Software"), to deal in the Software without restriction, including
129 without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
130 copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
131 following conditions:
132
133 The above copyright notice and this permission notice shall be included in all copies or substantial
134 portions of the Software.
135
136 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
137 LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
138 EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
139 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
140 THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.