---
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 v4.0-alpha5" 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: ".txt"
    };
</script>
'

---
<div class="container-fluid">
  <div class="row">
    <div class="col-md-3">
      <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="../new/index.html">New Features in Apache Cassandra 4.0</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/index.html">Architecture</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="#working-with-durations">Working with durations</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="operators.html">Arithmetic Operators</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="../data_modeling/index.html">Data Modeling</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">Contributing to Cassandra</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="../plugins/index.html">Third-Party Plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</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="content-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 notranslate"><span class="pre">native_type</span></code></a> | <a class="reference internal" href="#grammar-token-collection-type"><code class="xref docutils literal notranslate"><span class="pre">collection_type</span></code></a> | <a class="reference internal" href="#grammar-token-user-defined-type"><code class="xref docutils literal notranslate"><span class="pre">user_defined_type</span></code></a> | <a class="reference internal" href="#grammar-token-tuple-type"><code class="xref docutils literal notranslate"><span class="pre">tuple_type</span></code></a> | <a class="reference internal" href="#grammar-token-custom-type"><code class="xref docutils literal notranslate"><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
                 | DURATION
                 | 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 notranslate"><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 notranslate"><span class="pre">string</span></code></a></td>
<td>ASCII character string</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">integer</span></code></a></td>
<td>64-bit signed long</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">blob</span></code></a></td>
<td>Arbitrary bytes (no validation)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">boolean</span></code></a></td>
<td>Either <code class="docutils literal notranslate"><span class="pre">true</span></code> or <code class="docutils literal notranslate"><span class="pre">false</span></code></td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">float</span></code></a></td>
<td>Variable-precision decimal</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">duration</span></code></td>
<td><code class="xref std std-token docutils literal notranslate"><span class="pre">duration</span></code>,</td>
<td>A duration with nanosecond precision. See <a class="reference internal" href="#durations"><span class="std std-ref">Working with durations</span></a> below for details</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">float</span></code></a></td>
<td>32-bit IEEE-754 floating point</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">inet</span></code> constant, IP address should be input as strings</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">integer</span></code></a></td>
<td>32-bit signed int</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">integer</span></code></a></td>
<td>16-bit signed int</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">string</span></code></a></td>
<td>UTF8 encoded string</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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-odd"><td><code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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-even"><td><code class="docutils literal notranslate"><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 notranslate"><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-odd"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">integer</span></code></a></td>
<td>8-bit signed int</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><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 notranslate"><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-odd"><td><code class="docutils literal notranslate"><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 notranslate"><span class="pre">string</span></code></a></td>
<td>UTF8 encoded string</td>
</tr>
<tr class="row-even"><td><code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">PRIMARY</span> <span class="pre">KEY</span></code> have the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">1299038700000</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'2011-02-03</span> <span class="pre">04:05+0000'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'2011-02-03</span> <span class="pre">04:05:00+0000'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'2011-02-03</span> <span class="pre">04:05:00.000+0000'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'2011-02-03T04:05+0000'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'2011-02-03T04:05:00+0000'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'2011-02-03T04:05:00.000+0000'</span></code></li>
</ul>
<p>The <code class="docutils literal notranslate"><span class="pre">+0000</span></code> above is an RFC 822 4-digit time zone specification; <code class="docutils literal notranslate"><span class="pre">+0000</span></code> refers to GMT. US Pacific Standard Time is
<code class="docutils literal notranslate"><span class="pre">-0800</span></code>. The time zone may be omitted if desired (<code class="docutils literal notranslate"><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 notranslate"><span class="pre">'2011-02-03'</span></code> or <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">string</span></code></a>. In the later case, the format should be <code class="docutils literal notranslate"><span class="pre">yyyy-mm-dd</span></code> (so <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">string</span></code></a>
representing the time. In the later case, the format should be <code class="docutils literal notranslate"><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 notranslate"><span class="pre">'08:12:54'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'08:12:54.123'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'08:12:54.123456'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'08:12:54.123456789'</span></code></li>
</ul>
</div>
<div class="section" id="working-with-durations">
<span id="durations"></span><h2>Working with durations<a class="headerlink" href="#working-with-durations" title="Permalink to this headline">¶</a></h2>
<p>Values of the <code class="docutils literal notranslate"><span class="pre">duration</span></code> type are encoded as 3 signed integer of variable lengths. The first integer represents the
number of months, the second the number of days and the third the number of nanoseconds. This is due to the fact that
the number of days in a month can change, and a day can have 23 or 25 hours depending on the daylight saving.
Internally, the number of months and days are decoded as 32 bits integers whereas the number of nanoseconds is decoded
as a 64 bits integer.</p>
<p>A duration can be input as:</p>
<blockquote>
<div><ol class="arabic">
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">(quantity</span> <span class="pre">unit)+</span></code> like <code class="docutils literal notranslate"><span class="pre">12h30m</span></code> where the unit can be:</p>
<blockquote>
<div><ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">y</span></code>: years (12 months)</li>
<li><code class="docutils literal notranslate"><span class="pre">mo</span></code>: months (1 month)</li>
<li><code class="docutils literal notranslate"><span class="pre">w</span></code>: weeks (7 days)</li>
<li><code class="docutils literal notranslate"><span class="pre">d</span></code>: days (1 day)</li>
<li><code class="docutils literal notranslate"><span class="pre">h</span></code>: hours (3,600,000,000,000 nanoseconds)</li>
<li><code class="docutils literal notranslate"><span class="pre">m</span></code>: minutes (60,000,000,000 nanoseconds)</li>
<li><code class="docutils literal notranslate"><span class="pre">s</span></code>: seconds (1,000,000,000 nanoseconds)</li>
<li><code class="docutils literal notranslate"><span class="pre">ms</span></code>: milliseconds (1,000,000 nanoseconds)</li>
<li><code class="docutils literal notranslate"><span class="pre">us</span></code> or <code class="docutils literal notranslate"><span class="pre">µs</span></code> : microseconds (1000 nanoseconds)</li>
<li><code class="docutils literal notranslate"><span class="pre">ns</span></code>: nanoseconds (1 nanosecond)</li>
</ul>
</div></blockquote>
</li>
<li><p class="first">ISO 8601 format:  <code class="docutils literal notranslate"><span class="pre">P[n]Y[n]M[n]DT[n]H[n]M[n]S</span> <span class="pre">or</span> <span class="pre">P[n]W</span></code></p>
</li>
<li><p class="first">ISO 8601 alternative format: <code class="docutils literal notranslate"><span class="pre">P[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]</span></code></p>
</li>
</ol>
</div></blockquote>
<p>For example:</p>
<div class="highlight-cql notranslate"><div class="highlight"><pre><span></span><span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">RiderResults</span> <span class="p">(</span><span class="n">rider</span><span class="p">,</span> <span class="n">race</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">&#39;Christopher Froome&#39;</span><span class="p">,</span> <span class="s1">&#39;Tour de France&#39;</span><span class="p">,</span> <span class="mf">89</span><span class="n">h4m48s</span><span class="p">);</span>
<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">RiderResults</span> <span class="p">(</span><span class="n">rider</span><span class="p">,</span> <span class="n">race</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">&#39;BARDET Romain&#39;</span><span class="p">,</span> <span class="s1">&#39;Tour de France&#39;</span><span class="p">,</span> <span class="n">PT89H8M53S</span><span class="p">);</span>
<span class="k">INSERT</span> <span class="k">INTO</span> <span class="n">RiderResults</span> <span class="p">(</span><span class="n">rider</span><span class="p">,</span> <span class="n">race</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="k">VALUES</span> <span class="p">(</span><span class="s1">&#39;QUINTANA Nairo&#39;</span><span class="p">,</span> <span class="s1">&#39;Tour de France&#39;</span><span class="p">,</span> <span class="n">P0000</span><span class="o">-</span><span class="mf">00</span><span class="o">-</span><span class="mf">00</span><span class="n">T89</span><span class="p">:</span><span class="mf">09</span><span class="p">:</span><span class="mf">09</span><span class="p">);</span>
</pre></div>
</div>
<p id="duration-limitation">Duration columns cannot be used in a table’s <code class="docutils literal notranslate"><span class="pre">PRIMARY</span> <span class="pre">KEY</span></code>. This limitation is due to the fact that
durations cannot be ordered. It is effectively not possible to know if <code class="docutils literal notranslate"><span class="pre">1mo</span></code> is greater than <code class="docutils literal notranslate"><span class="pre">29d</span></code> without a date
context.</p>
<p>A <code class="docutils literal notranslate"><span class="pre">1d</span></code> duration is not equals to a <code class="docutils literal notranslate"><span class="pre">24h</span></code> one as the duration type has been created to be able to support daylight
saving.</p>
</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 '&lt;' <a class="reference internal" href="#grammar-token-cql-type"><code class="xref docutils literal notranslate"><span class="pre">cql_type</span></code></a> ',' <a class="reference internal" href="#grammar-token-cql-type"><code class="xref docutils literal notranslate"><span class="pre">cql_type</span></code></a> '&gt;'
                     | SET '&lt;' <a class="reference internal" href="#grammar-token-cql-type"><code class="xref docutils literal notranslate"><span class="pre">cql_type</span></code></a> '&gt;'
                     | LIST '&lt;' <a class="reference internal" href="#grammar-token-cql-type"><code class="xref docutils literal notranslate"><span class="pre">cql_type</span></code></a> '&gt;'
</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 notranslate"><span class="pre">map_literal</span></code></a> | <a class="reference internal" href="#grammar-token-set-literal"><code class="xref docutils literal notranslate"><span class="pre">set_literal</span></code></a> | <a class="reference internal" href="#grammar-token-list-literal"><code class="xref docutils literal notranslate"><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 notranslate"><span class="pre">term</span></code></a> ':' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><span class="pre">term</span></code></a> (',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><span class="pre">term</span></code></a> : <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><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 notranslate"><span class="pre">term</span></code></a> (',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><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 notranslate"><span class="pre">term</span></code></a> (',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><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 notranslate"><span class="pre">bind_marker</span></code></a> nor <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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">&lt;</span><span class="nb">text</span><span class="p">,</span> <span class="nb">text</span><span class="o">&gt;</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">&#39;jsmith&#39;</span><span class="p">,</span> <span class="s1">&#39;John Smith&#39;</span><span class="p">,</span> <span class="p">{</span> <span class="s1">&#39;fruit&#39;</span> <span class="p">:</span> <span class="s1">&#39;Apple&#39;</span><span class="p">,</span> <span class="s1">&#39;band&#39;</span> <span class="p">:</span> <span class="s1">&#39;Beatles&#39;</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">&#39;fruit&#39;</span> <span class="p">:</span> <span class="s1">&#39;Banana&#39;</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">&#39;jsmith&#39;</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 notranslate"><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">&#39;author&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;Ed Poe&#39;</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">&#39;jsmith&#39;</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">&#39;movie&#39;</span> <span class="p">:</span> <span class="s1">&#39;Cassablanca&#39;</span><span class="p">,</span> <span class="s1">&#39;band&#39;</span> <span class="p">:</span> <span class="s1">&#39;ZZ Top&#39;</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">&#39;jsmith&#39;</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 notranslate"><div class="highlight"><pre><span></span><span class="k">DELETE</span> <span class="n">favs</span><span class="p">[</span><span class="s1">&#39;author&#39;</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">&#39;jsmith&#39;</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">&#39;movie&#39;</span><span class="p">,</span> <span class="s1">&#39;band&#39;</span><span class="p">}</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">&#39;jsmith&#39;</span><span class="p">;</span>
</pre></div>
</div>
<p>Note that for removing multiple elements in a <code class="docutils literal notranslate"><span class="pre">map</span></code>, you remove from it a <code class="docutils literal notranslate"><span class="pre">set</span></code> of keys.</p>
</li>
</ul>
<p>Lastly, TTLs are allowed for both <code class="docutils literal notranslate"><span class="pre">INSERT</span></code> and <code class="docutils literal notranslate"><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 notranslate"><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">&#39;color&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;green&#39;</span> <span class="k">WHERE</span> <span class="n">id</span> <span class="o">=</span> <span class="s1">&#39;jsmith&#39;</span><span class="p">;</span>
</pre></div>
</div>
<p>will only apply the TTL to the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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">&lt;</span><span class="nb">text</span><span class="o">&gt;</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">&#39;cat.jpg&#39;</span><span class="p">,</span> <span class="s1">&#39;jsmith&#39;</span><span class="p">,</span> <span class="p">{</span> <span class="s1">&#39;pet&#39;</span><span class="p">,</span> <span class="s1">&#39;cute&#39;</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">&#39;kitten&#39;</span><span class="p">,</span> <span class="s1">&#39;cat&#39;</span><span class="p">,</span> <span class="s1">&#39;lol&#39;</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;cat.jpg&#39;</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 notranslate"><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">&#39;gray&#39;</span><span class="p">,</span> <span class="s1">&#39;cuddly&#39;</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;cat.jpg&#39;</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 notranslate"><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">&#39;cat&#39;</span> <span class="p">}</span> <span class="k">WHERE</span> <span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;cat.jpg&#39;</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 notranslate"><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 notranslate"><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">&lt;</span><span class="nb">int</span><span class="o">&gt;</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">&#39;123-afde&#39;</span><span class="p">,</span> <span class="s1">&#39;quake&#39;</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">&#39;123-afde&#39;</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 notranslate"><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">&#39;123-afde&#39;</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">&#39;123-afde&#39;</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 notranslate"><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">&#39;123-afde&#39;</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 notranslate"><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">&#39;123-afde&#39;</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 notranslate"><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">&#39;123-afde&#39;</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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">keyspace_name</span></code></a> '.' ] <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">udt_name</span></code></a>
                               '(' <a class="reference internal" href="#grammar-token-field-definition"><code class="xref docutils literal notranslate"><span class="pre">field_definition</span></code></a> ( ',' <a class="reference internal" href="#grammar-token-field-definition"><code class="xref docutils literal notranslate"><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 notranslate"><span class="pre">identifier</span></code></a> <a class="reference internal" href="#grammar-token-cql-type"><code class="xref docutils literal notranslate"><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 notranslate"><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">text</span><span class="p">,</span>
    <span class="n">phones</span> <span class="k">map</span><span class="o">&lt;</span><span class="nb">text</span><span class="p">,</span> <span class="n">phone</span><span class="o">&gt;</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">&lt;</span><span class="nb">text</span><span class="p">,</span> <span class="k">frozen</span><span class="o">&lt;</span><span class="n">address</span><span class="o">&gt;&gt;</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 notranslate"><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 4.0-alpha5, UDT have to be frozen in most cases, hence the <code class="docutils literal notranslate"><span class="pre">frozen&lt;address&gt;</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 notranslate"><span class="pre">identifier</span></code></a> ':' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><span class="pre">term</span></code></a> ( ',' <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ':' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><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 notranslate"><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">&#39;z3 Pr3z1den7&#39;</span><span class="p">,</span> <span class="p">{</span>
              <span class="s1">&#39;home&#39;</span> <span class="p">:</span> <span class="p">{</span>
                  <span class="n">street</span><span class="p">:</span> <span class="s1">&#39;1600 Pennsylvania Ave NW&#39;</span><span class="p">,</span>
                  <span class="n">city</span><span class="p">:</span> <span class="s1">&#39;Washington&#39;</span><span class="p">,</span>
                  <span class="n">zip</span><span class="p">:</span> <span class="s1">&#39;20500&#39;</span><span class="p">,</span>
                  <span class="n">phones</span><span class="p">:</span> <span class="p">{</span> <span class="s1">&#39;cell&#39;</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">&#39;202 456-1111&#39;</span> <span class="p">},</span>
                            <span class="s1">&#39;landline&#39;</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">&#39;...&#39;</span> <span class="p">}</span> <span class="p">}</span>
              <span class="p">},</span>
              <span class="s1">&#39;work&#39;</span> <span class="p">:</span> <span class="p">{</span>
                  <span class="n">street</span><span class="p">:</span> <span class="s1">&#39;1600 Pennsylvania Ave NW&#39;</span><span class="p">,</span>
                  <span class="n">city</span><span class="p">:</span> <span class="s1">&#39;Washington&#39;</span><span class="p">,</span>
                  <span class="n">zip</span><span class="p">:</span> <span class="s1">&#39;20500&#39;</span><span class="p">,</span>
                  <span class="n">phones</span><span class="p">:</span> <span class="p">{</span> <span class="s1">&#39;fax&#39;</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">&#39;...&#39;</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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">udt_name</span></code></a> <a class="reference internal" href="#grammar-token-alter-type-modification"><code class="xref docutils literal notranslate"><span class="pre">alter_type_modification</span></code></a>
<strong id="grammar-token-alter-type-modification">alter_type_modification</strong> ::=  ADD <a class="reference internal" href="#grammar-token-field-definition"><code class="xref docutils literal notranslate"><span class="pre">field_definition</span></code></a>
                             | RENAME <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> TO <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> ( <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> TO <a class="reference internal" href="definitions.html#grammar-token-identifier"><code class="xref docutils literal notranslate"><span class="pre">identifier</span></code></a> )*
</pre>
<p>You can:</p>
<ul class="simple">
<li>add a new field to the type (<code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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 '&lt;' <a class="reference internal" href="#grammar-token-cql-type"><code class="xref docutils literal notranslate"><span class="pre">cql_type</span></code></a> ( ',' <a class="reference internal" href="#grammar-token-cql-type"><code class="xref docutils literal notranslate"><span class="pre">cql_type</span></code></a> )* '&gt;'
<strong id="grammar-token-tuple-literal">tuple_literal</strong> ::=  '(' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><span class="pre">term</span></code></a> ( ',' <a class="reference internal" href="definitions.html#grammar-token-term"><code class="xref docutils literal notranslate"><span class="pre">term</span></code></a> )* ')'
</pre>
<p>and can be used thusly:</p>
<div class="highlight-cql notranslate"><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">&lt;</span><span class="nb">int</span><span class="p">,</span> <span class="nb">text</span><span class="o">&gt;</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">&#39;ev1&#39;</span><span class="p">,</span> <span class="p">(</span><span class="mf">3</span><span class="p">,</span> <span class="s1">&#39;hours&#39;</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 notranslate"><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 notranslate"><span class="pre">string</span></code></a> that contains the name of Java class that extends the server side <code class="docutils literal notranslate"><span class="pre">AbstractType</span></code>
class and that can be loaded by Cassandra (it should thus be in the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><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>
</div>