elasticsearch/docs/reference/query-dsl/filters.asciidoc

[[query-dsl-filters]]
== Filters

As a general rule, filters should be used instead of queries:

* for binary yes/no searches
* for queries on exact values

[float]
[[caching]]
=== Filters and Caching

Filters can be a great candidate for caching. Caching the result of a
filter does not require a lot of memory, and will cause other queries
executing against the same filter (same parameters) to be blazingly
fast.

However the cost of caching is not the same for all filters. For
instance some filters are already fast out of the box while caching could
add significant overhead, and some filters produce results that are already
cacheable so caching them is just a matter of putting the result in the
cache.

The default caching policy, `_cache: auto`, tracks the 1000 most recently
used filters on a per-index basis and makes decisions based on their
frequency.

[float]
==== Filters that read directly the index structure

Some filters can directly read the index structure and potentially jump
over large sequences of documents that are not worth evaluating (for
instance when these documents do not match the query). Caching these
filters introduces overhead given that all documents that the filter
matches need to be consumed in order to be loaded into the cache.

These filters, which include the <<query-dsl-term-filter,term>> and
<<query-dsl-term-query,query>> filters, are only cached after they
appear 5 times or more in the history of the 1000 most recently used
filters.

[float]
==== Filters that produce results that are already cacheable

Some filters produce results that are already cacheable, and the difference
between caching and not caching them is the act of placing the result in
the cache or not. These filters, which include the
<<query-dsl-terms-filter,terms>>,
<<query-dsl-prefix-filter,prefix>>, and
<<query-dsl-range-filter,range>> filters, are by default cached after they
appear twice or more in the history of the most 1000 recently used filters.

[float]
==== Computational filters

Some filters need to run some computation in order to figure out whether
a given document matches a filter. These filters, which include the geo and
<<query-dsl-script-filter,script>> filters, but also the
<<query-dsl-terms-filter,terms>>  and <<query-dsl-range-filter,range>>
filters when using the `fielddata` execution mode are never cached by default,
as it would require to evaluate the filter on all documents in your indices
while they can otherwise be only evaluated on documents that match the query.

[float]
==== Compound filters

The last type of filters are those working with other filters, and includes
the <<query-dsl-bool-filter,bool>>,
<<query-dsl-and-filter,and>>,
<<query-dsl-not-filter,not>> and
<<query-dsl-or-filter,or>> filters.

There is no general rule about these filters. Depending on the filters that
they wrap, they will sometimes return a filter that dynamically evaluates the
sub filters and sometimes evaluate the sub filters eagerly in order to return
a result that is already cacheable, so depending on the case, these filters
will be cached after they appear 2+ or 5+ times in the history of the most
1000 recently used filters.

[float]
==== Overriding the default behaviour

All filters allow to set `_cache` element on them to explicitly control
caching. It accepts 3 values: `true` in order to cache the filter, `false`
to make sure that the filter will not be cached, and `auto`, which is the
default and will decide on whether to cache the filter based on the cost
to cache it and how often it has been used as explained above.

Filters also allow to set `_cache_key` which will be used as the
caching key for that filter. This can be handy when using very large
filters (like a terms filter with many elements in it).

include::filters/and-filter.asciidoc[]

include::filters/bool-filter.asciidoc[]

include::filters/exists-filter.asciidoc[]

include::filters/geo-bounding-box-filter.asciidoc[]

include::filters/geo-distance-filter.asciidoc[]

include::filters/geo-distance-range-filter.asciidoc[]

include::filters/geo-polygon-filter.asciidoc[]

include::filters/geo-shape-filter.asciidoc[]

include::filters/geohash-cell-filter.asciidoc[]

include::filters/has-child-filter.asciidoc[]

include::filters/has-parent-filter.asciidoc[]

include::filters/ids-filter.asciidoc[]

include::filters/indices-filter.asciidoc[]

include::filters/limit-filter.asciidoc[]

include::filters/match-all-filter.asciidoc[]

include::filters/missing-filter.asciidoc[]

include::filters/nested-filter.asciidoc[]

include::filters/not-filter.asciidoc[]

include::filters/or-filter.asciidoc[]

include::filters/prefix-filter.asciidoc[]

include::filters/query-filter.asciidoc[]

include::filters/range-filter.asciidoc[]

include::filters/regexp-filter.asciidoc[]

include::filters/script-filter.asciidoc[]

include::filters/term-filter.asciidoc[]

include::filters/terms-filter.asciidoc[]

include::filters/type-filter.asciidoc[]