{% extends "rest_framework/api_basics.html" %}

{% block description %}


<p>
Some API operations allow the results to be filtered according to flexible conditions. The basic syntax for filtering objects is:
</p>

<p>
    <code>
    &lt;url&gt;?&lt;field name&gt;=&lt;oper&gt;:&lt;value&gt;[&amp;&lt;field name&gt;=&lt;oper&gt;:&lt;value&gt;]*
    </code>
</p>

<p>For example:</p>
<p>
    <code>
    /api/rest/systems/1007/annotations/?description=like:important&amp;timestamp=between:[2016-12-01,2016-12-07]
    </code>
</p>

<p>
The specific fields that can be used depend on the objects in question. Please refer to the documentation
of each request for the list of valid fields.
</p>

<p>
These are the operators that can be used in filters:
</p>

<table class="table table-bordered">
    <tbody>
        <tr>
            <th>Operator</th>
            <th>Acceptable value</th>
            <th>Comments</th>
        </tr>
        <tr>
            <td>eq</td>
            <td>number/string/timestamp</td>
            <td>This is the default operator if one is not specified.</td>
        </tr>
        <tr>
            <td>ne</td>
            <td>number/string/timestamp</td>
            <td>&nbsp;</td>
        </tr>
        <tr>
            <td>lt</td>
            <td>number/string/timestamp</td>
            <td>&nbsp;</td>
        </tr>
        <tr>
            <td>le</td>
            <td>number/string/timestamp</td>
            <td>&nbsp;</td>
        </tr>
        <tr>
            <td>gt</td>
            <td>number/string/timestamp</td>
            <td>&nbsp;</td>
        </tr>
        <tr>
            <td>ge</td>
            <td>number/string/timestamp</td>
            <td>&nbsp;</td>
        </tr>
        <tr>
            <td>in</td>
            <td>list</td>
            <td>Input list is val1, val2,.. which can be enclosed with () or [] or not enclosed at all.</td>
        </tr>
        <tr>
            <td>out</td>
            <td>list</td>
            <td>Input list is val1, val2,.. which can be enclosed with () or [] or not enclosed at all.</td>
        </tr>
        <tr>
            <td>between</td>
            <td>list</td>
            <td><p>A list of exactly two items, e.g. [5,10]; the filter is inclusive, equivalent to x &gt;= 5 AND y &lt;= 10.</p>
                <p>The between filter is symmetric, e.g. between[5,10] and between[10,5] mean the same thing.</p></td>
        </tr>
        <tr>
            <td>like</td>
            <td>string</td>
            <td>Searches for a substring anywhere inside the text.</td>
        </tr>
    </tbody>
</table>

<p>Notes:</p>
<ul>
    <li>When filtering on more than one field, the conditions are ANDed together.</li>
    <li>String comparisons are case sensitive except for the <tt>like</tt> operator.</li>
    <li>Timestamps are always in UTC, and should be specified in ISO-8601 format: <tt>yyyy-mm-dd[Thh:mm[:ss][Z]]</tt>.
        <br>For example 2016-01-17 or 2016-12-31T23:59:59</li>
</ul>

Next: <a href="/api/docs/sorting/">Sorting &raquo;</a>

{% endblock %}