Queries
-------

.. _override-operator:

How do I override what operator is used for a query?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Filter.query_operator_to_q_operator

The member `query_operator_to_q_operator` for `Filter` is used to convert from e.g. `:`
to `icontains`. You can specify another callable here:

.. code-block:: python

    Table(
        auto__model=Track,
        columns__album__filter__query_operator_to_q_operator=lambda op: 'exact',
    )

The above will force the album name to always be looked up with case
sensitive match even if the user types `album<Paranoid` in the
advanced query language. Use this feature with caution!

See also `How do I control what Q is produced?`_

.. _control-q:

How do I control what Q is produced?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. uses Filter.value_to_q

For more advanced customization you can use `value_to_q`. It is a
callable that takes `filter, op, value_string_or_f` and returns a
`Q` object. The default handles `__`, different operators, negation
and special handling of when the user searches for `null`.

.. code-block:: python

    class AlbumTable(Table):
        class Meta:
            auto__model = Album

            query__form__fields__eighties = Field.boolean(
                display_name="the '80s",
            )

            @staticmethod
            def query__filters__eighties__value_to_q(value_string_or_f, **_):
                if value_string_or_f == "1":
                    return Q(year__gte=1980) & Q(year__lte=1989)
                return Q()

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('5ace3009-df4e-4fd4-bc94-f85d7950538c', this)">▼ Hide result</div>
    <iframe id="5ace3009-df4e-4fd4-bc94-f85d7950538c" src="doc_includes/cookbook_queries/test_how_do_i_control_what_q_is_produced.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Without the filter selected:

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('44d3d979-7293-4a8f-913e-ccd46ca4d57b', this)">► Show result</div>
    <iframe id="44d3d979-7293-4a8f-913e-ccd46ca4d57b" src="doc_includes/cookbook_queries/test_how_do_i_control_what_q_is_produced1.html" style="background: white; display: none; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I control the name used in the advanced query?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.query_name

By default the names of filters are derived from the name you specify or from the model field name.
For deeply nested names, double underscores are replaced with single underscores, and those names
can become a bit unwieldy. You can then override this with `query_name`:

