Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100755 279 lines (235 sloc) 10.331 kb
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
1 Cassandra PHP-based client library for managing and querying your Cassandra
2 cluster. It's a high-level library performing all the rather complex low-level
3 lifting and providing a simple to learn and use interface.
4
5 Features:
6 - simple and intuitive interface
f906260 Priit Kallas Added Doxyfile and generated documentation.
authored
7 - well covered with unit tests (> 90%)
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
8 - support for multiple server pools using named singletons
9 - requires including a single file
10 - uses reasonable defaults through-out
11 - powerful syntax for querying data
12 - enables managing keyspaces and column-families
13 - automatic packing of datatypes using column metadata
14 - retries failed queries using back-off strategy
15 - built with performance in mind (caches schema description etc)
16 - well documented API and a working example
17
f906260 Priit Kallas Added Doxyfile and generated documentation.
authored
18 The class diagram is available on the wiki, see:
19 https://github.com/kallaspriit/Cassandra-PHP-Client-Library/wiki
20
21 The library uses the permissive MIT licence.
22
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
23
24 The following example covers most of what you need to know to use this library.
25 It should work out-of-box on a machine with default cassandra setup running. The
26 example file is contained in the download.
27
91fc18f Priit Kallas Fixed issued #1 and #2
authored
28 Open https://github.com/kallaspriit/Cassandra-PHP-Client-Library/blob/master/example.php
63c2994 Priit Kallas Improved readme.
authored
29 for prettier code.
30
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
31 <?php
32
a919fcd Priit Kallas Updated test to work with the new thrift and cassandra versions
authored
33 // show all the errors
34 error_reporting(E_ALL);
35
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
36 // the only file that needs including into your project
37 require_once 'Cassandra.php';
38
39 // list of seed servers to randomly connect to
40 // all the parameters are optional and default to given values
41 $servers = array(
42 array(
43 'host' => '127.0.0.1',
44 'port' => 9160,
45 'use-framed-transport' => true,
46 'send-timeout-ms' => 1000,
47 'receive-timeout-ms' => 1000
48 )
49 );
50
51 // create a named singleton, the second parameter name defaults to "main"
52 // you can have several named singletons with different server pools
53 $cassandra = Cassandra::createInstance($servers);
54
55 // at any point in code, you can get the named singleton instance, the name
56 // again defaults to "main" so no need to define it if using single instance
57 $cassandra2 = Cassandra::getInstance();
58
59 // drop the example keyspace and ignore errors should it not exist
60 try {
61 $cassandra->dropKeyspace('CassandraExample');
62 } catch (Exception $e) {}
63
64
65 // create a new keyspace, accepts extra parameters for replication options
66 // normally you don't do it every time
67 $cassandra->createKeyspace('CassandraExample');
68
69 // start using the created keyspace
70 $cassandra->useKeyspace('CassandraExample');
71
72 // if a request fails, it will be retried for this many times, each time backing
73 // down for a bit longer period to prevent floods; defaults to 5
74 $cassandra->setMaxCallRetries(5);
75
76 // create a standard column family with given column metadata
77 $cassandra->createStandardColumnFamily(
78 'CassandraExample', // keyspace name
79 'user', // the column-family name
80 array( // list of columns with metadata
81 array(
82 'name' => 'name',
83 'type' => Cassandra::TYPE_UTF8,
84 'index-type' => Cassandra::INDEX_KEYS, // create secondary index
85 'index-name' => 'NameIdx'
86 ),
87 array(
88 'name' => 'email',
89 'type' => Cassandra::TYPE_UTF8
90 ),
91 array(
92 'name' => 'age',
93 'type' => Cassandra::TYPE_INTEGER,
94 'index-type' => Cassandra::INDEX_KEYS,
95 'index-name' => 'AgeIdx'
96 )
97 )
98 // actually accepts more parameters with reasonable defaults
99 );
100
101 // create a super column family
102 $cassandra->createSuperColumnFamily(
103 'CassandraExample',
104 'cities',
105 array(
106 array(
107 'name' => 'population',
108 'type' => Cassandra::TYPE_INTEGER
109 ),
110 array(
111 'name' => 'comment',
112 'type' => Cassandra::TYPE_UTF8
113 )
114 ),
115 // see the definition for these additional optional parameters
116 Cassandra::TYPE_UTF8,
117 Cassandra::TYPE_UTF8,
118 Cassandra::TYPE_UTF8,
119 'Capitals supercolumn test',
120 1000,
121 1000,
122 0.5
123 );
124
125 // lets fetch and display the schema of created keyspace
126 $schema = $cassandra->getKeyspaceSchema('CassandraExample');
127 echo 'Schema: <pre>'.print_r($schema, true).'</pre><hr/>';
a919fcd Priit Kallas Updated test to work with the new thrift and cassandra versions
authored
128 /*
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
129 // should we need to, we can access the low-level client directly
130 $version = $cassandra->getConnection()->getClient()->describe_version();
131 echo 'Version directly: <pre>'.print_r($version, true).'</pre><hr/>';
a919fcd Priit Kallas Updated test to work with the new thrift and cassandra versions
authored
132 */
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
133 // if implemented, use the wrapped methods as these are smarter - can retry etc
134 $version = $cassandra->getVersion();
135 echo 'Version through wrapper: <pre>'.print_r($version, true).'</pre><hr/>';
136
137 // cluster is a pool of connections
138 $cluster = $cassandra->getCluster();
139 echo 'Cluster: <pre>'.print_r($cluster, true).'</pre><hr/>';
140
141 // you can ask the cluster for a connection to a random seed server from pool
142 $connection = $cluster->getConnection();
143 echo 'Connection: <pre>'.print_r($connection, true).'</pre><hr/>';
144
145 // access column family, using the singleton syntax
146 // there is shorter "cf" methid that is an alias to "columnFamily"
147 $userColumnFamily = Cassandra::getInstance()->columnFamily('user');
148 echo 'Column family "user": <pre>'.print_r($userColumnFamily, true).'</pre><hr/>';
149
150 // lets insert some test data using the convinience method "set" of Cassandra
151 // the syntax is COLUMN_FAMILY_NAME.KEY_NAME
152 $cassandra->set(
153 'user.john',
154 array(
155 'email' => 'john@smith.com',
156 'name' => 'John Smith',
157 'age' => 34
158 )
159 );
160
161 // when inserting data, it's ok if key name contains ".", no need to escape them
162 $cassandra->set(
163 'user.jane.doe',
164 array(
165 'email' => 'jane@doe.com',
166 'name' => 'Jane Doe',
167 'age' => 24
168 )
169 );
170
171 // longer way of inserting data, first getting the column family
172 $cassandra->cf('user')->set(
173 'chuck', // key name
174 array( // column names and values
175 'email' => 'chuck@norris.com',
176 'name' => 'Chuck Norris',
177 'age' => 24
178 ),
179 Cassandra::CONSISTENCY_QUORUM // optional consistency to use
180 // also accepts optional custom timestamp and time to live
181 );
182
183 // lets fetch all the information about user john
184 $john = $cassandra->get('user.john');
185 echo 'User "john": <pre>'.print_r($john, true).'</pre><hr/>';
186
187 // since the jane key "jane.doe" includes a ".", we have to escape it
188 $jane = $cassandra->get('user.'.Cassandra::escape('jane.doe'));
189 echo 'User "jane.doe": <pre>'.print_r($jane, true).'</pre><hr/>';
190
191 // there is some syntatic sugar on the query of Cassandra::get() allowing you
192 // to fetch specific columns, ranges of them, limit amount etc. for example,
193 // lets only fetch columns name and age
194 $chuck = $cassandra->get('user.chuck:name,age');
195 echo 'User "chuck", name and age: <pre>'.print_r($chuck, true).'</pre><hr/>';
196
197 // fetch all solumns from age to name (gets all columns in-between too)
198 $chuck2 = $cassandra->get('user.chuck:age-name');
199 echo 'User "chuck", columns ago to name: <pre>'.print_r($chuck2, true).'</pre><hr/>';
200
201 // the range columns do not need to exist, we can get character ranges
202 $chuck3 = $cassandra->get('user.chuck:a-z');
203 echo 'User "chuck", columns a-z: <pre>'.print_r($chuck3, true).'</pre><hr/>';
204
205 // when performing range queries, we can also limit the number of columns
206 // returned (2); also the method accepts consistency level as second parameter
207 $chuck4 = $cassandra->get('user.chuck:a-z|2', Cassandra::CONSISTENCY_ALL);
208 echo 'User "chuck", columns a-z, limited to 2 columns: <pre>'.print_r($chuck4, true).'</pre><hr/>';
209
210 // the Cassandra::get() is a convinience method proxying to lower level
211 // CassandraColumnFamily::get(), no need to worry about escaping with this.
212 // column family has additional methods getAll(), getColumns(), getColumnRange()
213 // that all map to lower level get() calls with more appopriate parameters
214 $jane2 = $cassandra->cf('user')->get('jane.doe');
215 echo 'User "jane.doe", lower level api: <pre>'.print_r($jane2, true).'</pre><hr/>';
216
217 // we defined a secondary index on "age" column of "user" column family so we
218 // can use CassandraColumnFamily::getWhere() to fetch users of specific age.
219 // this returns an iterator that you can go over with foreach or use the
220 // getAll() method that fetches all the data and returns an array
221 $aged24 = $cassandra->cf('user')->getWhere(array('age' => 24));
222 echo 'Users at age 24: <pre>'.print_r($aged24->getAll(), true).'</pre><hr/>';
223
224 // if we know we are going to need to values of several keys, we can request
225 // them in a single query for better performance
226 $chuckAndJohn = $cassandra->cf('user')->getMultiple(array('chuck', 'john'));
227 echo 'Users "chuck" and "john": <pre>'.print_r($chuckAndJohn, true).'</pre><hr/>';
228
a919fcd Priit Kallas Updated test to work with the new thrift and cassandra versions
authored
229 /* Uncomment this when using order preserving partitioner
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
230 // we can fetch a range of keys but this is predictable only if using an
231 // order preserving partitioner, Cassandra defaults to random one
232 // again as there may be more results than it's reasonable to fetch in a single
233 // query, an iterator is returned that can make several smaller range queries
234 // as the data is iterated
08412af Priit Kallas Finished with the docblock comments of the library, all tests and the ex...
authored
235 $usersAZ = $cassandra->cf('user')->getKeyRange('a', 'z');
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
236 echo 'Users with keys in range a-z: <pre>'.print_r($usersAZ->getAll(), true).'</pre><hr/>';
a919fcd Priit Kallas Updated test to work with the new thrift and cassandra versions
authored
237 */
dc718b5 Priit Kallas Added example file explaining the core features of the library.
authored
238
239 // find the number of columns a key has, we could also request for ranges
240 $chuckColumnCount = $cassandra->cf('user')->getColumnCount('chuck');
241 echo 'User "chuck" column count: <pre>'.print_r($chuckColumnCount, true).'</pre><hr/>';
242
243 // we can find column counts for several keys at once
244 $chuckJaneColumnCounts = $cassandra->cf('user')->getColumnCounts(array('chuck', 'jane.doe'));
245 echo 'User "chuck" and "jane.doe" column counts: <pre>'.print_r($chuckJaneColumnCounts, true).'</pre><hr/>';
246
247 // setting supercolumn values is similar to normal column families
248 $cassandra->set(
249 'cities.Estonia',
250 array(
251 'Tallinn' => array(
252 'population' => '411980',
253 'comment' => 'Capital of Estonia',
254 'size' => 'big'
255 ),
256 'Tartu' => array(
257 'population' => '98589',
258 'comment' => 'City of good thoughts',
259 'size' => 'medium'
260 )
261 )
262 );
263
264 // fetch all columns of Tartu in Estonia of cities
265 $tartu = $cassandra->cf('cities')->getAll('Estonia', 'Tartu');
266 echo 'Super-column cities.Estonia.Tartu: <pre>'.print_r($tartu, true).'</pre><hr/>';
267
268 // we could also use the higher level Cassandra::get() to fetch supercolumn info
269 // we can still use the additional filters of columns
270 $tallinn = $cassandra->get('cities.Estonia.Tallinn:population,size');
271 echo 'Super-column cities.Estonia.Tallinn: <pre>'.print_r($tallinn, true).'</pre><hr/>';
272
273 // you can delete all the data in a column family using "truncate"
274 $cassandra->truncate('user');
275
276 // you may choose to drop an entire keyspace
277 $cassandra->dropKeyspace('CassandraExample');
278
279 ?>
Something went wrong with that request. Please try again.