Repository: calcite Updated Branches: refs/heads/master cfd2071a4 -> 4b93fa826
Document Cassandra adapter (Michael Mior) Close apache/calcite#213 Project: http://git-wip-us.apache.org/repos/asf/calcite/repo Commit: http://git-wip-us.apache.org/repos/asf/calcite/commit/00e755db Tree: http://git-wip-us.apache.org/repos/asf/calcite/tree/00e755db Diff: http://git-wip-us.apache.org/repos/asf/calcite/diff/00e755db Branch: refs/heads/master Commit: 00e755db100c4bccfb2976a03c4f75a2adfc69be Parents: cfd2071 Author: Michael Mior <[email protected]> Authored: Mon Mar 21 13:43:41 2016 -0400 Committer: Julian Hyde <[email protected]> Committed: Mon Mar 21 20:19:21 2016 -0700 ---------------------------------------------------------------------- site/_docs/cassandra.md | 99 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/calcite/blob/00e755db/site/_docs/cassandra.md ---------------------------------------------------------------------- diff --git a/site/_docs/cassandra.md b/site/_docs/cassandra.md new file mode 100644 index 0000000..dcff107 --- /dev/null +++ b/site/_docs/cassandra.md @@ -0,0 +1,99 @@ +--- +layout: docs +title: Cassandra adapter +permalink: /docs/cassandra.html +--- +<!-- +{% comment %} +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to you under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +{% endcomment %} +--> + +For instructions on downloading and building Calcite, start with the +[tutorial](/docs/tutorial.html). Once you've managed to compile the +project, you can return here to start querying Cassandra with Calcite. +First, we need a [model definition](/docs/model.html). The model gives +Calcite the necessary parameters to create an instance of the Cassandra +adapter. Note that while models can contain definitions of +[materializations](/docs/model.html#materialization), the adapter will +attempt to automatically populate any materialized views +[defined in Cassandra](http://www.datastax.com/dev/blog/new-in-cassandra-3-0-materialized-views). + +A basic example of a model file is given below: + +{% highlight json %} +{ + version: '1.0', + defaultSchema: 'twissandra', + schemas: [ + { + name: 'twissandra', + type: 'custom', + factory: 'org.apache.calcite.adapter.cassandra.CassandraSchemaFactory', + operand: { + host: 'localhost', + keyspace: 'twissandra' + } + } + ] +} +{% endhighlight %} + +Assuming this file is stored as `model.json`, you can connect to Cassandra via [`sqlline`](https://github.com/julianhyde/sqlline) as follows: + +{% highlight bash %} +$ ./sqlline +sqlline> !connect jdbc:calcite:model=model.json admin admin +{% endhighlight %} + +`sqlline` will now accept SQL queries which access your CQL tables. +However, you're not restricted to issuing queries supported by +[CQL](https://cassandra.apache.org/doc/cql3/CQL-2.2.html). +Calcite allows you to perform complex operations such as aggregations +or joins. The adapter will attempt to compile the query into the most +efficient CQL possible by exploiting filtering and sorting directly in +Cassandra where possible. + +For example, in the example dataset there is a CQL table named `timeline` +with `username` as the partition key and `time` as the clustering key. + +We can issue a simple query to fetch the most recent tweet ID of the +user by writing standard SQL: + +{% highlight sql %} +sqlline> SELECT "tweet_id" FROM "timeline" WHERE "username"='JmuhsAaMdw' ORDER BY "time" DESC LIMIT 1; ++----------+ +| tweet_id | ++----------+ +| f3d3d4dc-d05b-11e5-b58b-90e2ba530b12 | ++----------+ +{% endhighlight %} + +While executing this query, the Cassandra adapter is able to recognize +that `username` is the partition key and can be filtered by Cassandra. +It also recognizes the clustering key `time` and pushes the ordering to +Cassandra as well. + +The final CQL query given to Cassandra is below: + +{% highlight sql %} +SELECT username, time, tweet_id FROM "timeline" WHERE username = 'JmuhsAaMdw' ORDER BY time DESC ALLOW FILTERING; +{% endhighlight %} + +There is still significant work to do in improving the flexibility and +performance of the adapter, but if you're looking for a quick way to +gain additional insights into data stored in Cassandra, Calcite should +prove useful.