.. code-block:: python

    track_table = Table(
        auto__model=Track,
        auto__include=['name', 'album', 'album__artist__name'],
        columns__album_artist_name__filter=dict(
            include=True,
            query_name='artist',
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('d2c18c6b-8610-4797-9036-5efded96ac3b', this)">▼ Hide result</div>
    <iframe id="d2c18c6b-8610-4797-9036-5efded96ac3b" src="doc_includes/cookbook_queries/test_how_do_I_set_the_name_for_a_filter.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I filter on the thing itself?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.attr
.. uses Filter.

Filtering a table on the thing itself is sometimes useful, but can be a bit unintuitive:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        auto__include=['name', 'artist', 'year'],

        query__filters__album=Filter.choice_queryset(
            attr=None,
            choices=Album.objects.all(),
            value_to_q=lambda value_string_or_f, **_: Q(pk=value_string_or_f) if value_string_or_f else Q(),
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ee4b1b88-12ad-457a-8da7-c14b6c89a53b', this)">▼ Hide result</div>
    <iframe id="ee4b1b88-12ad-457a-8da7-c14b6c89a53b" src="doc_includes/cookbook_queries/test_how_do_I_filter_on_the_thing_itself.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

How do I style the query container?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Query.attrs
.. uses Query.tag
.. uses Query.form_container

The `Query` component renders a container element that wraps the filter form.
You can configure its tag and attributes directly. The simple (GUI) form itself
is wrapped in `form_container`, which you can configure the same way:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        auto__include=['name', 'artist', 'year'],
        columns__name__filter__include=True,
        query__attrs__style__border='2px solid red',
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('ae7bdd1f-8c10-4041-9b43-ce1ad2dec9b4', this)">▼ Hide result</div>
    <iframe id="ae7bdd1f-8c10-4041-9b43-ce1ad2dec9b4" src="doc_includes/cookbook_queries/test_how_do_i_style_the_query_container.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _query-filter-rows:

How does a query filter the rows, and how do I post-process them?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Query.filter
.. uses Query.filters
.. uses Query.rows
.. uses Query.model
.. uses Query.postprocess

A `Query` holds a set of `filters` and the `rows` (and `model`) it filters. When
bound it builds a `Q` from the request, and its `filter` method applies that to
the `rows`. Use `postprocess` to operate on the resulting rows afterwards. A
`Query` is usually created for you by a `Table`, but you can declare and use one
on its own:

.. code-block:: python

    class AlbumQuery(Query):
        name = Filter()
        year = Filter.integer()

    query = AlbumQuery(rows=Album.objects.all())

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('a8e859e7-6b1e-4d78-881c-1b34e034f9cf', this)">▼ Hide result</div>
    <iframe id="a8e859e7-6b1e-4d78-881c-1b34e034f9cf" src="doc_includes/cookbook_queries/test_how_does_a_query_filter_the_rows.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _query-auto-config:

How do I choose which filters are generated from a model?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses QueryAutoConfig.model
.. uses QueryAutoConfig.exclude
.. uses QueryAutoConfig.default_included
.. uses QueryAutoConfig.rows

Like tables and forms, a `Query` can introspect a model. Pass `auto__model` (or
`auto__rows`) and pick the filters with `auto__include`/`auto__exclude`, or flip
the default with `auto__default_included`:

.. code-block:: python

    query = Query(
        auto__model=Album,
        auto__exclude=['year'],
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('3535276e-0a47-4b2d-8aac-e7352a196c5c', this)">▼ Hide result</div>
    <iframe id="3535276e-0a47-4b2d-8aac-e7352a196c5c" src="doc_includes/cookbook_queries/test_how_do_i_choose_which_filters_are_generated.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _filter-gui-field:

How do I configure a filter's GUI field?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.field
.. uses Filter.choices
.. uses Filter.search_fields

Each filter has a GUI form field, configured through the filter's `field`
namespace. For choice filters `choices` is the list of options, and
`search_fields` controls which model fields the autocomplete of a
`choice_queryset` filter searches:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__year__filter=dict(
            include=True,
            field__include=True,
        ),
        columns__artist__filter=dict(
            include=True,
            search_fields=['name'],
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('68e9b7a8-d4a7-4e0b-ae8b-888aabf55561', this)">▼ Hide result</div>
    <iframe id="68e9b7a8-d4a7-4e0b-ae8b-888aabf55561" src="doc_includes/cookbook_queries/test_how_do_i_configure_a_filters_gui_field.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _filter-matching:

How do I customize how a single filter matches?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.query_operator_for_field
.. uses Filter.unary
.. uses Filter.parse
.. uses Filter.is_valid_filter
.. uses Filter.pk_lookup_to_q
.. uses Filter.model
.. uses Filter.model_field
.. uses Filter.model_field_name

Lower-level hooks change how an individual filter behaves:

- `query_operator_for_field` is the operator used for the simple (GUI) form, e.g. `=` for exact-ish matching or `:` for "contains".
- `parse` parses the user's input string into a value.
- `unary` marks a filter as usable without a value in the advanced query language.
- `is_valid_filter` decides whether a filter is allowed to be part of a query at all.
- `pk_lookup_to_q` controls how a lookup by primary key is turned into a `Q`.

Filters generated from a model also carry `model`, `model_field` and
`model_field_name` (the same introspection you get on columns and fields), so a
custom hook can read the Django field's metadata when it needs to.

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__name__filter=dict(
            include=True,
            query_operator_for_field=':',
        ),
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('33a312e5-bb77-459c-aaf5-2225e4a11c44', this)">▼ Hide result</div>
    <iframe id="33a312e5-bb77-459c-aaf5-2225e4a11c44" src="doc_includes/cookbook_queries/test_how_do_i_customize_how_a_filter_matches.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _advanced-query:

How do I customize the advanced query language area?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Query.advanced

A `Query` with filters offers an "advanced" free-text query language alongside
the GUI form, with a link to toggle between them. Configure that toggle (and the
advanced area) through the `advanced` namespace:

.. code-block:: python

    albums = Table(
        auto__model=Album,
        columns__name__filter__include=True,
        query__advanced__toggle__attrs__class__advanced_toggle=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('2957098d-c641-4aa4-ac8f-31fde51c79a7', this)">▼ Hide result</div>
    <iframe id="2957098d-c641-4aa4-ac8f-31fde51c79a7" src="doc_includes/cookbook_queries/test_how_do_i_customize_the_advanced_query_toggle.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

.. _filter-multi-select:

How do I let a filter match several values at once?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. uses Filter.related
.. uses Filter.multi_choice_queryset

A filter on a foreign key (the `related` shortcut, which is what you get by
default for an `album` or `artist` column) normally lets the user pick a
single value in the GUI. Pass `multi_select=True` to turn it into a
multi-select where the chosen values are OR:ed together:

.. code-block:: python

    tracks = Table(
        auto__model=Track,
        auto__include=['name', 'album'],
        columns__album__filter__include=True,
        columns__album__filter__multi_select=True,
    )

.. raw:: html

    <div class="iframe_collapse" onclick="toggle('bcf408b3-548a-47c1-9042-97fb732c9d87', this)">▼ Hide result</div>
    <iframe id="bcf408b3-548a-47c1-9042-97fb732c9d87" src="doc_includes/cookbook_queries/test_how_do_i_let_a_filter_select_multiple_values.html" style="background: white; display: ; width: 100%; min-height: 100px; border: 1px solid gray;"></iframe>
    <div class="show_structure_toggler"><span onclick="toggle_iframe_structure_overlay()">Toggle structure</span></div>

Selecting two albums now produces a query like ``album__pk=1 OR album__pk=2``
instead of forcing the user to choose just one.