You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by ty...@apache.org on 2016/08/23 19:25:18 UTC
svn commit: r1757419 [21/29] - in /cassandra/site/src/doc: ./ 3.10/
3.10/_images/ 3.10/_sources/ 3.10/_sources/architecture/
3.10/_sources/configuration/ 3.10/_sources/cql/
3.10/_sources/data_modeling/ 3.10/_sources/development/ 3.10/_sources/faq/
3.10...
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