Added: cassandra/site/src/doc/3.10/cql/types.html URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/cql/types.html?rev=1757419&view=auto ============================================================================== --- cassandra/site/src/doc/3.10/cql/types.html (added) +++ cassandra/site/src/doc/3.10/cql/types.html Tue Aug 23 19:25:17 2016 @@ -0,0 +1,652 @@ +--- +layout: docpage + +title: "Documentation" + +is_homepage: false +is_sphinx_doc: true + +doc-parent: "The Cassandra Query Language (CQL)" + +doc-title: "Data Types" +doc-header-links: ' + <link rel="top" title="Apache Cassandra Documentation v3.10" href="../index.html"/> + <link rel="up" title="The Cassandra Query Language (CQL)" href="index.html"/> + <link rel="next" title="Data Definition" href="ddl.html"/> + <link rel="prev" title="Definitions" href="definitions.html"/> +' +doc-search-path: "../search.html" + +extra-footer: ' +<script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: "", + VERSION: "", + COLLAPSE_INDEX: false, + FILE_SUFFIX: ".html", + HAS_SOURCE: false, + SOURCELINK_SUFFIX: "" + }; +</script> +' + +--- +<div class="container-fluid"> + <div class="row"> + <div class="col-md-2"> + <div class="doc-navigation"> + <div class="doc-menu" role="navigation"> + <div class="navbar-header"> + <button type="button" class="pull-left navbar-toggle" data-toggle="collapse" data-target=".sidebar-navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + </div> + <div class="navbar-collapse collapse sidebar-navbar-collapse"> + <form id="doc-search-form" class="navbar-form" action="../search.html" method="get" role="search"> + <div class="form-group"> + <input type="text" size="30" class="form-control input-sm" name="q" placeholder="Search docs"> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </div> + </form> + + + + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../getting_started/index.html">Getting Started</a></li> +<li class="toctree-l1"><a class="reference internal" href="../architecture/index.html">Architecture</a></li> +<li class="toctree-l1"><a class="reference internal" href="../data_modeling/index.html">Data Modeling</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">The Cassandra Query Language (CQL)</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="definitions.html">Definitions</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Data Types</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#native-types">Native Types</a></li> +<li class="toctree-l3"><a class="reference internal" href="#working-with-timestamps">Working with timestamps</a></li> +<li class="toctree-l3"><a class="reference internal" href="#working-with-dates">Working with dates</a></li> +<li class="toctree-l3"><a class="reference internal" href="#working-with-times">Working with times</a></li> +<li class="toctree-l3"><a class="reference internal" href="#collections">Collections</a></li> +<li class="toctree-l3"><a class="reference internal" href="#user-defined-types">User-Defined Types</a></li> +<li class="toctree-l3"><a class="reference internal" href="#tuples">Tuples</a></li> +<li class="toctree-l3"><a class="reference internal" href="#custom-types">Custom Types</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="ddl.html">Data Definition</a></li> +<li class="toctree-l2"><a class="reference internal" href="dml.html">Data Manipulation</a></li> +<li class="toctree-l2"><a class="reference internal" href="indexes.html">Secondary Indexes</a></li> +<li class="toctree-l2"><a class="reference internal" href="mvs.html">Materialized Views</a></li> +<li class="toctree-l2"><a class="reference internal" href="security.html">Security</a></li> +<li class="toctree-l2"><a class="reference internal" href="functions.html">Functions</a></li> +<li class="toctree-l2"><a class="reference internal" href="json.html">JSON Support</a></li> +<li class="toctree-l2"><a class="reference internal" href="triggers.html">Triggers</a></li> +<li class="toctree-l2"><a class="reference internal" href="appendices.html">Appendices</a></li> +<li class="toctree-l2"><a class="reference internal" href="changes.html">Changes</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../configuration/index.html">Configuring Cassandra</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operating/index.html">Operating Cassandra</a></li> +<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Cassandra Tools</a></li> +<li class="toctree-l1"><a class="reference internal" href="../troubleshooting/index.html">Troubleshooting</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Cassandra Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">Frequently Asked Questions</a></li> +<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs and Contributing</a></li> +<li class="toctree-l1"><a class="reference internal" href="../contactus.html">Contact us</a></li> +</ul> + + + + </div><!--/.nav-collapse --> + </div> + </div> + </div> + <div class="col-md-8"> + <div class="content doc-content"> + <div class="container"> + + <div class="section" id="data-types"> +<span id="id1"></span><h1>Data Types<a class="headerlink" href="#data-types" title="Permalink to this headline">¶</a></h1> +<p>CQL is a typed language and supports a rich set of data types, including <a class="reference internal" href="#native-types"><span class="std std-ref">native types</span></a>, +<a class="reference internal" href="#collections"><span class="std std-ref">collection types</span></a>, <a class="reference internal" href="#udts"><span class="std std-ref">user-defined types</span></a>, <a class="reference internal" href="#tuples"><span class="std std-ref">tuple types</span></a> and <a class="reference internal" href="#custom-types"><span class="std std-ref">custom +types</span></a>:</p> +<pre> +<strong id="grammar-token-cql_type">cql_type</strong> ::= <a class="reference internal" href="#grammar-token-native_type"><code class="xref docutils literal"><span class="pre">native_type</span></code></a> | <a class="reference internal" href="#grammar-token-collection_type"><code class="xref docutils literal"><span class="pre">collection_type</span></code></a> | <a class="reference internal" href="#grammar-token-user_defined_type"><code class="xref docutils literal"><span class="pre">user_defined_type</span></code></a> | <a class="reference internal" href="#grammar-token-tuple_type"><code class="xref docutils literal"><span class="pre">tuple_type</span></code></a> | <a class="reference internal" href="#grammar-token-custom_type"><code class="xref docutils literal"><span class="pre">custom_type</span></code></a> +</pre> +<div class="section" id="native-types"> +<span id="id2"></span><h2>Native Types<a class="headerlink" href="#native-types" title="Permalink to this headline">¶</a></h2> +<p>The native types supported by CQL are:</p> +<pre> +<strong id="grammar-token-native_type">native_type</strong> ::= ASCII + | BIGINT + | BLOB + | BOOLEAN + | COUNTER + | DATE + | DECIMAL + | DOUBLE + | FLOAT + | INET + | INT + | SMALLINT + | TEXT + | TIME + | TIMESTAMP + | TIMEUUID + | TINYINT + | UUID + | VARCHAR + | VARINT +</pre> +<p>The following table gives additional informations on the native data types, and on which kind of <a class="reference internal" href="definitions.html#constants"><span class="std std-ref">constants</span></a> each type supports:</p> +<table border="1" class="docutils"> +<colgroup> +<col width="13%" /> +<col width="18%" /> +<col width="69%" /> +</colgroup> +<thead valign="bottom"> +<tr class="row-odd"><th class="head">type</th> +<th class="head">constants supported</th> +<th class="head">description</th> +</tr> +</thead> +<tbody valign="top"> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">ascii</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a></td> +<td>ASCII character string</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">bigint</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a></td> +<td>64-bit signed long</td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">blob</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-blob"><code class="xref std std-token docutils literal"><span class="pre">blob</span></code></a></td> +<td>Arbitrary bytes (no validation)</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">boolean</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-boolean"><code class="xref std std-token docutils literal"><span class="pre">boolean</span></code></a></td> +<td>Either <code class="docutils literal"><span class="pre">true</span></code> or <code class="docutils literal"><span class="pre">false</span></code></td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">counter</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a></td> +<td>Counter column (64-bit signed value). See <a class="reference internal" href="#counters"><span class="std std-ref">Counters</span></a> for details</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">date</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a>, +<a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a></td> +<td>A date (with no corresponding time value). See <a class="reference internal" href="#dates"><span class="std std-ref">Working with dates</span></a> below for details</td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">decimal</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a>, +<a class="reference internal" href="definitions.html#grammar-token-float"><code class="xref std std-token docutils literal"><span class="pre">float</span></code></a></td> +<td>Variable-precision decimal</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">double</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a> +<a class="reference internal" href="definitions.html#grammar-token-float"><code class="xref std std-token docutils literal"><span class="pre">float</span></code></a></td> +<td>64-bit IEEE-754 floating point</td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">float</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a>, +<a class="reference internal" href="definitions.html#grammar-token-float"><code class="xref std std-token docutils literal"><span class="pre">float</span></code></a></td> +<td>32-bit IEEE-754 floating point</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">inet</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a></td> +<td>An IP address, either IPv4 (4 bytes long) or IPv6 (16 bytes long). Note that +there is no <code class="docutils literal"><span class="pre">inet</span></code> constant, IP address should be input as strings</td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">int</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a></td> +<td>32-bit signed int</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">smallint</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a></td> +<td>16-bit signed int</td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">text</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a></td> +<td>UTF8 encoded string</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">time</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a>, +<a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a></td> +<td>A time (with no corresponding date value) with nanosecond precision. See +<a class="reference internal" href="#times"><span class="std std-ref">Working with times</span></a> below for details</td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">timestamp</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a>, +<a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a></td> +<td>A timestamp (date and time) with millisecond precision. See <a class="reference internal" href="#timestamps"><span class="std std-ref">Working with timestamps</span></a> +below for details</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">timeuuid</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-uuid"><code class="xref std std-token docutils literal"><span class="pre">uuid</span></code></a></td> +<td>Version 1 <a class="reference external" href="https://en.wikipedia.org/wiki/Universally_unique_identifier";>UUID</a>, generally used as a âconflict-freeâ timestamp. Also see +<a class="reference internal" href="functions.html#timeuuid-functions"><span class="std std-ref">Timeuuid functions</span></a></td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">tinyint</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a></td> +<td>8-bit signed int</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">uuid</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-uuid"><code class="xref std std-token docutils literal"><span class="pre">uuid</span></code></a></td> +<td>A <a class="reference external" href="https://en.wikipedia.org/wiki/Universally_unique_identifier";>UUID</a> (of any version)</td> +</tr> +<tr class="row-even"><td><code class="docutils literal"><span class="pre">varchar</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a></td> +<td>UTF8 encoded string</td> +</tr> +<tr class="row-odd"><td><code class="docutils literal"><span class="pre">varint</span></code></td> +<td><a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a></td> +<td>Arbitrary-precision integer</td> +</tr> +</tbody> +</table> +<div class="section" id="counters"> +<span id="id3"></span><h3>Counters<a class="headerlink" href="#counters" title="Permalink to this headline">¶</a></h3> +<p>The <code class="docutils literal"><span class="pre">counter</span></code> type is used to define <em>counter columns</em>. A counter column is a column whose value is a 64-bit signed +integer and on which 2 operations are supported: incrementing and decrementing (see the <a class="reference internal" href="dml.html#update-statement"><span class="std std-ref">UPDATE statement</span></a> for syntax). Note that the value of a counter cannot be set: a counter does not exist until first +incremented/decremented, and that first increment/decrement is made as if the prior value was 0.</p> +<p id="counter-limitations">Counters have a number of important limitations:</p> +<ul class="simple"> +<li>They cannot be used for columns part of the <code class="docutils literal"><span class="pre">PRIMARY</span> <span class="pre">KEY</span></code> of a table.</li> +<li>A table that contains a counter can only contain counters. In other words, either all the columns of a table outside +the <code class="docutils literal"><span class="pre">PRIMARY</span> <span class="pre">KEY</span></code> have the <code class="docutils literal"><span class="pre">counter</span></code> type, or none of them have it.</li> +<li>Counters do not support <span class="xref std std-ref">expiration</span>.</li> +<li>The deletion of counters is supported, but is only guaranteed to work the first time you delete a counter. In other +words, you should not re-update a counter that you have deleted (if you do, proper behavior is not guaranteed).</li> +<li>Counter updates are, by nature, not <a class="reference external" href="https://en.wikipedia.org/wiki/Idempotence";>idemptotent</a>. An important +consequence is that if a counter update fails unexpectedly (timeout or loss of connection to the coordinator node), +the client has no way to know if the update has been applied or not. In particular, replaying the update may or may +not lead to an over count.</li> +</ul> +</div> +</div> +<div class="section" id="working-with-timestamps"> +<span id="timestamps"></span><h2>Working with timestamps<a class="headerlink" href="#working-with-timestamps" title="Permalink to this headline">¶</a></h2> +<p>Values of the <code class="docutils literal"><span class="pre">timestamp</span></code> type are encoded as 64-bit signed integers representing a number of milliseconds since the +standard base time known as <a class="reference external" href="https://en.wikipedia.org/wiki/Unix_time";>the epoch</a>: January 1 1970 at 00:00:00 GMT.</p> +<p>Timestamps can be input in CQL either using their value as an <a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a>, or using a <a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a> that +represents an <a class="reference external" href="https://en.wikipedia.org/wiki/ISO_8601";>ISO 8601</a> date. For instance, all of the values below are +valid <code class="docutils literal"><span class="pre">timestamp</span></code> values for Mar 2, 2011, at 04:05:00 AM, GMT:</p> +<ul class="simple"> +<li><code class="docutils literal"><span class="pre">1299038700000</span></code></li> +<li><code class="docutils literal"><span class="pre">'2011-02-03</span> <span class="pre">04:05+0000'</span></code></li> +<li><code class="docutils literal"><span class="pre">'2011-02-03</span> <span class="pre">04:05:00+0000'</span></code></li> +<li><code class="docutils literal"><span class="pre">'2011-02-03</span> <span class="pre">04:05:00.000+0000'</span></code></li> +<li><code class="docutils literal"><span class="pre">'2011-02-03T04:05+0000'</span></code></li> +<li><code class="docutils literal"><span class="pre">'2011-02-03T04:05:00+0000'</span></code></li> +<li><code class="docutils literal"><span class="pre">'2011-02-03T04:05:00.000+0000'</span></code></li> +</ul> +<p>The <code class="docutils literal"><span class="pre">+0000</span></code> above is an RFC 822 4-digit time zone specification; <code class="docutils literal"><span class="pre">+0000</span></code> refers to GMT. US Pacific Standard Time is +<code class="docutils literal"><span class="pre">-0800</span></code>. The time zone may be omitted if desired (<code class="docutils literal"><span class="pre">'2011-02-03</span> <span class="pre">04:05:00'</span></code>), and if so, the date will be interpreted +as being in the time zone under which the coordinating Cassandra node is configured. There are however difficulties +inherent in relying on the time zone configuration being as expected, so it is recommended that the time zone always be +specified for timestamps when feasible.</p> +<p>The time of day may also be omitted (<code class="docutils literal"><span class="pre">'2011-02-03'</span></code> or <code class="docutils literal"><span class="pre">'2011-02-03+0000'</span></code>), in which case the time of day will +default to 00:00:00 in the specified or default time zone. However, if only the date part is relevant, consider using +the <a class="reference internal" href="#dates"><span class="std std-ref">date</span></a> type.</p> +</div> +<div class="section" id="working-with-dates"> +<span id="dates"></span><h2>Working with dates<a class="headerlink" href="#working-with-dates" title="Permalink to this headline">¶</a></h2> +<p>Values of the <code class="docutils literal"><span class="pre">date</span></code> type are encoded as 32-bit unsigned integers representing a number of days with âthe epochâ at +the center of the range (2^31). Epoch is January 1st, 1970</p> +<p>As for <a class="reference internal" href="#timestamps"><span class="std std-ref">timestamp</span></a>, a date can be input either as an <a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a> or using a date +<a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a>. In the later case, the format should be <code class="docutils literal"><span class="pre">yyyy-mm-dd</span></code> (so <code class="docutils literal"><span class="pre">'2011-02-03'</span></code> for instance).</p> +</div> +<div class="section" id="working-with-times"> +<span id="times"></span><h2>Working with times<a class="headerlink" href="#working-with-times" title="Permalink to this headline">¶</a></h2> +<p>Values of the <code class="docutils literal"><span class="pre">time</span></code> type are encoded as 64-bit signed integers representing the number of nanoseconds since midnight.</p> +<p>As for <a class="reference internal" href="#timestamps"><span class="std std-ref">timestamp</span></a>, a time can be input either as an <a class="reference internal" href="definitions.html#grammar-token-integer"><code class="xref std std-token docutils literal"><span class="pre">integer</span></code></a> or using a <a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a> +representing the time. In the later case, the format should be <code class="docutils literal"><span class="pre">hh:mm:ss[.fffffffff]</span></code> (where the sub-second precision +is optional and if provided, can be less than the nanosecond). So for instance, the following are valid inputs for a +time:</p> +<ul class="simple"> +<li><code class="docutils literal"><span class="pre">'08:12:54'</span></code></li> +<li><code class="docutils literal"><span class="pre">'08:12:54.123'</span></code></li> +<li><code class="docutils literal"><span class="pre">'08:12:54.123456'</span></code></li> +<li><code class="docutils literal"><span class="pre">'08:12:54.123456789'</span></code></li> +</ul> +</div> +<div class="section" id="collections"> +<span id="id4"></span><h2>Collections<a class="headerlink" href="#collections" title="Permalink to this headline">¶</a></h2> +<p>CQL supports 3 kind of collections: <a class="reference internal" href="#maps"><span class="std std-ref">Maps</span></a>, <a class="reference internal" href="#sets"><span class="std std-ref">Sets</span></a> and <a class="reference internal" href="#lists"><span class="std std-ref">Lists</span></a>. The types of those collections is defined +by:</p> +<pre> +<strong id="grammar-token-collection_type">collection_type</strong> ::= MAP '<' <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> ',' <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> '>' + | SET '<' <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> '>' + | LIST '<' <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> '>' +</pre> +<p>and their values can be inputd using collection literals:</p> +<pre> +<strong id="grammar-token-collection_literal">collection_literal</strong> ::= <a class="reference internal" href="#grammar-token-map_literal"><code class="xref docutils literal"><span class="pre">map_literal</span></code></a> | <a class="reference internal" href="#grammar-token-set_literal"><code class="xref docutils literal"><span class="pre">set_literal</span></code></a> | <a class="reference internal" href="#grammar-token-list_literal"><code class="xref docutils literal"><span class="pre">list_literal</span></code></a> +<strong id="grammar-token-map_literal">map_literal </strong> ::= '{' [ <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> ':' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> (',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> : <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a>)* ] '}' +<strong id="grammar-token-set_literal">set_literal </strong> ::= '{' [ <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> (',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a>)* ] '}' +<strong id="grammar-token-list_literal">list_literal </strong> ::= '[' [ <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> (',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a>)* ] ']' +</pre> +<p>Note however that neither <a class="reference internal" href="definitions.html#grammar-token-bind_marker"><code class="xref std std-token docutils literal"><span class="pre">bind_marker</span></code></a> nor <code class="docutils literal"><span class="pre">NULL</span></code> are supported inside collection literals.</p> +<div class="section" id="noteworthy-characteristics"> +<h3>Noteworthy characteristics<a class="headerlink" href="#noteworthy-characteristics" title="Permalink to this headline">¶</a></h3> +<p>Collections are meant for storing/denormalizing relatively small amount of data. They work well for things like âthe +phone numbers of a given userâ, âlabels applied to an emailâ, etc. But when items are expected to grow unbounded (âall +messages sent by a userâ, âevents registered by a sensorâ...), then collections are not appropriate and a specific table +(with clustering columns) should be used. Concretely, (non-frozen) collections have the following noteworthy +characteristics and limitations:</p> +<ul class="simple"> +<li>Individual collections are not indexed internally. Which means that even to access a single element of a collection, +the while collection has to be read (and reading one is not paged internally).</li> +<li>While insertion operations on sets and maps never incur a read-before-write internally, some operations on lists do. +Further, some lists operations are not idempotent by nature (see the section on <a class="reference internal" href="#lists"><span class="std std-ref">lists</span></a> below for +details), making their retry in case of timeout problematic. It is thus advised to prefer sets over lists when +possible.</li> +</ul> +<p>Please note that while some of those limitations may or may not be removed/improved upon in the future, it is a +anti-pattern to use a (single) collection to store large amounts of data.</p> +</div> +<div class="section" id="maps"> +<span id="id5"></span><h3>Maps<a class="headerlink" href="#maps" title="Permalink to this headline">¶</a></h3> +<p>A <code class="docutils literal"><span class="pre">map</span></code> is a (sorted) set of key-value pairs, where keys are unique and the map is sorted by its keys. You can define +and insert a map with:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">TABLE</span> <span class="k">users</span> <span class="p">(</span> + <span class="n">id</span> <span class="nb">text</span> <span class="k">PRIMARY</span> <span class="k">KEY</span><span class="p">,</span> + <span class="n">name</span> <span class="nb">text</span><span class="p">,</span> + <span class="n">favs</span> <span class="k">map</span><span class="o"><</span><span class="nb">text</span><span class="p">,</span> <span class="nb">text</span><span class="o">></span> <span class="c1">// A map of text keys, and text values</span> +<span class="p">);</span> + +<span class="k">INSERT</span> <span class="k">INTO</span> <span class="k">users</span> <span class="p">(</span><span class="n">id</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">favs</span><span class="p">)</span> + <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'jsmith'</span><span class="p">,</span> <span class="s1">'John Smith'</span><span class="p">,</span> <span class="p">{</span> <span class="s1">'fruit'</span> <span class="p">:</span> <span class="s1">'Apple'</span><span class="p">,</span> <span class="s1">'band'</span> <span class="p">:</span> <span class="s1">'Beatles'</span> <span class="p">});</span> + +<span class="c1">// Replace the existing map entirely.</span> +<span class="k">UPDATE</span> <span class="k">users</span> <span class="k">SET</span> <span class="n">favs</span> <span class="o">=</span> <span class="p">{</span> <span class="s1">'fruit'</span> <span class="p">:</span> <span class="s1">'Banana'</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'jsmith'</span><span class="p">;</span> +</pre></div> +</div> +<p>Further, maps support:</p> +<ul> +<li><p class="first">Updating or inserting one or more elements:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">UPDATE</span> <span class="k">users</span> <span class="k">SET</span> <span class="n">favs</span><span class="p">[</span><span class="s1">'author'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'Ed Poe'</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'jsmith'</span><span class="p">;</span> +<span class="k">UPDATE</span> <span class="k">users</span> <span class="k">SET</span> <span class="n">favs</span> <span class="o">=</span> <span class="n">favs</span> <span class="o">+</span> <span class="p">{</span> <span class="s1">'movie'</span> <span class="p">:</span> <span class="s1">'Cassablanca'</span><span class="p">,</span> <span class="s1">'band'</span> <span class="p">:</span> <span class="s1">'ZZ Top'</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'jsmith'</span><span class="p">;</span> +</pre></div> +</div> +</li> +<li><p class="first">Removing one or more element (if an element doesn’t exist, removing it is a no-op but no error is thrown):</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">DELETE</span> <span class="n">favs</span><span class="p">[</span><span class="s1">'author'</span><span class="p">]</span> <span class="k">FROM</span> <span class="k">users</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'jsmith'</span><span class="p">;</span> +<span class="k">UPDATE</span> <span class="k">users</span> <span class="k">SET</span> <span class="n">favs</span> <span class="o">=</span> <span class="n">favs</span> <span class="o">-</span> <span class="p">{</span> <span class="s1">'movie'</span><span class="p">,</span> <span class="s1">'band'</span><span class="p">}</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'jsmith'</span><span class="p">;</span> +</pre></div> +</div> +<p>Note that for removing multiple elements in a <code class="docutils literal"><span class="pre">map</span></code>, you remove from it a <code class="docutils literal"><span class="pre">set</span></code> of keys.</p> +</li> +</ul> +<p>Lastly, TTLs are allowed for both <code class="docutils literal"><span class="pre">INSERT</span></code> and <code class="docutils literal"><span class="pre">UPDATE</span></code>, but in both case the TTL set only apply to the newly +inserted/updated elements. In other words:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">UPDATE</span> <span class="k">users</span> <span class="k">USING</span> <span class="k">TTL</span> <span class="mf">10</span> <span class="k">SET</span> <span class="n">favs</span><span class="p">[</span><span class="s1">'color'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'green'</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'jsmith'</span><span class="p">;</span> +</pre></div> +</div> +<p>will only apply the TTL to the <code class="docutils literal"><span class="pre">{</span> <span class="pre">'color'</span> <span class="pre">:</span> <span class="pre">'green'</span> <span class="pre">}</span></code> record, the rest of the map remaining unaffected.</p> +</div> +<div class="section" id="sets"> +<span id="id6"></span><h3>Sets<a class="headerlink" href="#sets" title="Permalink to this headline">¶</a></h3> +<p>A <code class="docutils literal"><span class="pre">set</span></code> is a (sorted) collection of unique values. You can define and insert a map with:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">TABLE</span> <span class="n">images</span> <span class="p">(</span> + <span class="n">name</span> <span class="nb">text</span> <span class="k">PRIMARY</span> <span class="k">KEY</span><span class="p">,</span> + <span class="n">owner</span> <span class="nb">text</span><span class="p">,</span> + <span class="n">tags</span> <span class="k">set</span><span class="o"><</span><span class="nb">text</span><span class="o">></span> <span class="c1">// A set of text values</span> +<span class="p">);</span> + +<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">images</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">owner</span><span class="p">,</span> <span class="n">tags</span><span class="p">)</span> + <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'cat.jpg'</span><span class="p">,</span> <span class="s1">'jsmith'</span><span class="p">,</span> <span class="p">{</span> <span class="s1">'pet'</span><span class="p">,</span> <span class="s1">'cute'</span> <span class="p">});</span> + +<span class="c1">// Replace the existing set entirely</span> +<span class="k">UPDATE</span> <span class="n">images</span> <span class="k">SET</span> <span class="n">tags</span> <span class="o">=</span> <span class="p">{</span> <span class="s1">'kitten'</span><span class="p">,</span> <span class="s1">'cat'</span><span class="p">,</span> <span class="s1">'lol'</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'jsmith'</span><span class="p">;</span> +</pre></div> +</div> +<p>Further, sets support:</p> +<ul> +<li><p class="first">Adding one or multiple elements (as this is a set, inserting an already existing element is a no-op):</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">UPDATE</span> <span class="n">images</span> <span class="k">SET</span> <span class="n">tags</span> <span class="o">=</span> <span class="n">tags</span> <span class="o">+</span> <span class="p">{</span> <span class="s1">'gray'</span><span class="p">,</span> <span class="s1">'cuddly'</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">'cat.jpg'</span><span class="p">;</span> +</pre></div> +</div> +</li> +<li><p class="first">Removing one or multiple elements (if an element doesn’t exist, removing it is a no-op but no error is thrown):</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">UPDATE</span> <span class="n">images</span> <span class="k">SET</span> <span class="n">tags</span> <span class="o">=</span> <span class="n">tags</span> <span class="o">-</span> <span class="p">{</span> <span class="s1">'cat'</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">'cat.jpg'</span><span class="p">;</span> +</pre></div> +</div> +</li> +</ul> +<p>Lastly, as for <a class="reference internal" href="#maps"><span class="std std-ref">maps</span></a>, TTLs if used only apply to the newly inserted values.</p> +</div> +<div class="section" id="lists"> +<span id="id7"></span><h3>Lists<a class="headerlink" href="#lists" title="Permalink to this headline">¶</a></h3> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">As mentioned above and further discussed at the end of this section, lists have limitations and specific +performance considerations that you should take into account before using them. In general, if you can use a +<a class="reference internal" href="#sets"><span class="std std-ref">set</span></a> instead of list, always prefer a set.</p> +</div> +<p>A <code class="docutils literal"><span class="pre">list</span></code> is a (sorted) collection of non-unique values where elements are ordered by there position in the list. You +can define and insert a list with:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">TABLE</span> <span class="n">plays</span> <span class="p">(</span> + <span class="n">id</span> <span class="nb">text</span> <span class="k">PRIMARY</span> <span class="k">KEY</span><span class="p">,</span> + <span class="n">game</span> <span class="nb">text</span><span class="p">,</span> + <span class="n">players</span> <span class="nb">int</span><span class="p">,</span> + <span class="n">scores</span> <span class="k">list</span><span class="o"><</span><span class="nb">int</span><span class="o">></span> <span class="c1">// A list of integers</span> +<span class="p">)</span> + +<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">plays</span> <span class="p">(</span><span class="n">id</span><span class="p">,</span> <span class="n">game</span><span class="p">,</span> <span class="n">players</span><span class="p">,</span> <span class="n">scores</span><span class="p">)</span> + <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'123-afde'</span><span class="p">,</span> <span class="s1">'quake'</span><span class="p">,</span> <span class="mf">3</span><span class="p">,</span> <span class="p">[</span><span class="mf">17</span><span class="p">,</span> <span class="mf">4</span><span class="p">,</span> <span class="mf">2</span><span class="p">]);</span> + +<span class="c1">// Replace the existing list entirely</span> +<span class="k">UPDATE</span> <span class="n">plays</span> <span class="k">SET</span> <span class="n">scores</span> <span class="o">=</span> <span class="p">[</span> <span class="mf">3</span><span class="p">,</span> <span class="mf">9</span><span class="p">,</span> <span class="mf">4</span><span class="p">]</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'123-afde'</span><span class="p">;</span> +</pre></div> +</div> +<p>Further, lists support:</p> +<ul> +<li><p class="first">Appending and prepending values to a list:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">UPDATE</span> <span class="n">plays</span> <span class="k">SET</span> <span class="n">players</span> <span class="o">=</span> <span class="mf">5</span><span class="p">,</span> <span class="n">scores</span> <span class="o">=</span> <span class="n">scores</span> <span class="o">+</span> <span class="p">[</span> <span class="mf">14</span><span class="p">,</span> <span class="mf">21</span> <span class="p">]</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'123-afde'</span><span class="p">;</span> +<span class="k">UPDATE</span> <span class="n">plays</span> <span class="k">SET</span> <span class="n">players</span> <span class="o">=</span> <span class="mf">6</span><span class="p">,</span> <span class="n">scores</span> <span class="o">=</span> <span class="p">[</span> <span class="mf">3</span> <span class="p">]</span> <span class="o">+</span> <span class="n">scores</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'123-afde'</span><span class="p">;</span> +</pre></div> +</div> +</li> +<li><p class="first">Setting the value at a particular position in the list. This imply that the list has a pre-existing element for that +position or an error will be thrown that the list is too small:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">UPDATE</span> <span class="n">plays</span> <span class="k">SET</span> <span class="n">scores</span><span class="p">[</span><span class="mf">1</span><span class="p">]</span> <span class="o">=</span> <span class="mf">7</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'123-afde'</span><span class="p">;</span> +</pre></div> +</div> +</li> +<li><p class="first">Removing an element by its position in the list. This imply that the list has a pre-existing element for that position +or an error will be thrown that the list is too small. Further, as the operation removes an element from the list, the +list size will be diminished by 1, shifting the position of all the elements following the one deleted:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">DELETE</span> <span class="n">scores</span><span class="p">[</span><span class="mf">1</span><span class="p">]</span> <span class="k">FROM</span> <span class="n">plays</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'123-afde'</span><span class="p">;</span> +</pre></div> +</div> +</li> +<li><p class="first">Deleting <em>all</em> the occurrences of particular values in the list (if a particular element doesn’t occur at all in the +list, it is simply ignored and no error is thrown):</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">UPDATE</span> <span class="n">plays</span> <span class="k">SET</span> <span class="n">scores</span> <span class="o">=</span> <span class="n">scores</span> <span class="o">-</span> <span class="p">[</span> <span class="mf">12</span><span class="p">,</span> <span class="mf">21</span> <span class="p">]</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">'123-afde'</span><span class="p">;</span> +</pre></div> +</div> +</li> +</ul> +<div class="admonition warning"> +<p class="first admonition-title">Warning</p> +<p class="last">The append and prepend operations are not idempotent by nature. So in particular, if one of these operation +timeout, then retrying the operation is not safe and it may (or may not) lead to appending/prepending the value +twice.</p> +</div> +<div class="admonition warning"> +<p class="first admonition-title">Warning</p> +<p class="last">Setting and removing an element by position and removing occurences of particular values incur an internal +<em>read-before-write</em>. They will thus run more slowly and take more ressources than usual updates (with the exclusion +of conditional write that have their own cost).</p> +</div> +<p>Lastly, as for <a class="reference internal" href="#maps"><span class="std std-ref">maps</span></a>, TTLs when used only apply to the newly inserted values.</p> +</div> +</div> +<div class="section" id="user-defined-types"> +<span id="udts"></span><h2>User-Defined Types<a class="headerlink" href="#user-defined-types" title="Permalink to this headline">¶</a></h2> +<p>CQL support the definition of user-defined types (UDT for short). Such a type can be created, modified and removed using +the <a class="reference internal" href="#grammar-token-create_type_statement"><code class="xref std std-token docutils literal"><span class="pre">create_type_statement</span></code></a>, <a class="reference internal" href="#grammar-token-alter_type_statement"><code class="xref std std-token docutils literal"><span class="pre">alter_type_statement</span></code></a> and <a class="reference internal" href="#grammar-token-drop_type_statement"><code class="xref std std-token docutils literal"><span class="pre">drop_type_statement</span></code></a> described below. But +once created, a UDT is simply referred to by its name:</p> +<pre> +<strong id="grammar-token-user_defined_type">user_defined_type</strong> ::= <a class="reference internal" href="#grammar-token-udt_name"><code class="xref docutils literal"><span class="pre">udt_name</span></code></a> +<strong id="grammar-token-udt_name">udt_name </strong> ::= [ <a class="reference internal" href="ddl.html#grammar-token-keyspace_name"><code class="xref docutils literal"><span class="pre">keyspace_name</span></code></a> '.' ] <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> +</pre> +<div class="section" id="creating-a-udt"> +<h3>Creating a UDT<a class="headerlink" href="#creating-a-udt" title="Permalink to this headline">¶</a></h3> +<p>Creating a new user-defined type is done using a <code class="docutils literal"><span class="pre">CREATE</span> <span class="pre">TYPE</span></code> statement defined by:</p> +<pre> +<strong id="grammar-token-create_type_statement">create_type_statement</strong> ::= CREATE TYPE [ IF NOT EXISTS ] <a class="reference internal" href="#grammar-token-udt_name"><code class="xref docutils literal"><span class="pre">udt_name</span></code></a> + '(' <a class="reference internal" href="#grammar-token-field_definition"><code class="xref docutils literal"><span class="pre">field_definition</span></code></a> ( ',' <a class="reference internal" href="#grammar-token-field_definition"><code class="xref docutils literal"><span class="pre">field_definition</span></code></a> )* ')' +<strong id="grammar-token-field_definition">field_definition </strong> ::= <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> +</pre> +<p>A UDT has a name (used to declared columns of that type) and is a set of named and typed fields. Fields name can be any +type, including collections or other UDT. For instance:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">TYPE</span> <span class="n">phone</span> <span class="p">(</span> + <span class="n">country_code</span> <span class="nb">int</span><span class="p">,</span> + <span class="n">number</span> <span class="nb">text</span><span class="p">,</span> +<span class="p">)</span> + +<span class="k">CREATE</span> <span class="k">TYPE</span> <span class="n">address</span> <span class="p">(</span> + <span class="n">street</span> <span class="nb">text</span><span class="p">,</span> + <span class="n">city</span> <span class="nb">text</span><span class="p">,</span> + <span class="n">zip</span> <span class="nb">int</span><span class="p">,</span> + <span class="n">phones</span> <span class="k">map</span><span class="o"><</span><span class="nb">text</span><span class="p">,</span> <span class="n">phone</span><span class="o">></span> +<span class="p">)</span> + +<span class="k">CREATE</span> <span class="k">TABLE</span> <span class="k">user</span> <span class="p">(</span> + <span class="n">name</span> <span class="nb">text</span> <span class="k">PRIMARY</span> <span class="k">KEY</span><span class="p">,</span> + <span class="n">addresses</span> <span class="k">map</span><span class="o"><</span><span class="nb">text</span><span class="p">,</span> <span class="k">frozen</span><span class="o"><</span><span class="n">address</span><span class="o">>></span> +<span class="p">)</span> +</pre></div> +</div> +<p>Note that:</p> +<ul class="simple"> +<li>Attempting to create an already existing type will result in an error unless the <code class="docutils literal"><span class="pre">IF</span> <span class="pre">NOT</span> <span class="pre">EXISTS</span></code> option is used. If +it is used, the statement will be a no-op if the type already exists.</li> +<li>A type is intrinsically bound to the keyspace in which it is created, and can only be used in that keyspace. At +creation, if the type name is prefixed by a keyspace name, it is created in that keyspace. Otherwise, it is created in +the current keyspace.</li> +<li>As of Cassandra 3.10, UDT have to be frozen in most cases, hence the <code class="docutils literal"><span class="pre">frozen<address></span></code> in the table definition +above. Please see the section on <span class="xref std std-ref">frozen</span> for more details.</li> +</ul> +</div> +<div class="section" id="udt-literals"> +<h3>UDT literals<a class="headerlink" href="#udt-literals" title="Permalink to this headline">¶</a></h3> +<p>Once a used-defined type has been created, value can be input using a UDT literal:</p> +<pre> +<strong id="grammar-token-udt_literal">udt_literal</strong> ::= '{' <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> ':' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> ( ',' <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> ':' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> )* '}' +</pre> +<p>In other words, a UDT literal is like a <a class="reference internal" href="#maps"><span class="std std-ref">map</span></a> literal but its keys are the names of the fields of the type. +For instance, one could insert into the table define in the previous section using:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">INSERT</span> <span class="k">INTO</span> <span class="k">user</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">addresses</span><span class="p">)</span> + <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'z3 Pr3z1den7'</span><span class="p">,</span> <span class="p">{</span> + <span class="s1">'home'</span> <span class="p">:</span> <span class="p">{</span> + <span class="n">street</span><span class="p">:</span> <span class="s1">'1600 Pennsylvania Ave NW'</span><span class="p">,</span> + <span class="n">city</span><span class="p">:</span> <span class="s1">'Washington'</span><span class="p">,</span> + <span class="n">zip</span><span class="p">:</span> <span class="s1">'20500'</span><span class="p">,</span> + <span class="n">phones</span><span class="p">:</span> <span class="p">{</span> <span class="s1">'cell'</span> <span class="p">:</span> <span class="p">{</span> <span class="n">country_code</span><span class="p">:</span> <span class="mf">1</span><span class="p">,</span> <span class="n">number</span><span class="p">:</span> <span class="s1">'202 456-1111'</span> <span class="p">},</span> + <span class="s1">'landline'</span> <span class="p">:</span> <span class="p">{</span> <span class="n">country_code</span><span class="p">:</span> <span class="mf">1</span><span class="p">,</span> <span class="n">number</span><span class="p">:</span> <span class="s1">'...'</span> <span class="p">}</span> <span class="p">}</span> + <span class="p">}</span> + <span class="s1">'work'</span> <span class="p">:</span> <span class="p">{</span> + <span class="n">street</span><span class="p">:</span> <span class="s1">'1600 Pennsylvania Ave NW'</span><span class="p">,</span> + <span class="n">city</span><span class="p">:</span> <span class="s1">'Washington'</span><span class="p">,</span> + <span class="n">zip</span><span class="p">:</span> <span class="s1">'20500'</span><span class="p">,</span> + <span class="n">phones</span><span class="p">:</span> <span class="p">{</span> <span class="s1">'fax'</span> <span class="p">:</span> <span class="p">{</span> <span class="n">country_code</span><span class="p">:</span> <span class="mf">1</span><span class="p">,</span> <span class="n">number</span><span class="p">:</span> <span class="s1">'...'</span> <span class="p">}</span> <span class="p">}</span> + <span class="p">}</span> + <span class="p">})</span> +</pre></div> +</div> +<p>To be valid, a UDT literal should only include fields defined by the type it is a literal of, but it can omit some field +(in which case those will be <code class="docutils literal"><span class="pre">null</span></code>).</p> +</div> +<div class="section" id="altering-a-udt"> +<h3>Altering a UDT<a class="headerlink" href="#altering-a-udt" title="Permalink to this headline">¶</a></h3> +<p>An existing user-defined type can be modified using an <code class="docutils literal"><span class="pre">ALTER</span> <span class="pre">TYPE</span></code> statement:</p> +<pre> +<strong id="grammar-token-alter_type_statement">alter_type_statement </strong> ::= ALTER TYPE <a class="reference internal" href="#grammar-token-udt_name"><code class="xref docutils literal"><span class="pre">udt_name</span></code></a> <a class="reference internal" href="#grammar-token-alter_type_modification"><code class="xref docutils literal"><span class="pre">alter_type_modification</span></code></a> +<strong id="grammar-token-alter_type_modification">alter_type_modification</strong> ::= ALTER <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> TYPE <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> + | ADD <a class="reference internal" href="#grammar-token-field_definition"><code class="xref docutils literal"><span class="pre">field_definition</span></code></a> + | RENAME <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> TO <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> ( <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> TO <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal"><span class="pre">identifier</span></code></a> )* +</pre> +<p>You can:</p> +<ul class="simple"> +<li>modify the type of particular field (<code class="docutils literal"><span class="pre">ALTER</span> <span class="pre">TYPE</span> <span class="pre">address</span> <span class="pre">ALTER</span> <span class="pre">zip</span> <span class="pre">TYPE</span> <span class="pre">bigint</span></code>). The restrictions for such change +are the same than when <a class="reference internal" href="ddl.html#alter-table-statement"><span class="std std-ref">altering the type of column</span></a>.</li> +<li>add a new field to the type (<code class="docutils literal"><span class="pre">ALTER</span> <span class="pre">TYPE</span> <span class="pre">address</span> <span class="pre">ADD</span> <span class="pre">country</span> <span class="pre">text</span></code>). That new field will be <code class="docutils literal"><span class="pre">null</span></code> for any values +of the type created before the addition.</li> +<li>rename the fields of the type (<code class="docutils literal"><span class="pre">ALTER</span> <span class="pre">TYPE</span> <span class="pre">address</span> <span class="pre">RENAME</span> <span class="pre">zip</span> <span class="pre">TO</span> <span class="pre">zipcode</span></code>).</li> +</ul> +</div> +<div class="section" id="dropping-a-udt"> +<h3>Dropping a UDT<a class="headerlink" href="#dropping-a-udt" title="Permalink to this headline">¶</a></h3> +<p>You can drop an existing user-defined type using a <code class="docutils literal"><span class="pre">DROP</span> <span class="pre">TYPE</span></code> statement:</p> +<pre> +<strong id="grammar-token-drop_type_statement">drop_type_statement</strong> ::= DROP TYPE [ IF EXISTS ] <a class="reference internal" href="#grammar-token-udt_name"><code class="xref docutils literal"><span class="pre">udt_name</span></code></a> +</pre> +<p>Dropping a type results in the immediate, irreversible removal of that type. However, attempting to drop a type that is +still in use by another type, table or function will result in an error.</p> +<p>If the type dropped does not exist, an error will be returned unless <code class="docutils literal"><span class="pre">IF</span> <span class="pre">EXISTS</span></code> is used, in which case the operation +is a no-op.</p> +</div> +</div> +<div class="section" id="tuples"> +<span id="id8"></span><h2>Tuples<a class="headerlink" href="#tuples" title="Permalink to this headline">¶</a></h2> +<p>CQL also support tuples and tuple types (where the elements can be of different types). Functionally, tuples can be +though as anonymous UDT with anonymous fields. Tuple types and tuple literals are defined by:</p> +<pre> +<strong id="grammar-token-tuple_type">tuple_type </strong> ::= TUPLE '<' <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> ( ',' <a class="reference internal" href="#grammar-token-cql_type"><code class="xref docutils literal"><span class="pre">cql_type</span></code></a> )* '>' +<strong id="grammar-token-tuple_literal">tuple_literal</strong> ::= '(' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> ( ',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal"><span class="pre">term</span></code></a> )* ')' +</pre> +<p>and can be used thusly:</p> +<div class="highlight-cql"><div class="highlight"><pre><span></span><span class="k">CREATE</span> <span class="k">TABLE</span> <span class="n">durations</span> <span class="p">(</span> + <span class="n">event</span> <span class="nb">text</span><span class="p">,</span> + <span class="n">duration</span> <span class="k">tuple</span><span class="o"><</span><span class="nb">int</span><span class="p">,</span> <span class="nb">text</span><span class="o">></span><span class="p">,</span> +<span class="p">)</span> + +<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">durations</span> <span class="p">(</span><span class="n">event</span><span class="p">,</span> <span class="n">duration</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">'ev1'</span><span class="p">,</span> <span class="p">(</span><span class="mf">3</span><span class="p">,</span> <span class="s1">'hours'</span><span class="p">));</span> +</pre></div> +</div> +<p>Unlike other “composed” types (collections and UDT), a tuple is always <span class="xref std std-ref">frozen</span> (without the need of the +<cite>frozen</cite> keyword) and it is not possible to update only some elements of a tuple (without updating the whole tuple). +Also, a tuple literal should always have the same number of value than declared in the type it is a tuple of (some of +those values can be null but they need to be explicitly declared as so).</p> +</div> +<div class="section" id="custom-types"> +<span id="id9"></span><h2>Custom Types<a class="headerlink" href="#custom-types" title="Permalink to this headline">¶</a></h2> +<div class="admonition note"> +<p class="first admonition-title">Note</p> +<p class="last">Custom types exists mostly for backward compatiliby purposes and their usage is discouraged. Their usage is +complex, not user friendly and the other provided types, particularly <a class="reference internal" href="#udts"><span class="std std-ref">user-defined types</span></a>, should almost +always be enough.</p> +</div> +<p>A custom type is defined by:</p> +<pre> +<strong id="grammar-token-custom_type">custom_type</strong> ::= <a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref docutils literal"><span class="pre">string</span></code></a> +</pre> +<p>A custom type is a <a class="reference internal" href="definitions.html#grammar-token-string"><code class="xref std std-token docutils literal"><span class="pre">string</span></code></a> that contains the name of Java class that extends the server side <code class="docutils literal"><span class="pre">AbstractType</span></code> +class and that can be loaded by Cassandra (it should thus be in the <code class="docutils literal"><span class="pre">CLASSPATH</span></code> of every node running Cassandra). That +class will define what values are valid for the type and how the time sorts when used for a clustering column. For any +other purpose, a value of a custom type is the same than that of a <code class="docutils literal"><span class="pre">blob</span></code>, and can in particular be input using the +<a class="reference internal" href="definitions.html#grammar-token-blob"><code class="xref std std-token docutils literal"><span class="pre">blob</span></code></a> literal syntax.</p> +</div> +</div> + + + + + <div class="doc-prev-next-links" role="navigation" aria-label="footer navigation"> + + <a href="ddl.html" class="btn btn-default pull-right " role="button" title="Data Definition" accesskey="n">Next <span class="glyphicon glyphicon-circle-arrow-right" aria-hidden="true"></span></a> + + + <a href="definitions.html" class="btn btn-default" role="button" title="Definitions" accesskey="p"><span class="glyphicon glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a> + + </div> + + </div> + </div> + </div> + <div class="col-md-2"> + </div> + </div> +</div> \ No newline at end of file
Added: cassandra/site/src/doc/3.10/data_modeling/index.html URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/data_modeling/index.html?rev=1757419&view=auto ============================================================================== --- cassandra/site/src/doc/3.10/data_modeling/index.html (added) +++ cassandra/site/src/doc/3.10/data_modeling/index.html Tue Aug 23 19:25:17 2016 @@ -0,0 +1,106 @@ +--- +layout: docpage + +title: "Documentation" + +is_homepage: false +is_sphinx_doc: true + +doc-title: "Data Modeling" +doc-header-links: ' + <link rel="top" title="Apache Cassandra Documentation v3.10" href="../index.html"/> + <link rel="next" title="The Cassandra Query Language (CQL)" href="../cql/index.html"/> + <link rel="prev" title="Guarantees" href="../architecture/guarantees.html"/> +' +doc-search-path: "../search.html" + +extra-footer: ' +<script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: "", + VERSION: "", + COLLAPSE_INDEX: false, + FILE_SUFFIX: ".html", + HAS_SOURCE: false, + SOURCELINK_SUFFIX: "" + }; +</script> +' + +--- +<div class="container-fluid"> + <div class="row"> + <div class="col-md-2"> + <div class="doc-navigation"> + <div class="doc-menu" role="navigation"> + <div class="navbar-header"> + <button type="button" class="pull-left navbar-toggle" data-toggle="collapse" data-target=".sidebar-navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + </div> + <div class="navbar-collapse collapse sidebar-navbar-collapse"> + <form id="doc-search-form" class="navbar-form" action="../search.html" method="get" role="search"> + <div class="form-group"> + <input type="text" size="30" class="form-control input-sm" name="q" placeholder="Search docs"> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </div> + </form> + + + + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../getting_started/index.html">Getting Started</a></li> +<li class="toctree-l1"><a class="reference internal" href="../architecture/index.html">Architecture</a></li> +<li class="toctree-l1 current"><a class="current reference internal" href="#">Data Modeling</a></li> +<li class="toctree-l1"><a class="reference internal" href="../cql/index.html">The Cassandra Query Language (CQL)</a></li> +<li class="toctree-l1"><a class="reference internal" href="../configuration/index.html">Configuring Cassandra</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operating/index.html">Operating Cassandra</a></li> +<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Cassandra Tools</a></li> +<li class="toctree-l1"><a class="reference internal" href="../troubleshooting/index.html">Troubleshooting</a></li> +<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Cassandra Development</a></li> +<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">Frequently Asked Questions</a></li> +<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs and Contributing</a></li> +<li class="toctree-l1"><a class="reference internal" href="../contactus.html">Contact us</a></li> +</ul> + + + + </div><!--/.nav-collapse --> + </div> + </div> + </div> + <div class="col-md-8"> + <div class="content doc-content"> + <div class="container"> + + <div class="section" id="data-modeling"> +<h1>Data Modeling<a class="headerlink" href="#data-modeling" title="Permalink to this headline">¶</a></h1> +<div class="admonition-todo admonition" id="index-0"> +<p class="first admonition-title">Todo</p> +<p class="last">TODO</p> +</div> +</div> + + + + + <div class="doc-prev-next-links" role="navigation" aria-label="footer navigation"> + + <a href="../cql/index.html" class="btn btn-default pull-right " role="button" title="The Cassandra Query Language (CQL)" accesskey="n">Next <span class="glyphicon glyphicon-circle-arrow-right" aria-hidden="true"></span></a> + + + <a href="../architecture/guarantees.html" class="btn btn-default" role="button" title="Guarantees" accesskey="p"><span class="glyphicon glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a> + + </div> + + </div> + </div> + </div> + <div class="col-md-2"> + </div> + </div> +</div> \ No newline at end of file Added: cassandra/site/src/doc/3.10/development/code_style.html URL: http://svn.apache.org/viewvc/cassandra/site/src/doc/3.10/development/code_style.html?rev=1757419&view=auto ============================================================================== --- cassandra/site/src/doc/3.10/development/code_style.html (added) +++ cassandra/site/src/doc/3.10/development/code_style.html Tue Aug 23 19:25:17 2016 @@ -0,0 +1,210 @@ +--- +layout: docpage + +title: "Documentation" + +is_homepage: false +is_sphinx_doc: true + +doc-parent: "Cassandra Development" + +doc-title: "Code Style" +doc-header-links: ' + <link rel="top" title="Apache Cassandra Documentation v3.10" href="../index.html"/> + <link rel="up" title="Cassandra Development" href="index.html"/> + <link rel="next" title="Review Checklist" href="how_to_review.html"/> + <link rel="prev" title="Contributing Code Changes" href="patches.html"/> +' +doc-search-path: "../search.html" + +extra-footer: ' +<script type="text/javascript"> + var DOCUMENTATION_OPTIONS = { + URL_ROOT: "", + VERSION: "", + COLLAPSE_INDEX: false, + FILE_SUFFIX: ".html", + HAS_SOURCE: false, + SOURCELINK_SUFFIX: "" + }; +</script> +' + +--- +<div class="container-fluid"> + <div class="row"> + <div class="col-md-2"> + <div class="doc-navigation"> + <div class="doc-menu" role="navigation"> + <div class="navbar-header"> + <button type="button" class="pull-left navbar-toggle" data-toggle="collapse" data-target=".sidebar-navbar-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + </div> + <div class="navbar-collapse collapse sidebar-navbar-collapse"> + <form id="doc-search-form" class="navbar-form" action="../search.html" method="get" role="search"> + <div class="form-group"> + <input type="text" size="30" class="form-control input-sm" name="q" placeholder="Search docs"> + <input type="hidden" name="check_keywords" value="yes" /> + <input type="hidden" name="area" value="default" /> + </div> + </form> + + + + <ul class="current"> +<li class="toctree-l1"><a class="reference internal" href="../getting_started/index.html">Getting Started</a></li> +<li class="toctree-l1"><a class="reference internal" href="../architecture/index.html">Architecture</a></li> +<li class="toctree-l1"><a class="reference internal" href="../data_modeling/index.html">Data Modeling</a></li> +<li class="toctree-l1"><a class="reference internal" href="../cql/index.html">The Cassandra Query Language (CQL)</a></li> +<li class="toctree-l1"><a class="reference internal" href="../configuration/index.html">Configuring Cassandra</a></li> +<li class="toctree-l1"><a class="reference internal" href="../operating/index.html">Operating Cassandra</a></li> +<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Cassandra Tools</a></li> +<li class="toctree-l1"><a class="reference internal" href="../troubleshooting/index.html">Troubleshooting</a></li> +<li class="toctree-l1 current"><a class="reference internal" href="index.html">Cassandra Development</a><ul class="current"> +<li class="toctree-l2"><a class="reference internal" href="ide.html">Building and IDE Integration</a></li> +<li class="toctree-l2"><a class="reference internal" href="testing.html">Testing</a></li> +<li class="toctree-l2"><a class="reference internal" href="patches.html">Contributing Code Changes</a></li> +<li class="toctree-l2 current"><a class="current reference internal" href="#">Code Style</a><ul> +<li class="toctree-l3"><a class="reference internal" href="#general-code-conventions">General Code Conventions</a></li> +<li class="toctree-l3"><a class="reference internal" href="#exception-handling">Exception handling</a></li> +<li class="toctree-l3"><a class="reference internal" href="#boilerplate">Boilerplate</a></li> +<li class="toctree-l3"><a class="reference internal" href="#multiline-statements">Multiline statements</a></li> +<li class="toctree-l3"><a class="reference internal" href="#whitespace">Whitespace</a></li> +<li class="toctree-l3"><a class="reference internal" href="#imports">Imports</a></li> +<li class="toctree-l3"><a class="reference internal" href="#format-files-for-ides">Format files for IDEs</a></li> +</ul> +</li> +<li class="toctree-l2"><a class="reference internal" href="how_to_review.html">Review Checklist</a></li> +<li class="toctree-l2"><a class="reference internal" href="how_to_commit.html">How-to Commit</a></li> +</ul> +</li> +<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">Frequently Asked Questions</a></li> +<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs and Contributing</a></li> +<li class="toctree-l1"><a class="reference internal" href="../contactus.html">Contact us</a></li> +</ul> + + + + </div><!--/.nav-collapse --> + </div> + </div> + </div> + <div class="col-md-8"> + <div class="content doc-content"> + <div class="container"> + + <div class="section" id="code-style"> +<h1>Code Style<a class="headerlink" href="#code-style" title="Permalink to this headline">¶</a></h1> +<div class="section" id="general-code-conventions"> +<h2>General Code Conventions<a class="headerlink" href="#general-code-conventions" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div><ul class="simple"> +<li>The Cassandra project follows <a class="reference external" href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html";>Sun’s Java coding conventions</a> with an important exception: <code class="docutils literal"><span class="pre">{</span></code> and <code class="docutils literal"><span class="pre">}</span></code> are always placed on a new line</li> +</ul> +</div></blockquote> +</div> +<div class="section" id="exception-handling"> +<h2>Exception handling<a class="headerlink" href="#exception-handling" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div><ul class="simple"> +<li>Never ever write <code class="docutils literal"><span class="pre">catch</span> <span class="pre">(...)</span> <span class="pre">{}</span></code> or <code class="docutils literal"><span class="pre">catch</span> <span class="pre">(...)</span> <span class="pre">{</span> <span class="pre">logger.error()</span> <span class="pre">}</span></code> merely to satisfy Java’s compile-time exception checking. Always propagate the exception up or throw <code class="docutils literal"><span class="pre">RuntimeException</span></code> (or, if it “can’t happen,” <code class="docutils literal"><span class="pre">AssertionError</span></code>). This makes the exceptions visible to automated tests.</li> +<li>Avoid propagating up checked exceptions that no caller handles. Rethrow as <code class="docutils literal"><span class="pre">RuntimeException</span></code> (or <code class="docutils literal"><span class="pre">IOError</span></code>, if that is more applicable).</li> +<li>Similarly, logger.warn() is often a cop-out: is this an error or not? If it is don’t hide it behind a warn; if it isn’t, no need for the warning.</li> +<li>If you genuinely know an exception indicates an expected condition, it’s okay to ignore it BUT this must be explicitly explained in a comment.</li> +</ul> +</div></blockquote> +</div> +<div class="section" id="boilerplate"> +<h2>Boilerplate<a class="headerlink" href="#boilerplate" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div><ul class="simple"> +<li>Avoid redundant <code class="docutils literal"><span class="pre">@Override</span></code> annotations when implementing abstract or interface methods.</li> +<li>Do not implement equals or hashcode methods unless they are actually needed.</li> +<li>Prefer public final fields to private fields with getters. (But prefer encapsulating behavior in “real” methods to either.)</li> +<li>Prefer requiring initialization in the constructor to setters.</li> +<li>Avoid redundant <code class="docutils literal"><span class="pre">this</span></code> references to member fields or methods.</li> +<li>Do not extract interfaces (or abstract classes) unless you actually need multiple implementations of it.</li> +<li>Always include braces for nested levels of conditionals and loops. Only avoid braces for single level.</li> +</ul> +</div></blockquote> +</div> +<div class="section" id="multiline-statements"> +<h2>Multiline statements<a class="headerlink" href="#multiline-statements" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div><ul class="simple"> +<li>Try to keep lines under 120 characters, but use good judgement – it’s better to exceed 120 by a little, than split a line that has no natural splitting points.</li> +<li>When splitting inside a method call, use one line per parameter and align them, like this:</li> +</ul> +<div class="highlight-none"><div class="highlight"><pre><span></span>SSTableWriter writer = new SSTableWriter(cfs.getTempSSTablePath(), + columnFamilies.size(), + StorageService.getPartitioner()); +</pre></div> +</div> +<ul class="simple"> +<li>When splitting a ternary, use one line per clause, carry the operator, and align like this:</li> +</ul> +<div class="highlight-none"><div class="highlight"><pre><span></span>var = bar == null + ? doFoo() + : doBar(); +</pre></div> +</div> +</div></blockquote> +</div> +<div class="section" id="whitespace"> +<h2>Whitespace<a class="headerlink" href="#whitespace" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div><ul class="simple"> +<li>Please make sure to use 4 spaces instead of the tab character for all your indentation.</li> +<li>Many lines in many files have a bunch of trailing whitespace... Please either clean these up in a separate patch, or leave them alone, so that reviewers now and anyone reading code history later doesn’t have to pay attention to whitespace diffs.</li> +</ul> +</div></blockquote> +</div> +<div class="section" id="imports"> +<h2>Imports<a class="headerlink" href="#imports" title="Permalink to this headline">¶</a></h2> +<p>Please observe the following order for your imports:</p> +<div class="highlight-none"><div class="highlight"><pre><span></span>java +[blank line] +com.google.common +org.apache.commons +org.junit +org.slf4j +[blank line] +everything else alphabetically +</pre></div> +</div> +</div> +<div class="section" id="format-files-for-ides"> +<h2>Format files for IDEs<a class="headerlink" href="#format-files-for-ides" title="Permalink to this headline">¶</a></h2> +<blockquote> +<div><ul class="simple"> +<li>IntelliJ: <a class="reference external" href="https://wiki.apache.org/cassandra/CodeStyle?action=AttachFile&do=view&target=intellij-codestyle.jar";>intellij-codestyle.jar</a></li> +<li>IntelliJ 13: <a class="reference external" href="https://gist.github.com/jdsumsion/9ab750a05c2a567c6afc";>gist for IntelliJ 13</a> (this is a work in progress, still working on javadoc, ternary style, line continuations, etc)</li> +<li>Eclipse (<a class="reference external" href="https://github.com/tjake/cassandra-style-eclipse";>https://github.com/tjake/cassandra-style-eclipse</a>)</li> +</ul> +</div></blockquote> +</div> +</div> + + + + + <div class="doc-prev-next-links" role="navigation" aria-label="footer navigation"> + + <a href="how_to_review.html" class="btn btn-default pull-right " role="button" title="Review Checklist" accesskey="n">Next <span class="glyphicon glyphicon-circle-arrow-right" aria-hidden="true"></span></a> + + + <a href="patches.html" class="btn btn-default" role="button" title="Contributing Code Changes" accesskey="p"><span class="glyphicon glyphicon-circle-arrow-left" aria-hidden="true"></span> Previous</a> + + </div> + + </div> + </div> + </div> + <div class="col-md-2"> + </div> + </div> +</div> \ No newline at end of file
