.. _apiug-workdjangofilter:

Filter Qualifiers
=================

When specifying selection criteria using field-value pair parameters, these qualifiers can be applied to field values to filter results.

See `QuerySet API reference - Field lookups <https://docs.djangoproject.com/en/dev/ref/models/querysets/#field-lookups>`_ for a detailed description of each qualifier in the Django documentation.

Syntax
------
 ::
 
	<field>__<qualifier>=<value>

**Note:** There are *two* underscore characters between the field and qualifier names.

Qualifiers
----------


**Important:** The datatype of the specified value(s) must match the expected field datatype.

+-----------------------+---------------------------+-------------------------+---------------------------+
| :ref:`djfilt-exact`   |  :ref:`djfilt-iexact`     | :ref:`djfilt-contains`  |  :ref:`djfilt-icontains`  |
+-----------------------+---------------------------+-------------------------+---------------------------+
| :ref:`djfilt-in`      |  :ref:`djfilt-gt`         | :ref:`djfilt-gte`       |  :ref:`djfilt-lt`         |
+-----------------------+---------------------------+-------------------------+---------------------------+
| :ref:`djfilt-lte`     |  :ref:`djfilt-startswith` |:ref:`djfilt-istartswith`|  :ref:`djfilt-endswith`   |
+-----------------------+---------------------------+-------------------------+---------------------------+
|:ref:`djfilt-iendswith`|  :ref:`djfilt-range`      | :ref:`djfilt-year`      |  :ref:`djfilt-month`      |
+-----------------------+---------------------------+-------------------------+---------------------------+
| :ref:`djfilt-day`     |  :ref:`djfilt-weekday`    | :ref:`djfilt-isnull`    |  :ref:`djfilt-search`     |
+-----------------------+---------------------------+-------------------------+---------------------------+
| :ref:`djfilt-regex`   |  :ref:`djfilt-iregex`     | --                      |  --                       |
+-----------------------+---------------------------+-------------------------+---------------------------+

.. _djfilt-exact:

exact
^^^^^

Return element(s) whose value for the specified field is an exact match (case-sensitive).
Example::

	 library__exact=E_coli_dh10b

.. _djfilt-iexact:

iexact
^^^^^^

Return element(s) whose value for the specified field is an exact match (case-insensitive).
Example::

	 library__iexact=E_coli_dh10b

.. _djfilt-contains:

contains
^^^^^^^^

Return element(s) whose value for the specified field contains the specified value (case-sensitive). (See also :ref:`djfilt-search`.) Example::

	library__contains=E_coli
	
.. _djfilt-icontains:

icontains
^^^^^^^^^

Return element(s) whose value for the specified field contains the specified value (case-insensitive). Example::

	library__icontains=E_coli
	
.. _djfilt-in:

in
^^
Return element(s) whose value for the specified field is in the specified list. Example::

	 id__in=[1, 3, 4]

.. _djfilt-gt:

gt
^^
Return element(s) whose value for the specified field is greater than the specified value. Example::

	 name__gt=B4

.. _djfilt-gte:

gte
^^^
Return element(s) whose value for the specified field is greater than or equal to the specified value. Example::

	 name__gte=B4

.. _djfilt-lt:

lt
^^
Return element(s) whose value for the specified field is less than the specified value. Example::

	 name__lt=B24

.. _djfilt-lte:

lte
^^^
Return element(s) whose value for the specified field is less than or equal to the specified value. Example::

	 name__lte=B24

.. _djfilt-startswith:

startswith
^^^^^^^^^^
Return element(s) whose value for the specified field starts with the specified value (case-sensitive). Example::

	 library__startswith=E_coli

.. _djfilt-istartswith:

istartswith
^^^^^^^^^^^
Return element(s) whose value for the specified field starts with the specified value (case-insensitive). Example::

	 library__istartswith=E_coli

.. _djfilt-endswith:

endswith
^^^^^^^^
Return element(s) whose value for the specified field ends with the specified value (case-sensitive). Example::

	 library__endswith=dh10b

.. _djfilt-iendswith:

iendswith
^^^^^^^^^
Return element(s) whose value for the specified field ends with the specified value (case-insensitive). Example::

	 library__iendswith=dh10b

.. _djfilt-range:

range
^^^^^
Return element(s) whose value for the specified field is in the range of the specified values (inclusive). Example::

	 date__range=(start_date, end_date))

.. _djfilt-year:

year
^^^^
Return element(s) whose value for the specified date/datetime field matches the specified year. Example::

	 date__year=2013

.. _djfilt-month:

month
^^^^^
Return element(s) whose value for the specified date/datetime field matches the specified integer month. Example::

	 date__month=6

.. _djfilt-day:

day
^^^
Return element(s) whose value for the specified date/datetime field matches the specified integer day-of-month. Example::

	 date__day=17

.. _djfilt-weekday:

week_day
^^^^^^^^
Return element(s) whose value for the specified date/datetime field matches the specified integer day-of-week, where Sunday = 1 and Saturday = 7. Example::

	 date__week_day=2

.. _djfilt-isnull:

isnull
^^^^^^

Return element(s) whose value for the specified field is NULL, where True = NULL and False = NOT NULL. Example::

	date__isnull=True

.. _djfilt-search:
	
search
^^^^^^

Return element(s) whose value for the specified field contains the specified value. (See also :ref:`djfilt-contains`.) Example::

	comment__search="my test results"

.. _djfilt-regex:

regex
^^^^^

Return element(s) whose value for the specified field matches the regular expression (case-sensitive). Example::

	name__regex=r'^(An?|The) +'

.. _djfilt-iregex:

iregex
^^^^^^

Return element(s) whose value for the specified field matches the regular expression (case-insensitive). Example::

	name__iregex=r'^(an?|the) +'