You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by ee...@apache.org on 2010/10/31 15:37:02 UTC
svn commit: r1029361 - in /cassandra/trunk/doc: ./ cql/ cql/CQL.html
cql/CQL.textile
Author: eevans
Date: Sun Oct 31 14:37:01 2010
New Revision: 1029361
URL: http://svn.apache.org/viewvc?rev=1029361&view=rev
Log:
CQL documentation
Patch by eevans
Added:
cassandra/trunk/doc/
cassandra/trunk/doc/cql/
cassandra/trunk/doc/cql/CQL.html
cassandra/trunk/doc/cql/CQL.textile
Added: cassandra/trunk/doc/cql/CQL.html
URL: http://svn.apache.org/viewvc/cassandra/trunk/doc/cql/CQL.html?rev=1029361&view=auto
==============================================================================
--- cassandra/trunk/doc/cql/CQL.html (added)
+++ cassandra/trunk/doc/cql/CQL.html Sun Oct 31 14:37:01 2010
@@ -0,0 +1,16 @@
+<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/></head><body><h1 id="CassandraQueryLanguageCQLv0.99.0">Cassandra Query Language (CQL) v0.99.0</h1><h2 id="TableofContents">Table of Contents</h2><ol style="list-style: none;"><li><a href="#CassandraQueryLanguageCQLv0.99.0">Cassandra Query Language (CQL) v0.99.0</a><ol style="list-style: none;"><li><a href="#TableofContents">Table of Contents</a></li><li><a href="#USE">USE</a></li><li><a href="#SELECT">SELECT</a><ol style="list-style: none;"><li><a href="#ColumnFamily">Column Family</a></li><li><a href="#ConsistencyLevel">Consistency Level</a></li><li><a href="#Expressions">Expressions</a></li><li><a href="#Limits">Limits</a></li><li><a href="#Ordering">Ordering</a></li></ol></li><li><a href="#UPDATE">UP
DATE</a><ol style="list-style: none;"><li><a href="#ColumnFamily2">Column Family</a></li><li><a href="#ConsistencyLevel2">Consistency Level</a></li><li><a href="#RowsandColumns">Rows and Columns</a></li></ol></li><li><a href="#CommonIdioms">Common Idioms</a><ol style="list-style: none;"><li><a href="#consistency">Specifying Consistency</a></li><li><a href="#terms">Term specification</a><ol style="list-style: none;"><li><a href="#StringLiterals">String Literals</a></li><li><a href="#Integerslongs">Integers / longs</a></li></ol></li></ol></li></ol></li></ol><h2 id="USE">USE</h2><p><i>Synopsis:</i></p><pre><code>USE <KEYSPACE>;
+</code></pre><p>A <code>USE</code> statement consists of the <code>USE</code> keyword, followed by a valid keyspace name. Its purpose is to assign the per-connection, current working keyspace. All subsequent keyspace-specific actions will be performed in the context of the supplied value.</p><h2 id="SELECT">SELECT</h2><p><i>Synopsis:</i></p><pre><code>SELECT [FROM] <COLUMN FAMILY> [USING <CONSISTENCY>]
+ WHERE <EXRESSION> [ROWLIMIT N] [COLLIMIT N] [ASC | DESC];
+</code></pre><p>A <code>SELECT</code> is used to read one or more records from a Cassandra column family. It returns a result-set of rows, where each row consists of a key and a collection of columns corresponding to the query.</p><h3 id="ColumnFamily">Column Family</h3><pre><code>SELECT [FROM] <COLUMN FAMILY> ...
+</code></pre><p>Statements begin with the <code>SELECT</code> keyword followed by a Cassandra column family name. The keyword <code>FROM</code> can be used as a delimiter to improve readability, but is not required.</p><h3 id="ConsistencyLevel">Consistency Level</h3><pre><code>SELECT ... [USING <CONSISTENCY>] ...
+</code></pre><p>Following the column family identifier is an optional <a href="#consistency">consistency level specification</a>.</p><h3 id="Expressions">Expressions</h3><pre><code>SELECT ... <EXPRESSION>
+SELECT ... [[KEY | COL] [> | >= | = | < | <=] TERM] [[AND ...] ...]
+</code></pre><p>The expression portion of a CQL <code>SELECT</code> statement consists of one or more relations delimited by the <code>AND</code> keyword. Relations are defined as one of either the <code>KEY</code> or <code>COLUMN</code> keywords, a relational operator (<code>></code>, <code>>=</code>, <code>=</code>, <code><</code>, <code><=</code>), and a <a href="#terms">term</a>.</p><p><em>NOTE: The keyword <code>COLUMN</code> can be abbreviated as <code>COL</code>.</em></p><p><em>NOTE: Key and column ranges are always inclusive so the semantics of <code>>=</code> and <code>></code>, and <code><=</code> and <code><</code> are identical. This is subject to change.</em></p><h3 id="Limits">Limits</h3><pre><code>SELECT ... <EXPRESSION> [ROWLIMIT N | COLLIMIT N] ...
+</code></pre><p>Limiting the number of row and/or column results can be achieved by including one or both of the optional <code>ROWLIMIT</code> and <code>COLLIMIT</code> clauses after a <code>SELECT</code> expression.</p><h3 id="Ordering">Ordering</h3><pre><code>SELECT ... [[ASC | ASCENDING] | [DESC | DESCENDING]]
+</code></pre><p>By default, results are returned in the order determined by the column family comparator, <em>this is always considered ascending order</em>. Reversing this sort order is possible by supplying the <code>DESCENDING</code> clause in <code>SELECT</code> statements.</p><p>The <code>ASCENDING</code> keyword is also included, both for completeness sake, and to improve statement readability if desired. It has no effect otherwise.</p><p><em>NOTE: The keywords <code>ASC</code> and <code>DESC</code> are valid abbreviations for <code>ASCENDING</code> and <code>DESCENDING</code> respectively.</em></p><h2 id="UPDATE">UPDATE</h2><p><em>Synopsis:</em></p><pre><code>UPDATE <COLUMN FAMILY> [USING CONSISTENCY.<CL>] WITH
+ ROW(<KEY>, COL(<NAME>, <VALUE>), ...);
+</code></pre><p>An <code>UPDATE</code> is used to write one or more records to a Cassandra column family. No results are returned.</p><h3 id="ColumnFamily2">Column Family</h3><pre><code>UPDATE <COLUMN FAMILY> ...
+</code></pre><p>Statements begin with the <code>UPDATE</code> keyword followed by a Cassandra column family name.</p><h3 id="ConsistencyLevel2">Consistency Level</h3><pre><code>SELECT ... [USING <CONSISTENCY>] ...
+</code></pre><p>Following the column family identifier is an optional <a href="#consistency">consistency level specification</a>.</p><h3 id="RowsandColumns">Rows and Columns</h3><pre><code>... WITH ROW(<KEY>, COL(<NAME>, <VALUE>), ...)[, ROW(<KEY>, ...)];
+</code></pre><p>Rows are constructed by creating a parenthesized expression using the <code>ROW</code> keyword. Within the parenthesis, row specifications contain a key <a href="#terms">term</a>, followed by a comma, and one or more comma delimited column specifications. Columns are in turn a parenthesized expression using the <code>COLUMN</code> keyword, with two comma delimited <a href="#terms">term</a> arguments, the column name and value respectively. More than one row can be specified by separating them with commas.</p><p><em>NOTE: While there are no isolation guarantees, <code>UPDATE</code> queries are atomic.</em></p><h2 id="CommonIdioms">Common Idioms</h2><h3 id="consistency">Specifying Consistency</h3><pre><code>... USING <CONSISTENCY> ...
+</code></pre><p>Consistency level specifications are made up the keyword <code>USING</code>, followed by a consistency level identifier. Valid consistency levels are as follows:</p><ul><li><code>CONSISTENCY.ZERO</code></li><li><code>CONSISTENCY.ONE</code> (default)</li><li><code>CONSISTENCY.QUORUM</code></li><li><code>CONSISTENCY.ALL</code></li><li><code>CONSISTENCY.DCQUORUM</code></li><li><code>CONSISTENCY.DCQUORUMSYNC</code></li></ul><h3 id="terms">Term specification</h3><p>Where possible, the type of terms are inferred; the following term types are supported:</p><h4 id="StringLiterals">String Literals</h4><p>String literals are any value enclosed in double-quotes, (`"`). String literals are treated as raw bytes; no interpolation is performed.</p><h4 id="Integerslongs">Integers / longs</h4><p>Integers are any term consisting soley of unquoted numericals, longs are any otherwise valid integer term followed by an upper case “L”, (e.g. 100L). It is an error to s
pecify an integer term that will not fit in 4 bytes unsigned, or a long that will not fit in 8 bytes unsigned.</p></body></html>
\ No newline at end of file
Added: cassandra/trunk/doc/cql/CQL.textile
URL: http://svn.apache.org/viewvc/cassandra/trunk/doc/cql/CQL.textile?rev=1029361&view=auto
==============================================================================
--- cassandra/trunk/doc/cql/CQL.textile (added)
+++ cassandra/trunk/doc/cql/CQL.textile Sun Oct 31 14:37:01 2010
@@ -0,0 +1,120 @@
+h1. Cassandra Query Language (CQL) v0.99.0
+
+h2. Table of Contents
+
+{toc}
+
+h2. SELECT
+
+__Synopsis:__
+
+bc.
+SELECT [FROM] <COLUMN FAMILY> [USING <CONSISTENCY>]
+ WHERE <EXRESSION> [ROWLIMIT N] [COLLIMIT N] [ASC | DESC];
+
+A @SELECT@ is used to read one or more records from a Cassandra column family. It returns a result-set of rows, where each row consists of a key and a collection of columns corresponding to the query.
+
+h3. Column Family
+
+bc.
+SELECT [FROM] <COLUMN FAMILY> ...
+
+Statements begin with the @SELECT@ keyword followed by a Cassandra column family name. The keyword @FROM@ can be used as a delimiter to improve readability, but is not required.
+
+h3. Consistency Level
+
+bc.
+SELECT ... [USING <CONSISTENCY>] ...
+
+Following the column family identifier is an optional "consistency level specification":#consistency.
+
+h3. Expressions
+
+bc.
+SELECT ... <EXPRESSION>
+SELECT ... [[KEY | COL] [> | >= | = | < | <=] TERM] [[AND ...] ...]
+
+The expression portion of a CQL @SELECT@ statement consists of one or more relations delimited by the @AND@ keyword. Relations are defined as one of either the @KEY@ or @COLUMN@ keywords, a relational operator (@>@, @>=@, @=@, @<@, @<=@), and a "term":#terms.
+
+_NOTE: The keyword @COLUMN@ can be abbreviated as @COL@._
+
+_NOTE: Key and column ranges are always inclusive so the semantics of @>=@ and @>@, and @<=@ and @<@ are identical. This is subject to change._
+
+h3. Limits
+
+bc.
+SELECT ... <EXPRESSION> [ROWLIMIT N | COLLIMIT N] ...
+
+Limiting the number of row and/or column results can be achieved by including one or both of the optional @ROWLIMIT@ and @COLLIMIT@ clauses after a @SELECT@ expression.
+
+h3. Ordering
+
+bc.
+SELECT ... [[ASC | ASCENDING] | [DESC | DESCENDING]]
+
+By default, results are returned in the order determined by the column family comparator, _this is always considered ascending order_. Reversing this sort order is possible by supplying the @DESCENDING@ clause in @SELECT@ statements.
+
+The @ASCENDING@ keyword is also included, both for completeness sake, and to improve statement readability if desired. It has no effect otherwise.
+
+_NOTE: The keywords @ASC@ and @DESC@ are valid abbreviations for @ASCENDING@ and @DESCENDING@ respectively._
+
+h2. UPDATE
+
+_Synopsis:_
+
+bc.
+UPDATE <COLUMN FAMILY> [USING CONSISTENCY.<CL>] WITH
+ ROW(<KEY>, COL(<NAME>, <VALUE>), ...);
+
+An @UPDATE@ is used to write one or more records to a Cassandra column family. No results are returned.
+
+h3. Column Family
+
+bc.
+UPDATE <COLUMN FAMILY> ...
+
+Statements begin with the @UPDATE@ keyword followed by a Cassandra column family name.
+
+h3. Consistency Level
+
+bc.
+SELECT ... [USING <CONSISTENCY>] ...
+
+Following the column family identifier is an optional "consistency level specification":#consistency.
+
+h3. Rows and Columns
+
+bc.
+... WITH ROW(<KEY>, COL(<NAME>, <VALUE>), ...)[, ROW(<KEY>, ...)];
+
+Rows are constructed by creating a parenthesized expression using the @ROW@ keyword. Within the parenthesis, row specifications contain a key "term":#terms, followed by a comma, and one or more comma delimited column specifications. Columns are in turn a parenthesized expression using the @COLUMN@ keyword, with two comma delimited "term":#terms arguments, the column name and value respectively. More than one row can be specified by separating them with commas.
+
+_NOTE: While there are no isolation guarantees, @UPDATE@ queries are atomic._
+
+h2. Common Idioms
+
+h3(#consistency). Specifying Consistency
+
+bc.
+... USING <CONSISTENCY> ...
+
+Consistency level specifications are made up the keyword @USING@, followed by a consistency level identifier. Valid consistency levels are as follows:
+
+* @CONSISTENCY.ZERO@
+* @CONSISTENCY.ONE@ (default)
+* @CONSISTENCY.QUORUM@
+* @CONSISTENCY.ALL@
+* @CONSISTENCY.DCQUORUM@
+* @CONSISTENCY.DCQUORUMSYNC@
+
+h3(#terms). Term specification
+
+Where possible, the type of terms are inferred; the following term types are supported:
+
+h4. String Literals
+
+String literals are any value enclosed in double-quotes, (`"`). String literals are treated as raw bytes; no interpolation is performed.
+
+h4. Integers / longs
+
+Integers are any term consisting soley of unquoted numericals, longs are any otherwise valid integer term followed by an upper case "L", (e.g. 100L). It is an error to specify an integer term that will not fit in 4 bytes unsigned, or a long that will not fit in 8 bytes unsigned.