PyPI - amps-python-client - Versions diffs - 5.3.4.1__zip → 5.3.4.2__zip - Mend

amps-python-client 5.3.4.1zip → 5.3.4.2zip

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (917) hide show

amps-python-client-5.3.4.1/docs/user-guide/html/chapters/amps_expressions.html DELETED Viewed

@@ -1,1552 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-    <title>4. AMPS Expressions &#8212; AMPS User Guide develop documentation</title>
-    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
-    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
-    <script type="text/javascript">
-      var DOCUMENTATION_OPTIONS = {
-        URL_ROOT:    '../',
-        VERSION:     'develop',
-        COLLAPSE_INDEX: false,
-        FILE_SUFFIX: '.html',
-        HAS_SOURCE:  true,
-        SOURCELINK_SUFFIX: '.txt'
-      };
-    </script>
-    <script type="text/javascript" src="../_static/jquery.js"></script>
-    <script type="text/javascript" src="../_static/underscore.js"></script>
-    <script type="text/javascript" src="../_static/doctools.js"></script>
-    <link rel="index" title="Index" href="../genindex.html" />
-    <link rel="search" title="Search" href="../search.html" />
-    <link rel="next" title="5. AMPS Functions" href="amps_functions.html" />
-    <link rel="prev" title="3. Publish and Subscribe" href="pub_sub.html" />
-  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
-  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
-  </head>
-  <body role="document">
-  <div class="document">
-      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
-        <div class="sphinxsidebarwrapper">
-            <p class="logo"><a href="../index.html">
-              <img class="logo" src="../_static/flag_logo.png" alt="Logo"/>
-            </a></p>
-  <h3><a href="../index.html">Table Of Contents</a></h3>
-  <ul>
-<li><a class="reference internal" href="#">4. AMPS Expressions</a><ul>
-<li><a class="reference internal" href="#expressions-overview">Expressions Overview</a></li>
-<li><a class="reference internal" href="#expression-syntax">Expression Syntax</a><ul>
-<li><a class="reference internal" href="#ug-expression-identifiers">Identifiers</a></li>
-<li><a class="reference internal" href="#amps-data-types">AMPS Data Types</a><ul>
-<li><a class="reference internal" href="#numeric-types-and-literals-in-amps-expressions">Numeric Types and Literals in AMPS Expressions</a></li>
-<li><a class="reference internal" href="#type-promotion-for-numeric-types">Type Promotion for Numeric Types</a></li>
-<li><a class="reference internal" href="#string-literals-in-amps-expressions">String Literals in AMPS Expressions</a></li>
-<li><a class="reference internal" href="#null-nan-and-is-null">NULL, NaN and IS NULL</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#grouping-and-order-of-evaluation">Grouping and Order of Evaluation</a></li>
-<li><a class="reference internal" href="#logical-operators">Logical Operators</a></li>
-<li><a class="reference internal" href="#arithmetic-operators">Arithmetic Operators</a></li>
-<li><a class="reference internal" href="#comparison-operators">Comparison Operators</a></li>
-<li><a class="reference internal" href="#regular-expression-matching">Regular Expression Matching</a></li>
-<li><a class="reference internal" href="#conditional-operators">Conditional Operators</a></li>
-<li><a class="reference internal" href="#working-with-arrays">Working with Arrays</a></li>
-<li><a class="reference internal" href="#working-with-timestamps">Working with Timestamps</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#using-regular-expressions-in-amps">Using Regular Expressions in AMPS</a><ul>
-<li><a class="reference internal" href="#examples">Examples</a></li>
-<li><a class="reference internal" href="#raw-strings">Raw Strings</a></li>
-<li><a class="reference internal" href="#subscribing-to-a-set-of-topics-using-regular-expressions">Subscribing to a Set of Topics Using Regular Expressions</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#performance-considerations">Performance Considerations</a><ul>
-<li><a class="reference internal" href="#use-short-circuiting">Use Short-Circuiting</a></li>
-<li><a class="reference internal" href="#avoid-redundant-expressions">Avoid Redundant Expressions</a></li>
-<li><a class="reference internal" href="#use-specialized-operators-for-simple-comparisons-use-like-when-necessary">Use Specialized Operators for Simple Comparisons, Use LIKE when Necessary</a></li>
-<li><a class="reference internal" href="#optimize-for-partial-parsing">Optimize for Partial Parsing</a></li>
-<li><a class="reference internal" href="#sow-queries-and-indexing">SOW Queries and Indexing</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
-<ul>
-  <li><a href="../index.html">Documentation overview</a><ul>
-      <li>Previous: <a href="pub_sub.html" title="previous chapter">3. Publish and Subscribe</a></li>
-      <li>Next: <a href="amps_functions.html" title="next chapter">5. AMPS Functions</a></li>
-  </ul></li>
-</ul>
-</div>
-<div id="searchbox" style="display: none" role="search">
-  <h3>Quick search</h3>
-    <form class="search" action="../search.html" method="get">
-      <div><input type="text" name="q" /></div>
-      <div><input type="submit" value="Go" /></div>
-      <input type="hidden" name="check_keywords" value="yes" />
-      <input type="hidden" name="area" value="default" />
-    </form>
-</div>
-<script type="text/javascript">$('#searchbox').show(0);</script>
-        </div>
-      </div>
-      <div class="documentwrapper">
-        <div class="bodywrapper">
-          <div class="body" role="main">
-  <div class="section" id="amps-expressions">
-<span id="ug-amps-expressions"></span><span id="index-0"></span><span id="id1"></span><h1>4. AMPS Expressions<a class="headerlink" href="#amps-expressions" title="Permalink to this headline">¶</a></h1>
-<p>AMPS includes an expression language that combines elements of XPath and
-SQL-92&#8217;s <code class="docutils literal"><span class="pre">WHERE</span></code> clause. This expression language is used whenever the
-AMPS server refers to the contents of a message, including:</p>
-<ul class="simple">
-<li>Content filtering</li>
-<li>Constructing fields for message enrichment</li>
-<li>Creating projected fields for views</li>
-</ul>
-<p>AMPS uses a common syntax for each of these purposes, and provides a
-common set of operators and functions. AMPS also provides special
-directives for message enrichment, and aggregation functions for
-projecting views.</p>
-<p>For example, when an expression is used as a content filter, any message
-for which the expression returns <code class="docutils literal"><span class="pre">true</span></code> matches the content filter.
-When an expression is used to construct a field for message enrichment
-or view projection, the expression is evaluated and the result that the
-expression returns is used as the content of the field.</p>
-<div class="section" id="expressions-overview">
-<h2>Expressions Overview<a class="headerlink" href="#expressions-overview" title="Permalink to this headline">¶</a></h2>
-<p>The quickest way to learn AMPS expressions is to think of each as a
-combination of identifiers that tell AMPS where to find data in a
-message, and operators that tell AMPS what to do with that data. Each
-AMPS expression produces a value. The way AMPS uses that value depends
-on where the expression is used. For example, in a content filter, AMPS
-uses the value of the expression to determine whether a message matches
-the filter. When constructing a field, AMPS uses the value of the
-expression as the contents of the field.</p>
-<p>Consider a simple example of an expression used as a filter. Imagine
-AMPS receives the following JSON message:</p>
-<div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;name&quot;</span><span class="o">:</span><span class="s2">&quot;Gyro&quot;</span><span class="p">,</span> <span class="s2">&quot;job&quot;</span><span class="o">:</span><span class="s2">&quot;kitten&quot;</span><span class="p">}</span>
-</pre></div>
-</div>
-<p>Using an AMPS expression, you can easily construct a content filter that
-matches the message:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">name</span> <span class="o">=</span> <span class="s1">&#39;Gyro&#39;</span>
-</pre></div>
-</div>
-<p>There are three parts to this expression. The first part, <code class="docutils literal"><span class="pre">/name</span></code>, is
-an <em>identifier</em> that tells AMPS to look for the contents of the <code class="docutils literal"><span class="pre">name</span></code>
-field at the top level of the JSON document. The second part of the
-filter, <code class="docutils literal"><span class="pre">=</span></code>, is the equality <em>operator</em>, which tells AMPS to compare
-the values on either side of the operator and return <code class="docutils literal"><span class="pre">true</span></code> if the
-values match. The final part of the filter, <code class="docutils literal"><span class="pre">'Gyro'</span></code>, is a string
-<em>literal</em> for the equality operator to use in the comparison. When an
-expression is used in a content filter, a message matches the filter
-when the expression returns <code class="docutils literal"><span class="pre">true</span></code>. The expression returns <code class="docutils literal"><span class="pre">true</span></code>
-for the sample message, so the sample message matches the filter.</p>
-<p>The identifier syntax is a subset of XPath, as described in
-<a class="reference internal" href="#ug-expression-identifiers"><span class="std std-ref">Identifiers</span></a>. The comparison syntax
-is similar to SQL-92.</p>
-<p>Notice that AMPS makes no rigid guarantees as to the number of times
-a given expression is evaluated or when that evaluation will take
-place. AMPS will evaluate the expression as needed.</p>
-</div>
-<div class="section" id="expression-syntax">
-<span id="content-filter-syntax"></span><h2>Expression Syntax<a class="headerlink" href="#expression-syntax" title="Permalink to this headline">¶</a></h2>
-<p>AMPS expressions are designed to work exactly as expected if you are
-familiar with XPath path specifiers and SQL-92 predicates. This section
-describes in detail how AMPS evaluates the syntax, operators, and
-functions available in the AMPS expression language.</p>
-<p>AMPS expressions combine the following elements:</p>
-<ul class="simple">
-<li><em>Identifiers</em> specify a field in a message. When evaluating an
-expression, AMPS replaces identifiers with values from the message
-or set of messages being evaluated.</li>
-<li><em>Literal</em> values are explicit values in an AMPS expression, such as
-<code class="docutils literal"><span class="pre">'IBM'</span></code> or <code class="docutils literal"><span class="pre">42</span></code></li>
-<li><em>Operators</em> and <em>functions</em> such as <code class="docutils literal"><span class="pre">=</span></code>, <code class="docutils literal"><span class="pre">&lt;</span></code>, <code class="docutils literal"><span class="pre">&gt;</span></code>, <code class="docutils literal"><span class="pre">*</span></code>, and
-<code class="docutils literal"><span class="pre">UNIX_TIMESTAMP()</span></code></li>
-</ul>
-<p>Every AMPS expression produces a value. The way that AMPS uses the value
-depends on the context in which AMPS evaluates the expression. For
-example, if the expression is used for a filter, the message is
-considered to match the filter when the expression returns <code class="docutils literal"><span class="pre">true</span></code>.
-When an expression is used to project a field, the result of the
-expression is used as the value of the projected field.</p>
-<div class="section" id="ug-expression-identifiers">
-<span id="index-1"></span><span id="identifiers"></span><h3>Identifiers<a class="headerlink" href="#ug-expression-identifiers" title="Permalink to this headline">¶</a></h3>
-<p>AMPS identifiers use a subset of XPath to specify values in a message.
-AMPS identifiers specify the value of an attribute or element in an XML
-message, and the value of a field in a JSON, FIX or NVFIX message.
-Given that the identifier syntax is only used to specify values, the subset
-of XPath used by AMPS does not include wildcards, relative paths, array
-manipulation, predicates or functions.</p>
-<p>For example, when messages are in this XML format:</p>
-<div class="highlight-xml"><div class="highlight"><pre><span></span><span class="nt">&lt;Order</span> <span class="na">update=</span><span class="s">&quot;full&quot;</span><span class="nt">&gt;</span>
-    <span class="nt">&lt;ClientID&gt;</span>12345<span class="nt">&lt;/ClientID&gt;</span>
-    <span class="nt">&lt;Symbol&gt;</span>IBM<span class="nt">&lt;/Symbol&gt;</span>
-    <span class="nt">&lt;OrderQty&gt;</span>1000<span class="nt">&lt;/OrderQty&gt;</span>
-<span class="nt">&lt;/Order&gt;</span>
-</pre></div>
-</div>
-<p>The following identifier specifies the <code class="docutils literal"><span class="pre">Symbol</span></code> element of an
-<code class="docutils literal"><span class="pre">Order</span></code> message:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Symbol</span>
-</pre></div>
-</div>
-<p>The following identifier specifies the <code class="docutils literal"><span class="pre">update</span></code> attribute of an
-<code class="docutils literal"><span class="pre">Order</span></code> message:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="nd">@update</span>
-</pre></div>
-</div>
-<p>For FIX and NVFIX, you specify fields using <code class="docutils literal"><span class="pre">/</span></code> and the tag name. AMPS
-interprets FIX and NVFIX messages as though they were an XML fragment
-with no root element. For example, to specify the value of FIX tag
-<code class="docutils literal"><span class="pre">55</span></code> (symbol), use the following identifier:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="mi">55</span>
-</pre></div>
-</div>
-<p>Likewise, for JSON or other types that represent an object, you navigate
-through the object structure using the <code class="docutils literal"><span class="pre">/</span></code> to indicate each level of
-nesting.</p>
-<p>AMPS only guarantees support for field identifiers that are valid <em>step names</em>
-in XPath. For example, AMPS does not guarantee that it can process or
-filter on a field named <code class="docutils literal"><span class="pre">Fits&amp;Starts</span></code>.</p>
-<p>AMPS also supports an optional <em>bracketed field identifier</em> syntax that extends
-the characters available for field names. For example, the following step name:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">[</span><span class="o">/</span><span class="n">Not</span> <span class="n">Xpath</span> <span class="n">Name</span><span class="p">]</span>
-</pre></div>
-</div>
-<p>refers to a field name of <code class="docutils literal"><span class="pre">Not</span> <span class="pre">Xpath</span> <span class="pre">Name</span></code> at the root level of the message.
-This syntax allows spaces to be used in field names in AMPS expressions, even
-though this is not a valid step name in XPath. Notice that not all message
-types support field names with embedded spaces or other special characters.
-For example, the <code class="docutils literal"><span class="pre">Not</span> <span class="pre">Xpath</span> <span class="pre">Name</span></code> identifier is not a valid element name
-in XML, nor would it be a valid field name in Google Protocol Buffers.</p>
-<p>AMPS checks the syntax of identifiers when parsing an expression. AMPS
-does not try to predict whether an identifier will match messages within
-a particular topic. It is not an error to submit an identifier that can
-never match due to the limitations of the message type. For example,
-AMPS allows you to use an identifier like <code class="docutils literal"><span class="pre">/OrderQty</span></code> in a filter submitted
-for a FIX connection, even though FIX messages only use numeric tags, or an
-identifier like <code class="docutils literal"><span class="pre">/DataPackage/RunDate</span></code> in a filter submitted for a BFlat
-connection, even though BFlat does not support nested elements.</p>
-<p>The message type is responsible for constructing a set of identifiers
-from a message. In most cases, the mapping is simple. However, see the
-documentation for the message type for details, or if the mapping is
-unclear. For example, a <code class="docutils literal"><span class="pre">composite-local</span></code> message type adds the number
-of the part to the beginning of each XPath within the part (so, a
-top-level field of <code class="docutils literal"><span class="pre">/name</span></code> in the first part of the message has an
-identifier of <code class="docutils literal"><span class="pre">/0/name</span></code>).</p>
-</div>
-<div class="section" id="amps-data-types">
-<span id="ug-expressions-data-types"></span><span id="index-2"></span><h3>AMPS Data Types<a class="headerlink" href="#amps-data-types" title="Permalink to this headline">¶</a></h3>
-<p>Each value in AMPS is assigned a data type when the message type module
-parses the value. AMPS operators and functions attempt to convert values
-into compatible types, based on the type of operation. For example, the
-<code class="docutils literal"><span class="pre">*</span></code> operator (multiplication) will attempt to convert all values to
-numeric values, while the <code class="docutils literal"><span class="pre">CONCAT</span></code> function (string concatenation)
-will attempt to convert all values to strings. In effect, a value in
-AMPS can be transparently treated as any type to which it can be
-meaningfully converted.</p>
-<p>Internally, AMPS uses the data types in the table below. As mentioned above, the
-message type module is responsible for assigning the type of a value
-from an incoming message as part of the parsing process. For some types,
-such as JSON, XML, FIX and NVFIX, the parser infers the type of the
-value from the field. For other types, such as MessagePack, BFLAT,
-Google Protocol Buffers or BSON, the message itself contains information
-about the type of the field.</p>
-<p>As mentioned above, the AMPS expression language does not limit the value
-to the type assigned by the message type module. Instead, a value in AMPS
-can be used in any context.</p>
-<p>For example, given the following JSON document:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;a&quot;</span><span class="p">:</span><span class="mi">1</span><span class="p">,</span><span class="s2">&quot;b&quot;</span><span class="p">:</span><span class="s2">&quot;47&quot;</span><span class="p">}</span>
-</pre></div>
-</div>
-<p>The values of <code class="docutils literal"><span class="pre">/a</span></code> and <code class="docutils literal"><span class="pre">/b</span></code> can be used as either string values or
-numeric values. AMPS will automatically convert these values as necessary,
-and AMPS considers the string or numeric representation to
-be equally correct and valid.</p>
-<p>The following table lists the data types in the AMPS expression language:</p>
-<table border="1" class="colwidths-given docutils" id="id3">
-<caption><span class="caption-text"><em>AMPS data types</em></span><a class="headerlink" href="#id3" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="10%" />
-<col width="30%" />
-<col width="60%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Type</th>
-<th class="head">Description</th>
-<th class="head">Untyped Message Examples</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td>NULL</td>
-<td>Unknown, untyped value
-(SQL-92 semantics)</td>
-<td><p class="first">[no field provided]</p>
-<p>NVFIX: <code class="docutils literal"><span class="pre">a=&lt;SOH&gt;</span></code></p>
-<p>JSON: <code class="docutils literal"><span class="pre">{&quot;a&quot;:null}</span></code></p>
-<p class="last">XML: <code class="docutils literal"><span class="pre">&lt;a/&gt;</span></code></p>
-</td>
-</tr>
-<tr class="row-odd"><td>Boolean</td>
-<td>True (<code class="docutils literal"><span class="pre">1</span></code>) or false
-(<code class="docutils literal"><span class="pre">0</span></code>)</td>
-<td>JSON: <code class="docutils literal"><span class="pre">{&quot;e&quot;:true}</span></code></td>
-</tr>
-<tr class="row-even"><td>Integer</td>
-<td>Signed 64-bit integer or
-unsigned 64-bit integer
-for values &gt; LONG_MAX</td>
-<td><p class="first">NVFIX: <code class="docutils literal"><span class="pre">b=24</span></code></p>
-<p>JSON: <code class="docutils literal"><span class="pre">{&quot;b&quot;:24}</span></code></p>
-<p class="last">XML: <code class="docutils literal"><span class="pre">&lt;b&gt;24&lt;/b&gt;</span></code></p>
-</td>
-</tr>
-<tr class="row-odd"><td>Floating
-Point
-Number</td>
-<td>64-bit floating point
-number</td>
-<td><p class="first">NVFIX: <code class="docutils literal"><span class="pre">c=24.0</span></code></p>
-<p>JSON: <code class="docutils literal"><span class="pre">{&quot;c&quot;:24.0}</span></code></p>
-<p class="last">XML: <code class="docutils literal"><span class="pre">&lt;c&gt;24.0&lt;/c&gt;</span></code></p>
-</td>
-</tr>
-<tr class="row-even"><td>String</td>
-<td><p class="first">Arbitrary sequence of
-bytes of a specific length</p>
-<p class="last">An empty string is
-considered to be <code class="docutils literal"><span class="pre">NULL</span></code></p>
-</td>
-<td><p class="first">NVFIX:
-<code class="docutils literal"><span class="pre">d=Grilled</span> <span class="pre">cheese</span> <span class="pre">sandwich&lt;SOH&gt;</span></code></p>
-<p>JSON:
-<code class="docutils literal"><span class="pre">{&quot;d&quot;:&quot;Grilled</span> <span class="pre">cheese</span> <span class="pre">sandwich&quot;}</span></code></p>
-<p class="last">XML:
-<code class="docutils literal"><span class="pre">&lt;d&gt;Grilled</span> <span class="pre">cheese</span> <span class="pre">sandwich&lt;/d&gt;</span></code></p>
-</td>
-</tr>
-</tbody>
-</table>
-<div class="section" id="numeric-types-and-literals-in-amps-expressions">
-<span id="ug-numeric-types"></span><span id="index-3"></span><h4>Numeric Types and Literals in AMPS Expressions<a class="headerlink" href="#numeric-types-and-literals-in-amps-expressions" title="Permalink to this headline">¶</a></h4>
-<p>Numeric values in AMPS are always <em>typed</em> as either integers or floating
-point values. All numeric types that are less than or equal to the
-LONG_MAX limit in AMPS are signed, otherwise, the numeric type is unsigned.
-AMPS message types convert the original numeric types (or original
-representation for message types that do not have typed values) into the
-internal AMPS type system for the purposes of expression evaluation.</p>
-<p>Within expressions, integer values are all numerals, with no decimal
-point, and can have a value in the same range as a 64-bit integer. For
-example:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="mi">42</span>
-<span class="mi">149</span>
-<span class="o">-</span><span class="mi">273</span>
-<span class="mi">18446744073709551610</span>
-</pre></div>
-</div>
-<p>Within expressions, all numerals with a decimal point are floating-point
-numbers. AMPS interprets these numerals as double-precision floating
-point values. For example:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="mf">3.1415926535</span>
-<span class="mf">98.6</span>
-<span class="o">-</span><span class="mf">273.0</span>
-</pre></div>
-</div>
-<p>or, in scientific notation:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="mf">31.4e-1</span>
-<span class="mf">6.022E23</span>
-<span class="mf">2.998e8</span>
-</pre></div>
-</div>
-<p>AMPS automatically converts strings that contain numeric values to
-numbers when strings are used with an operator, function or
-comparison that expects a numeric value.</p>
-</div>
-<div class="section" id="type-promotion-for-numeric-types">
-<h4>Type Promotion for Numeric Types<a class="headerlink" href="#type-promotion-for-numeric-types" title="Permalink to this headline">¶</a></h4>
-<p>AMPS uses the following rules for type promotion when evaluating numeric
-expressions:</p>
-<ol class="arabic simple">
-<li>If any of the values in the expression is <code class="docutils literal"><span class="pre">NaN</span></code>, the result is
-<code class="docutils literal"><span class="pre">NaN</span></code>.</li>
-<li>Otherwise, if any of the values in the expression is floating point,
-the result is floating point.</li>
-<li>Otherwise, all of the values in the expression are integers, and the
-result is an integer.</li>
-</ol>
-<p>Notice that, for division in particular, the results returned are
-affected by the type of the values. For example, the expression
-<code class="docutils literal"><span class="pre">1</span> <span class="pre">/</span> <span class="pre">5</span></code> evaluates to <code class="docutils literal"><span class="pre">0</span></code> since the result is interpreted as an
-integer. In comparison, the expression <code class="docutils literal"><span class="pre">1.0</span> <span class="pre">/</span> <span class="pre">5</span></code> evaluates to <code class="docutils literal"><span class="pre">0.2</span></code>
-since the result is interpreted as a floating point value.</p>
-<p>When a function or operator that expects a numeric type is provided with
-a string, AMPS will attempt to convert string values to numeric types as
-necessary. When converting string values, AMPS recognizes the same numeric
-formats in message data as are supported in the AMPS expression language
-(see <a class="reference internal" href="#ug-expression-literal-values"><span class="std std-ref">String Literals</span></a>). If the
-string is in an unrecognized format, AMPS converts the string as
-<code class="docutils literal"><span class="pre">NaN</span></code>.</p>
-</div>
-<div class="section" id="string-literals-in-amps-expressions">
-<span id="ug-expression-literal-values"></span><h4>String Literals in AMPS Expressions<a class="headerlink" href="#string-literals-in-amps-expressions" title="Permalink to this headline">¶</a></h4>
-<p>When creating expressions for AMPS, string literals are indicated with
-single or double quotes. For example:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Instrmt</span><span class="o">/</span><span class="nd">@Sym</span> <span class="o">=</span> <span class="s1">&#39;IBM&#39;</span>
-</pre></div>
-</div>
-<p>AMPS supports the following escape sequences within string literals:</p>
-<table border="1" class="docutils" id="id4">
-<caption><span class="caption-text"><em>Escape Sequences</em></span><a class="headerlink" href="#id4" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head"><strong>Escape Sequence</strong></th>
-<th class="head"><strong>Definition</strong></th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td>\a</td>
-<td>Alert</td>
-</tr>
-<tr class="row-odd"><td>\b</td>
-<td>Backspace</td>
-</tr>
-<tr class="row-even"><td>\t</td>
-<td>Horizontal tab</td>
-</tr>
-<tr class="row-odd"><td>\n</td>
-<td>Newline</td>
-</tr>
-<tr class="row-even"><td>\f</td>
-<td>Form feed</td>
-</tr>
-<tr class="row-odd"><td>\r</td>
-<td>Carriage return</td>
-</tr>
-<tr class="row-even"><td>\xHH</td>
-<td>Hexadecimal digit where H is (0..9,a..f,A..F)</td>
-</tr>
-<tr class="row-odd"><td>\OOO</td>
-<td>Octal Digit (0..7)</td>
-</tr>
-</tbody>
-</table>
-<p>Additionally, any character which follows a backslash will be treated as
-a literal character.</p>
-<p>AMPS string operations have no restrictions on character set, and
-correctly handle embedded <code class="docutils literal"><span class="pre">NULL</span></code> characters (<code class="docutils literal"><span class="pre">\x00</span></code>) and characters
-outside of the 7-bit ASCII range. AMPS string operations are not
-unicode-aware.</p>
-</div>
-<div class="section" id="null-nan-and-is-null">
-<span id="ug-null-nan"></span><span id="index-4"></span><h4>NULL, NaN and IS NULL<a class="headerlink" href="#null-nan-and-is-null" title="Permalink to this headline">¶</a></h4>
-<p>XPath expressions are considered to be <code class="docutils literal"><span class="pre">NULL</span></code> when they evaluate to an
-empty or nonexistent field reference. <code class="docutils literal"><span class="pre">NULL</span></code> values follow SQL-92
-semantics.</p>
-<p>This means that comparisons with <code class="docutils literal"><span class="pre">NULL</span></code> are never true
-(in other words, even if <code class="docutils literal"><span class="pre">/a</span></code> is <code class="docutils literal"><span class="pre">NULL</span></code>, <code class="docutils literal"><span class="pre">/a</span> <span class="pre">!=</span> <span class="pre">NULL</span></code> is false
-and <code class="docutils literal"><span class="pre">/a</span> <span class="pre">==</span> <span class="pre">NULL</span></code> is also false).</p>
-<p>In numeric expressions where the operands or results are not a valid
-number, the XPath expression evaluates to <code class="docutils literal"><span class="pre">NaN</span></code> (not a number). The rules
-for applying the <code class="docutils literal"><span class="pre">AND</span></code> and <code class="docutils literal"><span class="pre">OR</span></code> operators against <code class="docutils literal"><span class="pre">NULL</span></code> and <code class="docutils literal"><span class="pre">NaN</span></code>
-values are outlined in the tables below:</p>
-<span id="table-logical-and"></span><table border="1" class="docutils" id="id5">
-<caption><span class="caption-text"><em>Logical AND with NULL/NaN Values</em></span><a class="headerlink" href="#id5" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head"><strong>Operand1</strong></th>
-<th class="head">&#160;</th>
-<th class="head"><strong>Operand2</strong></th>
-<th class="head"><strong>Result</strong></th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td>TRUE</td>
-<td>(AND)</td>
-<td>NULL</td>
-<td>NULL</td>
-</tr>
-<tr class="row-odd"><td>FALSE</td>
-<td>(AND)</td>
-<td>NULL</td>
-<td>FALSE</td>
-</tr>
-<tr class="row-even"><td>NULL</td>
-<td>(AND)</td>
-<td>NULL</td>
-<td>NULL</td>
-</tr>
-<tr class="row-odd"><td>NULL</td>
-<td>(AND)</td>
-<td>TRUE</td>
-<td>NULL</td>
-</tr>
-<tr class="row-even"><td>NULL</td>
-<td>(AND)</td>
-<td>FALSE</td>
-<td>NULL</td>
-</tr>
-</tbody>
-</table>
-<span id="table-logical-or"></span><table border="1" class="docutils" id="id6">
-<caption><span class="caption-text"><em>Logical OR with NULL/NaN Values</em></span><a class="headerlink" href="#id6" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head"><strong>Operand1</strong></th>
-<th class="head">&#160;</th>
-<th class="head"><strong>Operand2</strong></th>
-<th class="head"><strong>Result</strong></th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td>TRUE</td>
-<td>(OR)</td>
-<td>NULL</td>
-<td>TRUE</td>
-</tr>
-<tr class="row-odd"><td>FALSE</td>
-<td>(OR)</td>
-<td>NULL</td>
-<td>NULL</td>
-</tr>
-<tr class="row-even"><td>NULL</td>
-<td>(OR)</td>
-<td>NULL</td>
-<td>NULL</td>
-</tr>
-<tr class="row-odd"><td>NULL</td>
-<td>(OR)</td>
-<td>TRUE</td>
-<td>NULL</td>
-</tr>
-<tr class="row-even"><td>NULL</td>
-<td>(OR)</td>
-<td>FALSE</td>
-<td>NULL</td>
-</tr>
-</tbody>
-</table>
-<p>Likewise, direct comparisons with <code class="docutils literal"><span class="pre">NULL</span></code> are not ever true (so, if <code class="docutils literal"><span class="pre">/b</span></code> is NULL,
-<code class="docutils literal"><span class="pre">/b</span> <span class="pre">==</span> <span class="pre">NULL</span></code> does not produce a true value, and neither does <code class="docutils literal"><span class="pre">/b</span> <span class="pre">!=</span> <span class="pre">NULL</span></code>).
-AMPS, like SQL-92, provides an <code class="docutils literal"><span class="pre">IS</span> <span class="pre">NULL</span></code> predicate for testing whether a value is
-<code class="docutils literal"><span class="pre">NULL</span></code>, and an <code class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span> <span class="pre">NULL</span></code> predicate for testing whether a value is not <code class="docutils literal"><span class="pre">NULL</span></code>.</p>
-<p>There also exists an
-<code class="docutils literal"><span class="pre">IS</span> <span class="pre">NAN</span></code> predicate for checking that a value is <code class="docutils literal"><span class="pre">NaN</span></code> (not a
-number.)</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p>To reliably check for existence of a <code class="docutils literal"><span class="pre">NULL</span></code> value, you must
-use the <code class="docutils literal"><span class="pre">IS</span> <span class="pre">NULL</span></code> predicate such as the filter:
-<code class="docutils literal"><span class="pre">/optionalField</span> <span class="pre">IS</span> <span class="pre">NULL</span></code></p>
-<p class="last">To reliably check that a value is not <code class="docutils literal"><span class="pre">NULL</span></code>, you must use
-the <code class="docutils literal"><span class="pre">IS</span> <span class="pre">NOT</span> <span class="pre">NULL</span></code> predicate or negate the value of an
-<code class="docutils literal"><span class="pre">IS</span> <span class="pre">NULL</span></code> test: <code class="docutils literal"><span class="pre">/optionalField</span> <span class="pre">IS</span> <span class="pre">NOT</span> <span class="pre">NULL</span></code> and
-<code class="docutils literal"><span class="pre">NOT</span> <span class="pre">/optionalField</span> <span class="pre">IS</span> <span class="pre">NULL</span></code> are equivalent</p>
-</div>
-<p id="index-5">AMPS also provides a <code class="docutils literal"><span class="pre">COALESCE()</span></code> function that accepts a set
-of values and returns the first value that is not NULL. For example,
-given the following filter expression:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">COALESCE</span><span class="p">(</span><span class="o">/</span><span class="n">userCategory</span><span class="p">,</span>
-         <span class="o">/</span><span class="n">employeeCategory</span><span class="p">,</span>
-         <span class="o">/</span><span class="n">vendorCategory</span><span class="p">,</span>
-         <span class="s1">&#39;restricted&#39;</span><span class="p">)</span> <span class="o">!=</span> <span class="s1">&#39;restricted&#39;</span>
-</pre></div>
-</div>
-<p>AMPS will return the first value that is not <code class="docutils literal"><span class="pre">NULL</span></code>, and compare that
-value to the constant string <code class="docutils literal"><span class="pre">'restricted'</span></code>. Notice that, to make the
-intent of the filter clear, this example provides a constant value for
-AMPS to return from the <code class="docutils literal"><span class="pre">COALESCE</span></code> if all of the field values are
-<code class="docutils literal"><span class="pre">NULL</span></code>.</p>
-<p>The <code class="docutils literal"><span class="pre">COALESCE</span></code> function, like other functions in AMPS, is not array-aware.
-This means that when one of the XPath expressions provided to <code class="docutils literal"><span class="pre">COALESCE</span></code>
-specifies an array in the original message, AMPS provides the <em>first item in
-the array</em> to the <code class="docutils literal"><span class="pre">COALESCE</span></code> function. See <a class="reference internal" href="#working-with-arrays">Working With Arrays</a> for details.</p>
-</div>
-</div>
-<div class="section" id="grouping-and-order-of-evaluation">
-<span id="index-6"></span><h3>Grouping and Order of Evaluation<a class="headerlink" href="#grouping-and-order-of-evaluation" title="Permalink to this headline">¶</a></h3>
-<p>AMPS expressions allow you to group parts of the expression using
-parentheses. Parts of an expression inside parentheses are evaluated
-together. 60East recommends using parentheses to group independent parts
-of an expression to ensure that the expression is evaluated in the expected
-order. For example, in this expression:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span> <span class="o">/</span><span class="n">counter</span> <span class="o">%</span> <span class="mi">3</span> <span class="p">)</span> <span class="o">==</span> <span class="mi">0</span>
-</pre></div>
-</div>
-<p>The clause <code class="docutils literal"><span class="pre">/counter</span> <span class="pre">%</span> <span class="pre">3</span></code> is evaluated first, and the result of that
-evaluation is compared to <code class="docutils literal"><span class="pre">0</span></code>.</p>
-<p>Within a group, elements are evaluated left to right in precedence
-order. For example, given the filter below:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">expression1</span> <span class="n">OR</span> <span class="n">expression2</span> <span class="n">AND</span> <span class="n">expression3</span><span class="p">)</span> <span class="n">OR</span> <span class="p">(</span><span class="n">expression4</span> <span class="n">AND</span>
-            <span class="n">NOT</span> <span class="n">expression5</span><span class="p">)</span> <span class="o">...</span>
-</pre></div>
-</div>
-<p>AMPS evaluates <code class="docutils literal"><span class="pre">expression2</span></code>, then <code class="docutils literal"><span class="pre">expression3</span></code> (since <code class="docutils literal"><span class="pre">AND</span></code> has
-higher precedence than <code class="docutils literal"><span class="pre">OR</span></code>), and if they evaluate to false, then
-<code class="docutils literal"><span class="pre">expression1</span></code> will be evaluated.</p>
-<p>AMPS does not guarantee that all parts of an expression will be
-evaluated if the result of an expression can be determined after only
-evaluating part of the expression. For example, given the expression:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">A_FUNCTION</span><span class="p">(</span><span class="o">/</span><span class="n">a</span><span class="p">)</span> <span class="n">OR</span> <span class="n">B_FUNCTION</span><span class="p">(</span><span class="o">/</span><span class="n">b</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>AMPS only guarantees that <code class="docutils literal"><span class="pre">B_FUNCTION(/b)</span></code> will be evaluated if
-<code class="docutils literal"><span class="pre">A_FUNCTION(/a)</span></code> returns <code class="docutils literal"><span class="pre">false</span></code>.</p>
-</div>
-<div class="section" id="logical-operators">
-<h3>Logical Operators<a class="headerlink" href="#logical-operators" title="Permalink to this headline">¶</a></h3>
-<p>The logical operators are <code class="docutils literal"><span class="pre">NOT</span></code>, <code class="docutils literal"><span class="pre">AND</span></code>, and <code class="docutils literal"><span class="pre">OR</span></code>, in order of
-precedence. These operators have the usual Boolean logic semantics.</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Instrmt</span><span class="o">/</span><span class="nd">@Sym</span> <span class="o">=</span> <span class="s1">&#39;IBM&#39;</span> <span class="n">OR</span> <span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Instrmt</span><span class="o">/</span><span class="nd">@Sym</span> <span class="o">=</span> <span class="s1">&#39;MSFT&#39;</span>
-</pre></div>
-</div>
-<p>As with other operators, you can use parentheses to group operators and
-affect the order of evaluation.</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span><span class="o">/</span><span class="n">orderType</span> <span class="o">=</span> <span class="s1">&#39;rush&#39;</span> <span class="n">AND</span> <span class="o">/</span><span class="n">customerType</span> <span class="n">IN</span> <span class="p">(</span><span class="s1">&#39;silver&#39;</span><span class="p">,</span> <span class="s1">&#39;gold&#39;</span><span class="p">)</span> <span class="p">)</span>
-<span class="n">OR</span>  <span class="o">/</span><span class="n">customerType</span> <span class="o">=</span> <span class="s1">&#39;platinum&#39;</span>
-</pre></div>
-</div>
-</div>
-<div class="section" id="arithmetic-operators">
-<h3>Arithmetic Operators<a class="headerlink" href="#arithmetic-operators" title="Permalink to this headline">¶</a></h3>
-<p>AMPS supports the arithmetic operators <code class="docutils literal"><span class="pre">+</span></code>, <code class="docutils literal"><span class="pre">-</span></code>, <code class="docutils literal"><span class="pre">*</span></code>, <code class="docutils literal"><span class="pre">/</span></code>,
-<code class="docutils literal"><span class="pre">%</span></code>, and <code class="docutils literal"><span class="pre">MOD</span></code> in expressions. The result of arithmetic operators
-where one of the operands is <code class="docutils literal"><span class="pre">NULL</span></code> is undefined and evaluates to
-<code class="docutils literal"><span class="pre">NULL</span></code>.</p>
-<p>AMPS distinguishes between floating point and integral types. When an
-arithmetic operator uses two different types, AMPS will convert the
-integral type to a floating point value as described in
-<a class="reference internal" href="#ug-numeric-types"><span class="std std-ref">Numeric Types and Literals</span></a>.</p>
-<p>Examples of filter expressions using arithmetic operators:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="mi">6</span> <span class="o">*</span> <span class="o">/</span><span class="mi">14</span> <span class="o">&lt;</span> <span class="mi">1000</span>
-<span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="nd">@Qty</span> <span class="o">*</span> <span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="nd">@Prc</span> <span class="o">&gt;=</span> <span class="mi">1000000</span>
-</pre></div>
-</div>
-<p>AMPS numeric types are signed, and the AMPS arithmetic operators
-correctly handle negative numbers. The <code class="docutils literal"><span class="pre">MOD</span></code> and <code class="docutils literal"><span class="pre">%</span></code> operators
-preserve the sign of the first argument to the operator. That is,
-<code class="docutils literal"><span class="pre">-5</span> <span class="pre">%</span> <span class="pre">3</span></code> produces a result of <code class="docutils literal"><span class="pre">-2</span></code>, while <code class="docutils literal"><span class="pre">5</span> <span class="pre">%</span> <span class="pre">-3</span></code> produces a
-result of <code class="docutils literal"><span class="pre">2</span></code>.</p>
-<div class="admonition caution">
-<p class="first admonition-title">Caution</p>
-<p class="last">When using mathematical operators in conjunction with filters,
-be careful about the placement of the operator. Some operators
-are used in the XPath expression as well as for mathematical
-operation (for example, the <code class="docutils literal"><span class="pre">'/'</span></code> operator in division).
-Therefore, it is important to separate mathematical operators
-with white space to prevent interpretation as an XPath
-expression.</p>
-</div>
-</div>
-<div class="section" id="comparison-operators">
-<h3>Comparison Operators<a class="headerlink" href="#comparison-operators" title="Permalink to this headline">¶</a></h3>
-<p>The comparison operators can be loosely grouped into equality
-comparisons and range comparisons. The basic equality comparison
-operators, in precedence order, are <code class="docutils literal"><span class="pre">==</span></code>, <code class="docutils literal"><span class="pre">=</span></code>, <code class="docutils literal"><span class="pre">&gt;</span></code>, <code class="docutils literal"><span class="pre">&gt;=</span></code>, <code class="docutils literal"><span class="pre">&lt;</span></code>,
-<code class="docutils literal"><span class="pre">&lt;=</span></code>, <code class="docutils literal"><span class="pre">!=</span></code>, and <code class="docutils literal"><span class="pre">&lt;&gt;</span></code>. The <code class="docutils literal"><span class="pre">==</span></code> comparison and the <code class="docutils literal"><span class="pre">=</span></code> comparison
-are treated as the same operator and produce the same results.</p>
-<p>If these binary operators are applied to two operands of different
-types, AMPS attempts to convert strings to numbers. If conversion
-succeeds, AMPS uses the numeric values. If conversion fails because the
-string cannot be meaningfully converted to a number, strings are always
-considered to be greater than numbers. The operators consider an empty
-string to be <code class="docutils literal"><span class="pre">NULL</span></code>.</p>
-<p>The following table shows some examples of how AMPS compares different
-types.</p>
-<table border="1" class="docutils" id="id7">
-<caption><span class="caption-text"><em>Comparison Operator Examples</em></span><a class="headerlink" href="#id7" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Expression</th>
-<th class="head">Result</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">1</span> <span class="pre">&lt;</span> <span class="pre">2</span></code></td>
-<td>TRUE</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">10</span> <span class="pre">&lt;</span> <span class="pre">'2'</span></code></td>
-<td>FALSE, &#8216;2&#8217; can be converted to a
-number</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">'2.000'</span> <span class="pre">&lt;&gt;</span> <span class="pre">'2.0'</span></code></td>
-<td>TRUE, no conversion to numbers since
-both are strings</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">2</span> <span class="pre">=</span> <span class="pre">2.0</span></code></td>
-<td>TRUE, numeric comparison</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">10</span> <span class="pre">&lt;</span> <span class="pre">'Crank</span> <span class="pre">It</span> <span class="pre">Up'</span></code></td>
-<td>TRUE, strings are greater than
-numbers</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">10</span> <span class="pre">&lt;</span> <span class="pre">''</span></code></td>
-<td>FALSE, an empty string is considered
-to be NULL</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">10</span> <span class="pre">&gt;</span> <span class="pre">''</span></code></td>
-<td>FALSE, an empty string is considered
-to be NULL</td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">''</span> <span class="pre">=</span> <span class="pre">''</span></code></td>
-<td>FALSE, an empty string is considered
-to be NULL</td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">''</span> <span class="pre">IS</span> <span class="pre">NULL</span></code></td>
-<td>TRUE, an empty string is considered
-to be NULL</td>
-</tr>
-</tbody>
-</table>
-<p>There are also set and range comparison operators. The <code class="docutils literal"><span class="pre">BETWEEN</span></code> operator
-can be used to check the range values.</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">The range used in the <code class="docutils literal"><span class="pre">BETWEEN</span></code> operator is inclusive of both
-operands, meaning the expression <code class="docutils literal"><span class="pre">/A</span> <span class="pre">BETWEEN</span> <span class="pre">0</span> <span class="pre">AND</span> <span class="pre">100</span></code> is
-equivalent to <code class="docutils literal"><span class="pre">/A</span> <span class="pre">&gt;=</span> <span class="pre">0</span> <span class="pre">AND</span> <span class="pre">/A</span> <span class="pre">&lt;=</span> <span class="pre">100</span></code></p>
-</div>
-<p>For example:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">OrdQty</span><span class="o">/</span><span class="nd">@Qty</span> <span class="n">BETWEEN</span> <span class="mi">0</span> <span class="n">AND</span> <span class="mi">10000</span>
-<span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="nd">@Px</span> <span class="n">NOT</span> <span class="n">BETWEEN</span> <span class="mf">90.0</span> <span class="n">AND</span> <span class="mf">90.5</span>
-<span class="p">(</span><span class="o">/</span><span class="n">price</span> <span class="o">*</span> <span class="o">/</span><span class="n">qty</span><span class="p">)</span> <span class="n">BETWEEN</span> <span class="mi">0</span> <span class="n">AND</span> <span class="mi">100000</span>
-</pre></div>
-</div>
-<p>The <code class="docutils literal"><span class="pre">IN</span></code> operator can be used to perform membership operations on sets
-of values. The <code class="docutils literal"><span class="pre">IN</span></code> operator returns true when the value on the left
-of the <code class="docutils literal"><span class="pre">IN</span></code> appears in the set of values in the <code class="docutils literal"><span class="pre">IN</span></code> clause. For
-example:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">Trade</span><span class="o">/</span><span class="n">OwnerID</span> <span class="n">NOT</span> <span class="n">IN</span> <span class="p">(</span><span class="s1">&#39;JMB&#39;</span><span class="p">,</span> <span class="s1">&#39;BLH&#39;</span><span class="p">,</span> <span class="s1">&#39;CJB&#39;</span><span class="p">)</span>
-<span class="o">/</span><span class="mi">21964</span> <span class="n">IN</span> <span class="p">(</span><span class="o">/</span><span class="mi">14</span><span class="o">*</span><span class="mi">5</span><span class="p">,</span> <span class="o">/</span><span class="mi">6</span><span class="o">*/</span><span class="mi">14</span><span class="p">,</span> <span class="mi">1000</span><span class="p">,</span> <span class="mi">2000</span><span class="p">)</span>
-<span class="o">/</span><span class="n">customer</span> <span class="n">IN</span> <span class="p">(</span><span class="s1">&#39;Bob&#39;</span><span class="p">,</span> <span class="s1">&#39;Phil&#39;</span><span class="p">,</span> <span class="s1">&#39;Brent&#39;</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>The <code class="docutils literal"><span class="pre">IN</span></code> operator returns true for the set of records that would be
-returned by an equivalent set of <code class="docutils literal"><span class="pre">=</span></code> comparisons joined by <code class="docutils literal"><span class="pre">OR</span></code>. The
-following two statements return the same set of records:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">pet</span> <span class="n">IN</span> <span class="p">(</span><span class="s1">&#39;puppy&#39;</span><span class="p">,</span> <span class="s1">&#39;kitten&#39;</span><span class="p">,</span> <span class="s1">&#39;goldfish&#39;</span><span class="p">)</span>
-</pre></div>
-</div>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span><span class="o">/</span><span class="n">pet</span> <span class="o">=</span> <span class="s1">&#39;puppy&#39;</span><span class="p">)</span> <span class="n">OR</span> <span class="p">(</span><span class="o">/</span><span class="n">pet</span> <span class="o">=</span> <span class="s1">&#39;kitten&#39;</span><span class="p">)</span> <span class="n">OR</span> <span class="p">(</span><span class="o">/</span><span class="n">pet</span> <span class="o">=</span> <span class="s1">&#39;goldfish)</span>
-</pre></div>
-</div>
-<p>This equivalence means that <code class="docutils literal"><span class="pre">NULL</span></code> values in either the field being
-evaluated, or the set of values provided to the <code class="docutils literal"><span class="pre">IN</span></code> clause, always return
-false.</p>
-<p>This also means that, for string values, the <code class="docutils literal"><span class="pre">IN</span></code> operator performs exact,
-case-sensitive matching.</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">When evaluating against a set of values, the <code class="docutils literal"><span class="pre">IN</span></code> operator
-typically provides better performance than using a set of <code class="docutils literal"><span class="pre">OR</span></code>
-operators. That is, a filter written as
-<code class="docutils literal"><span class="pre">/firstName</span> <span class="pre">IN</span> <span class="pre">('Joe',</span> <span class="pre">'Kathleen',</span> <span class="pre">'Frank',</span> <span class="pre">'Cindy',</span> <span class="pre">'Mortimer')</span></code>
-will typically perform better than an equivalent filter written
-as
-<code class="docutils literal"><span class="pre">/firstName</span> <span class="pre">=</span> <span class="pre">'Joe'</span> <span class="pre">OR</span> <span class="pre">/firstName</span> <span class="pre">=</span> <span class="pre">'Kathleen'</span> <span class="pre">OR</span> <span class="pre">/firstName</span> <span class="pre">=</span>
-<span class="pre">'Frank'</span> <span class="pre">OR</span> <span class="pre">/firstName</span> <span class="pre">=</span> <span class="pre">'Cindy'</span> <span class="pre">OR</span> <span class="pre">/firstName</span> <span class="pre">=</span> <span class="pre">'Mortimer'</span></code>.</p>
-</div>
-</div>
-<div class="section" id="regular-expression-matching">
-<span id="ug-filter-syntax-regular-expression"></span><h3>Regular Expression Matching<a class="headerlink" href="#regular-expression-matching" title="Permalink to this headline">¶</a></h3>
-<p>AMPS also provides a regular expression comparison operator, <code class="docutils literal"><span class="pre">LIKE</span></code>,
-to provide regular expression matching on string values. A <em>pattern</em> is
-used for the right side of the <code class="docutils literal"><span class="pre">LIKE</span></code> operator. A pattern must be
-provided as a literal, quoted value. For more on regular expressions and
-the <code class="docutils literal"><span class="pre">LIKE</span></code> comparison operator, please see the section on
-<a class="reference internal" href="#ug-regular-expressions"><span class="std std-ref">Using Regular Expressions in AMPS</span></a>.</p>
-<p>The string comparison operators described in the section called
-<a class="reference internal" href="amps_functions.html#ug-string-comparison-functions"><span class="std std-ref">String Comparison Functions</span></a> are usually more
-efficient than equivalent <code class="docutils literal"><span class="pre">LIKE</span></code> expressions, particularly when used
-to compare multiple literal patterns, or when the only purpose of the
-regular expression is to perform case-insensitive matching. Use <code class="docutils literal"><span class="pre">LIKE</span></code>
-operations when it is not practical to represent the filter condition
-with the string comparison operators.</p>
-<table border="1" class="docutils" id="id8">
-<caption><span class="caption-text"><em>AMPS regular expression comparison</em></span><a class="headerlink" href="#id8" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Function or Operator</th>
-<th class="head">Parameters</th>
-<th class="head">Description</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">LIKE</span></code></td>
-<td><p class="first">The string to be
-compared</p>
-<p class="last">The pattern to evaluate
-the string against</p>
-</td>
-<td><p class="first"><em>Case-sensitive</em></p>
-<p>Returns true if the
-string to be compared
-matches the pattern.</p>
-<p>For example, the
-following filter uses a
-PCRE backreference to
-return true for any
-message where the
-<code class="docutils literal"><span class="pre">/state</span></code> field
-contains two identical
-characters in a row.</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">state</span> <span class="n">LIKE</span> <span class="s1">&#39;(.)</span><span class="se">\1</span><span class="s1">&#39;</span>
-</pre></div>
-</div>
-<p class="last">This operator is not
-unicode-aware.</p>
-</td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="section" id="conditional-operators">
-<span id="index-7"></span><h3>Conditional Operators<a class="headerlink" href="#conditional-operators" title="Permalink to this headline">¶</a></h3>
-<p>AMPS contains support for a ternary conditional <code class="docutils literal"><span class="pre">IF</span></code> operator which
-allows for a Boolean condition to be evaluated to <code class="docutils literal"><span class="pre">true</span></code> or <code class="docutils literal"><span class="pre">false</span></code>,
-and will return one of the two parameters. The general format of the
-<code class="docutils literal"><span class="pre">IF</span></code> statement is</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">IF</span> <span class="p">(</span><span class="n">BOOLEAN_CONDITIONAL</span><span class="p">,</span> <span class="n">VALUE_TRUE</span><span class="p">,</span> <span class="n">VALUE_FALSE</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>In this example, the <code class="docutils literal"><span class="pre">BOOLEAN_CONDITIONAL</span></code> will be evaluated, and if
-the result is true, the <code class="docutils literal"><span class="pre">VALUE_TRUE</span></code> value will be returned otherwise
-the <code class="docutils literal"><span class="pre">VALUE_FALSE</span></code> will be returned.</p>
-<table border="1" class="docutils" id="id9">
-<caption><span class="caption-text"><em>AMPS if statement</em></span><a class="headerlink" href="#id9" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="33%" />
-<col width="33%" />
-<col width="33%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Function or Operator</th>
-<th class="head">Parameters</th>
-<th class="head">Description</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">IF</span></code></td>
-<td><p class="first">Conditional expression</p>
-<p>Value to return if
-conditional expression
-is true</p>
-<p class="last">Value to return if
-conditional expression
-is false</p>
-</td>
-<td><p class="first">Evaluate the conditional
-expression and return
-one of the two input
-values based on the
-results of the
-expression.</p>
-<p class="last">The AMPS expression
-engine can conditionally
-evaluate the terms
-provided to the <code class="docutils literal"><span class="pre">IF</span></code>
-statement in version
-5.3.4 and greater.
-In previous versions of
-AMPS, all expressions
-provided to the <code class="docutils literal"><span class="pre">IF</span></code>
-statement were fully
-evaluated before the
-<code class="docutils literal"><span class="pre">IF</span></code> statement
-was evaluated.</p>
-</td>
-</tr>
-</tbody>
-</table>
-<p>For example:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">SUM</span><span class="p">(</span> <span class="n">IF</span><span class="p">((</span> <span class="p">(</span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">OrdQty</span><span class="o">/</span><span class="nd">@Qty</span> <span class="o">&gt;</span> <span class="mi">500</span><span class="p">)</span> <span class="n">AND</span>
-          <span class="p">(</span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Instrmt</span><span class="o">/</span><span class="nd">@Sym</span> <span class="o">=</span><span class="s1">&#39;MSFT&#39;</span><span class="p">)),</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span> <span class="p">))</span>
-</pre></div>
-</div>
-<p>The above example returns a count of the total number of orders that
-have been placed where the symbol is MSFT and the order contains a
-quantity more than 500.</p>
-<p>The <code class="docutils literal"><span class="pre">IF</span></code> operator can also be used to evaluate results to determine if
-results are <code class="docutils literal"><span class="pre">NULL</span></code> or <code class="docutils literal"><span class="pre">NaN</span></code>. This is useful for calculating aggregates
-where some values may be <code class="docutils literal"><span class="pre">NULL</span></code> or <code class="docutils literal"><span class="pre">NaN</span></code>. The <code class="docutils literal"><span class="pre">NULL</span></code> and <code class="docutils literal"><span class="pre">NaN</span></code> values are
-discussed in more detail in the section called
-<a class="reference internal" href="#ug-null-nan"><span class="std std-ref">NULL, NaN, and IS NULL</span></a>.</p>
-<p>For example:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">SUM</span><span class="p">(</span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Instrmt</span><span class="o">/</span><span class="nd">@Qty</span> <span class="o">*</span> <span class="n">IF</span><span class="p">(</span>
-    <span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Instmt</span><span class="o">/</span><span class="nd">@Price</span> <span class="n">IS</span> <span class="n">NOT</span> <span class="n">NULL</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
-</pre></div>
-</div>
-</div>
-<div class="section" id="working-with-arrays">
-<h3>Working with Arrays<a class="headerlink" href="#working-with-arrays" title="Permalink to this headline">¶</a></h3>
-<p>AMPS supports filters that operate on arrays in messages. There are two
-simple principles behind how AMPS treats arrays:</p>
-<ol class="arabic simple" id="index-8">
-<li><em>Binary operators</em> that yield <code class="docutils literal"><span class="pre">true</span></code> or <code class="docutils literal"><span class="pre">false</span></code>
-(for example, <code class="docutils literal"><span class="pre">=</span></code>, <code class="docutils literal"><span class="pre">&lt;</span></code>, <code class="docutils literal"><span class="pre">LIKE</span></code>) are <em>array aware</em>, as is the
-<code class="docutils literal"><span class="pre">IN</span></code> operator. These operators work on arrays as a whole, and evaluate
-every element in the array.</li>
-<li><em>Arithmetic operators</em>, <em>functions</em>, <em>user-defined functions</em> and other
-<em>scalar operators</em>, are <em>not</em> array aware, and use the first element in
-the array.</li>
-</ol>
-<p>With these simple principles, you can predict how AMPS will
-evaluate an expression that uses an array. For any operator, an empty
-array evaluates to <code class="docutils literal"><span class="pre">NULL</span></code>.</p>
-<p>Let&#8217;s look at some examples. For the purposes of this section, we will
-consider the following JSON document:</p>
-<div class="highlight-javascript"><div class="highlight"><pre><span></span><span class="p">{</span>
-    <span class="s2">&quot;data&quot;</span>  <span class="o">:</span> <span class="p">[</span><span class="mf">1</span><span class="p">,</span> <span class="mf">2</span><span class="p">,</span> <span class="mf">3</span><span class="p">,</span> <span class="s2">&quot;zebra&quot;</span><span class="p">,</span> <span class="mf">5</span><span class="p">],</span>
-    <span class="s2">&quot;other&quot;</span> <span class="o">:</span> <span class="p">[</span><span class="mf">14</span><span class="p">,</span> <span class="mf">34</span><span class="p">,</span> <span class="mf">23</span><span class="p">,</span> <span class="mf">5</span><span class="p">]</span>
-<span class="p">}</span>
-</pre></div>
-</div>
-<p>While these arrays are presented using JSON format for simplicity, the
-same principles apply to arrays in other message formats.</p>
-<p>Here are some examples of ways to use an array in an AMPS filter:</p>
-<ol class="arabic">
-<li><p class="first">Determining if any element in an array meets a criteria. To determine
-this, you provide the identifier for the array, and use a comparison
-operator.</p>
-<table border="1" class="docutils" id="id10">
-<caption><span class="caption-text"><em>Match if any element matches</em></span><a class="headerlink" href="#id10" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Filter</th>
-<th class="head">Evaluates as</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">=</span> <span class="pre">1</span></code></td>
-<td>TRUE, <code class="docutils literal"><span class="pre">/data</span></code> contains <code class="docutils literal"><span class="pre">1</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">=</span> <span class="pre">'zebra'</span></code></td>
-<td>TRUE, <code class="docutils literal"><span class="pre">/data</span></code> contains <code class="docutils literal"><span class="pre">'zebra'</span></code></td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">!=</span> <span class="pre">'zebra'</span></code></td>
-<td>TRUE, <code class="docutils literal"><span class="pre">/data</span></code> contains an element
-that is not <code class="docutils literal"><span class="pre">'zebra'</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">=</span> <span class="pre">42</span></code></td>
-<td>FALSE, <code class="docutils literal"><span class="pre">/data</span></code> does not contain
-<code class="docutils literal"><span class="pre">42</span></code></td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">LIKE</span> <span class="pre">'z'</span></code></td>
-<td>TRUE, a member of <code class="docutils literal"><span class="pre">/data</span></code> matches
-<code class="docutils literal"><span class="pre">'z'</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">/other</span> <span class="pre">&gt;</span> <span class="pre">30</span></code></td>
-<td>TRUE, a member of <code class="docutils literal"><span class="pre">/other</span></code> is
-<code class="docutils literal"><span class="pre">&gt;</span> <span class="pre">30</span></code></td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/other</span> <span class="pre">&gt;</span> <span class="pre">50</span></code></td>
-<td>FALSE, no member of <code class="docutils literal"><span class="pre">/other</span></code> is
-<code class="docutils literal"><span class="pre">&gt;</span> <span class="pre">50</span></code></td>
-</tr>
-</tbody>
-</table>
-</li>
-<li><p class="first">Determine whether a specific value is at a specific position. To
-determine this, use the subscript operator <code class="docutils literal"><span class="pre">[]</span></code> on the XPath
-identifier to specify the position, and use the equality operator to
-check the value at that position.</p>
-<table border="1" class="docutils" id="id11">
-<caption><span class="caption-text"><em>Match if a value is at a specific position</em></span><a class="headerlink" href="#id11" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Filter</th>
-<th class="head">Evaluates as</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/data[0]</span> <span class="pre">=</span> <span class="pre">1</span></code></td>
-<td>TRUE, first element of <code class="docutils literal"><span class="pre">/data</span></code> is
-<code class="docutils literal"><span class="pre">1</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">/data[3]</span> <span class="pre">=</span> <span class="pre">&quot;zebra&quot;</span></code></td>
-<td>TRUE, fourth element of <code class="docutils literal"><span class="pre">/data</span></code> is
-<code class="docutils literal"><span class="pre">'zebra'</span></code></td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/data[1]</span> <span class="pre">!=</span> <span class="pre">1</span></code></td>
-<td>TRUE, second element of <code class="docutils literal"><span class="pre">/data</span></code> is
-not <code class="docutils literal"><span class="pre">1</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">/other[1]</span> <span class="pre">LIKE</span> <span class="pre">'4'</span></code></td>
-<td>TRUE, second element of <code class="docutils literal"><span class="pre">/other</span></code>
-matches <code class="docutils literal"><span class="pre">'4'</span></code></td>
-</tr>
-</tbody>
-</table>
-</li>
-<li><p class="first">Determine whether any value in one array is present in another array.</p>
-<table border="1" class="docutils" id="id12">
-<caption><span class="caption-text"><em>Match if any elements match</em></span><a class="headerlink" href="#id12" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Filter</th>
-<th class="head">Evaluates as</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">=</span> <span class="pre">/other</span></code></td>
-<td>TRUE, a value in <code class="docutils literal"><span class="pre">/data</span></code> equals a
-value in <code class="docutils literal"><span class="pre">/other</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">!=</span> <span class="pre">/other</span></code></td>
-<td>TRUE, a value in <code class="docutils literal"><span class="pre">/data</span></code> does not
-equal a value in <code class="docutils literal"><span class="pre">/other</span></code></td>
-</tr>
-</tbody>
-</table>
-</li>
-<li><p class="first">Determine whether an array contains one of a set of values.</p>
-<table border="1" class="docutils" id="id13">
-<caption><span class="caption-text"><em>Match if any of a set of values is present</em></span><a class="headerlink" href="#id13" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Filter</th>
-<th class="head">Evaluates as</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">3</span> <span class="pre">IN</span> <span class="pre">(/data)</span></code></td>
-<td>TRUE, <code class="docutils literal"><span class="pre">3</span></code> is a member of <code class="docutils literal"><span class="pre">/data</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">IN</span> <span class="pre">(1,</span> <span class="pre">2,</span> <span class="pre">3)</span></code></td>
-<td>TRUE, a member of <code class="docutils literal"><span class="pre">/data</span></code> is in
-<code class="docutils literal"><span class="pre">(1,</span> <span class="pre">2,</span> <span class="pre">3)</span></code></td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">/data</span> <span class="pre">IN</span> <span class="pre">(&quot;zebra&quot;,</span> <span class="pre">&quot;antelope&quot;,</span>
-<span class="pre">&quot;lion&quot;)</span></code></td>
-<td>TRUE, a member of <code class="docutils literal"><span class="pre">/data</span></code> is in
-<code class="docutils literal"><span class="pre">(&quot;zebra&quot;,</span> <span class="pre">&quot;antelope&quot;,</span> <span class="pre">&quot;lion&quot;)</span></code></td>
-</tr>
-</tbody>
-</table>
-</li>
-</ol>
-</div>
-<div class="section" id="working-with-timestamps">
-<h3>Working with Timestamps<a class="headerlink" href="#working-with-timestamps" title="Permalink to this headline">¶</a></h3>
-<p>AMPS does not include a dedicated timestamp data type. Instead, AMPS represents
-timestamps either as a <code class="docutils literal"><span class="pre">double</span></code> or a <code class="docutils literal"><span class="pre">string</span></code>.</p>
-<p>When representing timestamps as a <code class="docutils literal"><span class="pre">double</span></code>, AMPS uses standard UNIX timestamps.</p>
-<p>When representing timestamps as a <code class="docutils literal"><span class="pre">string</span></code>, AMPS formats strings in a format compliant
-with ISO-8601. The format AMPS uses was chosen to balance parsing speed, precision,
-readability, and bandwidth. The format uses:</p>
-<ul class="simple">
-<li>Basic format (no delimiters between parts of a date or time)</li>
-<li>Decimal fractional seconds (with <code class="docutils literal"><span class="pre">.</span></code> delimiting the fraction rather than <code class="docutils literal"><span class="pre">,</span></code>)</li>
-<li>Explicit <code class="docutils literal"><span class="pre">T</span></code> to separate date and time</li>
-<li>Explicit time zone specifier allowed, but not required</li>
-</ul>
-<p>A <code class="docutils literal"><span class="pre">string</span></code> timestamp has the format of <code class="docutils literal"><span class="pre">YYYYmmddTHHMMSS[Z]</span></code> where:</p>
-<ul class="simple">
-<li><code class="docutils literal"><span class="pre">YYYY</span></code> is the four digit year</li>
-<li><code class="docutils literal"><span class="pre">mm</span></code> is the two digit month</li>
-<li><code class="docutils literal"><span class="pre">dd</span></code> is the two digit day</li>
-<li><code class="docutils literal"><span class="pre">T</span></code> is the character separator between the date and time</li>
-<li><code class="docutils literal"><span class="pre">HH</span></code> is the two digit hour</li>
-<li><code class="docutils literal"><span class="pre">MM</span></code> is the two digit minute</li>
-<li><code class="docutils literal"><span class="pre">SS</span></code> is the two digit second</li>
-<li><code class="docutils literal"><span class="pre">Z</span></code> is an optional timezone specifier. AMPS timestamps are always
-in UTC, regardless of whether the timezone is included. AMPS only
-accepts a literal value of <code class="docutils literal"><span class="pre">Z</span></code> for a timezone specifier.</li>
-</ul>
-<p>For example, a timestamp for January 2nd, 2015, at 12:35:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="mi">20150102</span><span class="n">T123500Z</span>
-</pre></div>
-</div>
-<p>Timestamps in string format are used for point-in-time bookmarks, as
-explicit time specifiers in configuration files, in the <code class="docutils literal"><span class="pre">timestamp</span></code>
-header optionally returned on AMPS messages, and so on.</p>
-<p>The timestamp format AMPS uses was chosen to make string comparisons
-for timestamps work as expected, including simple comparisons like
-<code class="docutils literal"><span class="pre">&lt;</span></code> and <code class="docutils literal"><span class="pre">&gt;</span></code>, as well as more sophisticated comparisons like the
-<code class="docutils literal"><span class="pre">BETWEEN</span></code> operator.</p>
-<p>AMPS provides functions to convert between <code class="docutils literal"><span class="pre">string</span></code> representation
-of a timestamp and the <code class="docutils literal"><span class="pre">double</span></code> representation of a timestamp,
-as described in <a class="reference internal" href="amps_functions.html#ug-date-and-time-functions"><span class="std std-ref">Date and Time Functions</span></a>.</p>
-</div>
-</div>
-<div class="section" id="using-regular-expressions-in-amps">
-<span id="regular-expressions"></span><span id="ug-regular-expressions"></span><span id="index-9"></span><h2>Using Regular Expressions in AMPS<a class="headerlink" href="#using-regular-expressions-in-amps" title="Permalink to this headline">¶</a></h2>
-<p>Regular expression matching provides precision, power, and flexibility
-for matching patterns. AMPS supports regular expression matching on
-topics and within content filters. Regular expressions are implemented
-in AMPS using the Perl-Compatible Regular Expressions (PCRE) library.
-For a complete definition of the supported regular expression syntax,
-please refer to:</p>
-<p><a class="reference external" href="http://perldoc.perl.org/perlre.html">http://perldoc.perl.org/perlre.html</a></p>
-<p>To use regular expressions for topic matching, provide a regular
-expression pattern where you would normally provide a topic name.</p>
-<p>To use regular expressions in content filtering, compare strings to
-regular expressions using the <code class="docutils literal"><span class="pre">LIKE</span></code> operator. The syntax of the
-<code class="docutils literal"><span class="pre">LIKE</span></code> operator is:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="n">string</span> <span class="n">LIKE</span> <span class="n">pattern</span>
-</pre></div>
-</div>
-<p>In this context, a string is any expression that provides a string and pattern is
-a literal regular expression pattern.</p>
-<p>This chapter presents a brief overview of regular expressions in AMPS.
-However, this chapter is not exhaustive. For more information on regular
-expression matching, see the PCRE site mentioned above.</p>
-<div class="section" id="examples">
-<h3>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
-<p>Here is an example of a content filter for messages that will match any
-message meeting the following criteria:</p>
-<ul class="simple">
-<li>Regular expression match of symbols of 2 or 3 characters starting
-with “IB”</li>
-<li>Regular expression match of prices starting with “90”</li>
-<li>Numeric comparison of prices less than 91</li>
-</ul>
-<p>The corresponding content filter would be:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="n">Instrmt</span><span class="o">/</span><span class="nd">@Sym</span> <span class="n">LIKE</span> <span class="s2">&quot;^IB.?$&quot;</span><span class="p">)</span> <span class="n">AND</span>
-<span class="p">(</span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="nd">@Px</span> <span class="n">LIKE</span> <span class="s2">&quot;^90\..*&quot;</span> <span class="n">AND</span> <span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Order</span><span class="o">/</span><span class="nd">@Px</span> <span class="o">&lt;</span> <span class="mf">91.0</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>The tables below (
-<a class="reference internal" href="#table-regex-meta-chars"><span class="std std-ref">Regular Expression Meta-characters</span></a>,
-<a class="reference internal" href="#table-regex-repetition-constructs"><span class="std std-ref">Regular Expression Repetition Constructs</span></a>, and
-<a class="reference internal" href="#table-regex-behavior-modifiers"><span class="std std-ref">Regular Expression Behavior Modifiers</span></a>
-) contain a brief summary of special characters and constructs available within regular expressions.</p>
-<p>Here are more examples of using regular expressions within AMPS:</p>
-<p id="index-10">Use <code class="docutils literal"><span class="pre">(?i)</span></code> to enable case-insensitive regular expression searching. For example, the following
-filter will be true regardless if <code class="docutils literal"><span class="pre">/client/country</span></code> contains “US” or
-“us”.</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span><span class="o">/</span><span class="n">client</span><span class="o">/</span><span class="n">country</span> <span class="n">LIKE</span> <span class="s2">&quot;(?i)ˆus$&quot;</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>To match messages where tag 55 has a <code class="docutils literal"><span class="pre">TRADE</span></code> suffix, use the following
-filter:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span><span class="o">/</span><span class="mi">55</span> <span class="n">LIKE</span> <span class="s2">&quot;TRADE$&quot;</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>To match messages where tag 109 has a <code class="docutils literal"><span class="pre">US</span></code> prefix and a <code class="docutils literal"><span class="pre">TRADE</span></code>
-suffix, with case insensitive matching, use the following filter:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="p">(</span><span class="o">/</span><span class="mi">109</span> <span class="n">LIKE</span> <span class="s2">&quot;(?i)ˆUS.*TRADE$&quot;</span><span class="p">)</span>
-</pre></div>
-</div>
-<span id="table-regex-meta-chars"></span><table border="1" class="docutils" id="id14">
-<caption><span class="caption-text"><em>Regular Expression Meta-characters</em></span><a class="headerlink" href="#id14" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head"><strong>Characters</strong></th>
-<th class="head"><strong>Meaning</strong></th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td>^</td>
-<td>Beginning of string</td>
-</tr>
-<tr class="row-odd"><td>$</td>
-<td>End of string</td>
-</tr>
-<tr class="row-even"><td>.</td>
-<td>Any character except a newline</td>
-</tr>
-<tr class="row-odd"><td>*</td>
-<td>Match previous 0 or more times</td>
-</tr>
-<tr class="row-even"><td>?</td>
-<td>Match previous 0 or 1 times</td>
-</tr>
-<tr class="row-odd"><td>|</td>
-<td>The previous is an alternative to the following</td>
-</tr>
-<tr class="row-even"><td>()</td>
-<td>Grouping of expression</td>
-</tr>
-<tr class="row-odd"><td>[]</td>
-<td>Set of characters</td>
-</tr>
-<tr class="row-even"><td>{}</td>
-<td>Repetition modifier</td>
-</tr>
-<tr class="row-odd"><td>\</td>
-<td>Escape for special characters</td>
-</tr>
-</tbody>
-</table>
-<span id="table-regex-repetition-constructs"></span><table border="1" class="docutils" id="id15">
-<caption><span class="caption-text"><em>Regular Expression Repetition Constructs</em></span><a class="headerlink" href="#id15" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head"><strong>Construct</strong></th>
-<th class="head"><strong>Meaning</strong></th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><em>a</em>*</td>
-<td>Zero or more <em>a</em>&#8216;s</td>
-</tr>
-<tr class="row-odd"><td><em>a</em>?</td>
-<td>Zero or one <em>a</em>&#8216;s</td>
-</tr>
-<tr class="row-even"><td><em>a</em>{<em>m</em>}</td>
-<td>Exactly <em>m a</em>&#8216;s</td>
-</tr>
-<tr class="row-odd"><td><em>a</em>{<em>m</em>,}</td>
-<td>At least <em>m a</em>&#8216;s</td>
-</tr>
-<tr class="row-even"><td><em>a</em>{<em>m</em>,<em>n</em>}</td>
-<td>At least <em>m</em>, but no more than <em>n a</em>&#8216;s</td>
-</tr>
-</tbody>
-</table>
-<span id="table-regex-behavior-modifiers"></span><table border="1" class="docutils" id="id16">
-<caption><span class="caption-text"><em>Regular Expression Behavior Modifiers</em></span><a class="headerlink" href="#id16" title="Permalink to this table">¶</a></caption>
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head"><strong>Modifier</strong></th>
-<th class="head"><strong>Meaning</strong></th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td>i</td>
-<td>Case insensitive search</td>
-</tr>
-<tr class="row-odd"><td>m</td>
-<td>Multi-line search</td>
-</tr>
-<tr class="row-even"><td>s</td>
-<td>Any character (including newlines) can be matched by a .
-character</td>
-</tr>
-<tr class="row-odd"><td>x</td>
-<td>Unescaped white space is ignored in the pattern</td>
-</tr>
-<tr class="row-even"><td>A</td>
-<td>Constrain the pattern to only match the beginning of a
-string</td>
-</tr>
-<tr class="row-odd"><td>U</td>
-<td>Make the quantifiers non-greedy by default (the
-quantifiers are greedy and try to match as much as
-possible by default)</td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="section" id="raw-strings">
-<h3>Raw Strings<a class="headerlink" href="#raw-strings" title="Permalink to this headline">¶</a></h3>
-<p id="index-11">AMPS additionally provides support for <em>raw strings</em>, which are strings
-prefixed by an &#8216;r&#8217; or &#8216;R&#8217; character. Raw strings use different rules for
-how a backslash escape sequence is interpreted by the parser. When a
-string literal is provided as a raw string, the characters in the raw
-string are matched exactly, even when those characters are special
-characters for a regular expression.</p>
-<p>In the example below, the raw string - noted by the <code class="docutils literal"><span class="pre">r</span></code> prefix of the
-string literal in the second operand of the <code class="docutils literal"><span class="pre">LIKE</span></code> predicate (
-<a class="reference internal" href="#listing-raw-string"><span class="std std-ref">Raw String Example</span></a>
-) - causes AMPS to search for the literal characters
-<code class="docutils literal"><span class="pre">++</span></code> in the results, without requiring those characters to be escaped (
-<a class="reference internal" href="#listing-regular-string"><span class="std std-ref">Regular String Example</span></a>
-). In this example we are querying for a string that
-contains the programming language named C++. In the regular string, we
-are required to escape the <code class="docutils literal"><span class="pre">'+'</span></code> character since it is also used in a
-regular expression as the “match previous 1 or more times” regular
-expression character. In the raw string we can use <code class="docutils literal"><span class="pre">r'C++'</span></code> to search
-for the string and not have to escape the special <code class="docutils literal"><span class="pre">'+'</span></code> character.</p>
-<div class="code highlight-default" id="listing-raw-string"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Language</span> <span class="n">LIKE</span> <span class="sa">r</span><span class="s1">&#39;C++&#39;</span>
-</pre></div>
-</div>
-<p><em>Raw String Example</em></p>
-<div class="code highlight-default" id="listing-regular-string"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">FIXML</span><span class="o">/</span><span class="n">Language</span> <span class="n">LIKE</span> <span class="s1">&#39;C\+\+&#39;</span>
-</pre></div>
-</div>
-<p><em>Regular String Example</em></p>
-</div>
-<div class="section" id="subscribing-to-a-set-of-topics-using-regular-expressions">
-<span id="ug-regex-sub"></span><h3>Subscribing to a Set of Topics Using Regular Expressions<a class="headerlink" href="#subscribing-to-a-set-of-topics-using-regular-expressions" title="Permalink to this headline">¶</a></h3>
-<p>As mentioned previously, AMPS supports regular expression filtering for
-topics, in addition to content filters. Regular expressions use the same
-grammar described in content filtering. Regular expression matching for
-topics is enabled in an AMPS instance by default.</p>
-<p>Subscriptions or queries that use a regular expression for the topic
-name provide all matching records from AMPS topics where the name of the
-topic matches the regular expression used for the subscription or query.
-For example, if your AMPS configuration has three SOW topics,
-<code class="docutils literal"><span class="pre">Topic_A</span></code>, <code class="docutils literal"><span class="pre">Topic_B</span></code> and <code class="docutils literal"><span class="pre">Topic_C</span></code> and you wish to search for all
-messages in all of your SOW topics for records where the <code class="docutils literal"><span class="pre">Name</span></code> field
-is equal to “Bob”, then you could use a <code class="docutils literal"><span class="pre">sow</span></code> command with a topic of
-<code class="docutils literal"><span class="pre">^Topic_.*</span></code> and a filter of <code class="docutils literal"><span class="pre">/FIXML/&#64;Name='Bob'</span></code> to return all
-matching messages that match the filter in all of the topics that match
-the topic regular expression.</p>
-<p>Notice that, as with the <code class="docutils literal"><span class="pre">LIKE</span></code> expression, a regular expression
-will match at any position in the topic name. To anchor the match
-to the beginning of the string, use the <code class="docutils literal"><span class="pre">^</span></code> directive at the
-beginning of the regular expression. To anchor the match to the
-end of the string, use the <code class="docutils literal"><span class="pre">$</span></code> directive at the end of the string.</p>
-<p>For example, to match a topic with <code class="docutils literal"><span class="pre">&quot;order&quot;</span></code> anywhere in the topic
-name, you could use the regular expression <code class="docutils literal"><span class="pre">order.*</span></code>  (the
-ending <code class="docutils literal"><span class="pre">.*</span></code> matches zero or more characters, but lets AMPS know
-to interpret this as a regular expression). To match only
-topics that start with <code class="docutils literal"><span class="pre">order</span></code>, you would use the regular expression
-<code class="docutils literal"><span class="pre">^order</span></code>.  To match topics that end with <code class="docutils literal"><span class="pre">order</span></code>, you would
-use the regular expression <code class="docutils literal"><span class="pre">order$</span></code>.</p>
-<div class="admonition tip">
-<p class="first admonition-title">Tip</p>
-<p class="last">Results returned when performing a topic regular expression
-query will follow “configuration order” — meaning that the
-topics will be searched in the order that they appear in your
-AMPS configuration file. Using the above query example with
-<code class="docutils literal"><span class="pre">Topic_A</span></code>, <code class="docutils literal"><span class="pre">Topic_B</span></code> and <code class="docutils literal"><span class="pre">Topic_C</span></code>, if the configuration
-file has these topics in that exact order, the results will be
-returned first from <code class="docutils literal"><span class="pre">Topic_A</span></code>, then from <code class="docutils literal"><span class="pre">Topic_B</span></code> and
-finally the results from <code class="docutils literal"><span class="pre">Topic_C</span></code>. As with other queries,
-AMPS does not make any guarantees about the ordering of results
-within any given topic query.</p>
-</div>
-</div>
-</div>
-<div class="section" id="performance-considerations">
-<h2>Performance Considerations<a class="headerlink" href="#performance-considerations" title="Permalink to this headline">¶</a></h2>
-<p>This section describes general performance considerations for the AMPS
-expression language and content filters. The considerations here are aspects
-of AMPS performance to be aware of in the general case. However, since the
-AMPS expression language operates on specific data, the structure and size
-of the messages that your application uses may have more effect on overall
-performance than the specific expressions used.  For example, parsing and
-filtering a 20MB XML document is inherently more expensive than parsing
-and filtering a 400 byte BFlat document.</p>
-<div class="section" id="use-short-circuiting">
-<h3>Use Short-Circuiting<a class="headerlink" href="#use-short-circuiting" title="Permalink to this headline">¶</a></h3>
-<p>When clauses in an expression are joined by <code class="docutils literal"><span class="pre">OR</span></code>, AMPS will only
-evaluate the right side of an <code class="docutils literal"><span class="pre">OR</span></code> expression if the left side
-of the expression is false.</p>
-<p>When constructing an expression, this means that there can be a
-performance advantage to having relatively less expensive clauses
-on the left hand sides of the <code class="docutils literal"><span class="pre">OR</span></code>. For example, in the
-following clause:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">code</span> <span class="o">=</span> <span class="s1">&#39;restricted&#39;</span> <span class="n">OR</span> <span class="o">/</span><span class="n">notes</span> <span class="n">LIKE</span> <span class="s1">&#39;restricted|limited&#39;</span>
-</pre></div>
-</div>
-<p>The regular expression comparison is only evaluated if the comparison
-<code class="docutils literal"><span class="pre">/code</span> <span class="pre">=</span> <span class="pre">'restricted'</span></code> is false. If the comparison is true, then
-the overall clause is true and there is no need to evaluate the
-regular expression.</p>
-</div>
-<div class="section" id="avoid-redundant-expressions">
-<h3>Avoid Redundant Expressions<a class="headerlink" href="#avoid-redundant-expressions" title="Permalink to this headline">¶</a></h3>
-<p>AMPS does not reorder or recombine complex expressions. Where feasible,
-your application can save work at the server by combining expressions.
-In particular, if an application is constructing a filter by reading
-options from various sources, performance can be improved by combining
-the queries.</p>
-<p>For example, in a filter like the following:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="nb">id</span> <span class="o">=</span> <span class="s1">&#39;12345&#39;</span> <span class="n">OR</span> <span class="o">/</span><span class="nb">id</span> <span class="n">IN</span> <span class="p">(</span><span class="s1">&#39;12345&#39;</span><span class="p">,</span><span class="s1">&#39;23456&#39;</span><span class="p">,</span><span class="s1">&#39;34567&#39;</span><span class="p">,</span><span class="s1">&#39;45678&#39;</span><span class="p">)</span>
-              <span class="n">OR</span> <span class="o">/</span><span class="nb">id</span> <span class="n">IN</span> <span class="p">(</span><span class="s1">&#39;12345&#39;</span><span class="p">,</span><span class="s1">&#39;45678&#39;</span><span class="p">,</span><span class="s1">&#39;90909&#39;</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>The comparison against <code class="docutils literal"><span class="pre">'12345'</span></code> will be evaluated three times in cases where
-the value of <code class="docutils literal"><span class="pre">/id</span></code> does not match any of the values in the filter.</p>
-<p>This filter is equivalent to:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="nb">id</span> <span class="n">IN</span> <span class="p">(</span><span class="s1">&#39;12345&#39;</span><span class="p">,</span><span class="s1">&#39;23456&#39;</span><span class="p">,</span><span class="s1">&#39;34567&#39;</span><span class="p">,</span><span class="s1">&#39;45678&#39;</span><span class="p">,</span><span class="s1">&#39;90909&#39;</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>The same results are produced, but only evaluates the <code class="docutils literal"><span class="pre">/id</span></code> field against
-a given value one time.</p>
-</div>
-<div class="section" id="use-specialized-operators-for-simple-comparisons-use-like-when-necessary">
-<h3>Use Specialized Operators for Simple Comparisons, Use LIKE when Necessary<a class="headerlink" href="#use-specialized-operators-for-simple-comparisons-use-like-when-necessary" title="Permalink to this headline">¶</a></h3>
-<p>The <code class="docutils literal"><span class="pre">LIKE</span></code> operator offers access to full Perl-Compatible Regular
-Expressions within the AMPS expression language. This flexibility
-allows for very precise filtering, and the PCRE engine performs
-well.</p>
-<p>However, for comparisons for which AMPS provides a named function,
-the named function is highly-optimized and will perform somewhat
-better than the general-purpose regular expression engine.</p>
-<p>For example, given a choice between two equivalent
-expressions:</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">state</span> <span class="n">BEGINS</span> <span class="n">WITH</span><span class="p">(</span><span class="s1">&#39;North&#39;</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>and</p>
-<div class="code highlight-default"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">state</span> <span class="n">LIKE</span> <span class="s1">&#39;^North&#39;</span>
-</pre></div>
-</div>
-<p>The version that uses <code class="docutils literal"><span class="pre">BEGINS</span> <span class="pre">WITH</span></code> will typically perform slightly
-better than the version that uses the regular expression.</p>
-<p>This doesn&#8217;t mean that regular expressions or the <code class="docutils literal"><span class="pre">LIKE</span></code> operator
-perform poorly. The <code class="docutils literal"><span class="pre">LIKE</span></code> operator can efficiently match patterns
-that would be difficult or impossible to match using the other operators.
-However, for very simple comparisons where AMPS provides a dedicated
-operator, that operator typically performs slightly better than a regular
-expression.</p>
-<p>The following table shows some examples of regular expressions and the AMPS operator
-equivalent.</p>
-<table border="1" class="docutils">
-<colgroup>
-<col width="50%" />
-<col width="50%" />
-</colgroup>
-<thead valign="bottom">
-<tr class="row-odd"><th class="head">Regular Expression</th>
-<th class="head">AMPS Operator Equivalent</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">^something</span></code></td>
-<td><code class="docutils literal"><span class="pre">BEGINS</span> <span class="pre">WITH('something')</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">something$</span></code></td>
-<td><code class="docutils literal"><span class="pre">ENDS</span> <span class="pre">WITH</span> <span class="pre">('something')</span></code></td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">something</span></code></td>
-<td><code class="docutils literal"><span class="pre">INSTR(/field,</span> <span class="pre">'something')</span> <span class="pre">!=</span> <span class="pre">0</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">(?i)something</span></code></td>
-<td><code class="docutils literal"><span class="pre">INSTR_I(/field,</span> <span class="pre">'something')</span> <span class="pre">!=</span> <span class="pre">0</span></code></td>
-</tr>
-<tr class="row-even"><td><code class="docutils literal"><span class="pre">(?i)^something$</span></code></td>
-<td><code class="docutils literal"><span class="pre">STREQUAL_I(/field,</span> <span class="pre">'something')</span> <span class="pre">!=</span> <span class="pre">0</span></code></td>
-</tr>
-<tr class="row-odd"><td><code class="docutils literal"><span class="pre">^a$|^b$|^c$</span></code></td>
-<td><code class="docutils literal"><span class="pre">IN</span> <span class="pre">('a','b','c')</span></code></td>
-</tr>
-</tbody>
-</table>
-<p><em>Regular expressions and operators</em></p>
-</div>
-<div class="section" id="optimize-for-partial-parsing">
-<h3>Optimize for Partial Parsing<a class="headerlink" href="#optimize-for-partial-parsing" title="Permalink to this headline">¶</a></h3>
-<p>Most AMPS message types have the ability to <em>partially parse</em> messages.
-That is, rather than parsing the entire message, the message type can
-simply find the identifiers that will be used, and stop the parsing
-process as soon as those identifiers are found.</p>
-<p>This optimization is most useful for larger messages. For example,
-if the SOW key for a topic is based on the <code class="docutils literal"><span class="pre">/id</span></code> field of a message and
-there are active content filters that use both the <code class="docutils literal"><span class="pre">/id</span></code> field and the
-<code class="docutils literal"><span class="pre">/code</span></code> field, while no other field is being indexed, then, considering
-the message below:</p>
-<div class="code js highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s2">&quot;id&quot;</span><span class="p">:</span><span class="mi">24</span><span class="p">,</span><span class="s2">&quot;code&quot;</span><span class="p">:</span><span class="s2">&quot;A12347&quot;</span><span class="p">,</span><span class="s2">&quot;notes&quot;</span><span class="p">:</span><span class="s2">&quot;entered on behalf of a sloth&quot;</span><span class="p">,</span>
-     <span class="o">//</span> <span class="o">...</span> <span class="mi">100</span><span class="n">K</span> <span class="n">of</span> <span class="n">other</span> <span class="n">data</span> <span class="o">...</span>
-<span class="p">}</span>
-</pre></div>
-</div>
-<p>The AMPS parser can stop parsing after processing only the <code class="docutils literal"><span class="pre">/id</span></code> and the
-<code class="docutils literal"><span class="pre">/code</span></code> fields. In this case, halting the parsing after processing these two
-fields avoids the expense of parsing the remaining parts of the message.</p>
-<p>Notice that this optimization will only improve performance in cases
-where AMPS doesn&#8217;t need to parse the entire message. For example, if
-there is a <code class="docutils literal"><span class="pre">delta_subscribe</span></code> active for the topic, or if the
-command being processed is a <code class="docutils literal"><span class="pre">delta_publish</span></code>, AMPS will parse the
-message completely to be able to calculate the deltas. Likewise, if
-any filter refers to a field that doesn&#8217;t appear in the message,
-AMPS will parse the message completely to be able to determine that
-the field does not appear in the message.</p>
-</div>
-<div class="section" id="sow-queries-and-indexing">
-<h3>SOW Queries and Indexing<a class="headerlink" href="#sow-queries-and-indexing" title="Permalink to this headline">¶</a></h3>
-<p>Queries over topics in the State of the World (SOW) have additional performance
-considerations. AMPS maintains indexes over SOW topics to help locate messages
-in response to a query.</p>
-<ul class="simple">
-<li>Queries over a topic in the SOW can use SOW topic indexes. Where
-possible, use an exact string match and create a hash index to
-take advantage of hash indexes.</li>
-<li>When a query is submitted with an XPath identifier for which no index
-exists, AMPS will create and populate a memo index for that XPath
-identifier. This can add to the amount of time a query takes the
-first time a given XPath identifier is queried. You can specify that
-AMPS creates a memo index for a given identifier by using the
-<code class="docutils literal"><span class="pre">Index</span></code> configuration item in the <code class="docutils literal"><span class="pre">Topic</span></code> definition. Once
-an index is created, AMPS will continue to search for that XPath
-identifier in incoming messages for that topic to keep the index
-up to date.</li>
-</ul>
-<p>Notice that SOW topic indexes are only used for <code class="docutils literal"><span class="pre">sow</span></code> commands and during
-the <code class="docutils literal"><span class="pre">sow</span></code> portion of a <code class="docutils literal"><span class="pre">sow_and_subscribe</span></code> (or <code class="docutils literal"><span class="pre">sow_and_delta_subscribe</span></code>)
-command. Once the subscription to current updates begins, the subscription
-does not use a SOW topic index because there is no need to locate
-a message. During a subscription, filters are run against the current
-message.</p>
-<p>See <a class="reference internal" href="sow.html#ug-sow-indexing"><span class="std std-ref">SOW Indexing</span></a> for details.</p>
-</div>
-</div>
-</div>
-          </div>
-        </div>
-      </div>
-    <div class="clearer"></div>
-  </div>
-    <div class="footer">
-      &copy;2023 60East Technologies, Inc. (version develop).
-      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 1.5.3</a>
-      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.10</a>
-    </div>
-  </body>
-</html>

amps-python-client 5.3.4.1__zip → 5.3.4.2__zip

amps-python-client 5.3.4.1zip → 5.3.4.2zip