Skip to content

Commit

Permalink
[DOCS] Add search and filtering tutorial/quickstart, edit filtering p…
Browse files Browse the repository at this point in the history
  • Loading branch information
leemthompo authored Oct 28, 2024
1 parent 918a9cc commit 0d8d8bd
Show file tree
Hide file tree
Showing 3 changed files with 662 additions and 15 deletions.
47 changes: 33 additions & 14 deletions docs/reference/query-dsl/query_filter_context.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -29,26 +29,45 @@ parameter, such as the `query` parameter in the
[discrete]
[[filter-context]]
=== Filter context
In a filter context, a query clause answers the question ``__Does this
document match this query clause?__'' The answer is a simple Yes or No -- no
scores are calculated. Filter context is mostly used for filtering structured
data, e.g.

* __Does this +timestamp+ fall into the range 2015 to 2016?__
* __Is the +status+ field set to ++"published"++__?
A filter answers the binary question “Does this document match this query clause?”. The answer is simply "yes" or "no".
Filtering has several benefits:

Frequently used filters will be cached automatically by Elasticsearch, to
speed up performance.
. *Simple binary logic*: In a filter context, a query clause determines document matches based on a yes/no criterion, without score calculation.
. *Performance*: Because they don't compute relevance scores, filters execute faster than queries.
. *Caching*: {es} automatically caches frequently used filters, speeding up subsequent search performance.
. *Resource efficiency*: Filters consume less CPU resources compared to full-text queries.
. *Query combination*: Filters can be combined with scored queries to refine result sets efficiently.

Filter context is in effect whenever a query clause is passed to a `filter`
parameter, such as the `filter` or `must_not` parameters in the
<<query-dsl-bool-query,`bool`>> query, the `filter` parameter in the
<<query-dsl-constant-score-query,`constant_score`>> query, or the
<<search-aggregations-bucket-filter-aggregation,`filter`>> aggregation.
Filters are particularly effective for querying structured data and implementing "must have" criteria in complex searches.

Structured data refers to information that is highly organized and formatted in a predefined manner. In the context of Elasticsearch, this typically includes:

* Numeric fields (integers, floating-point numbers)
* Dates and timestamps
* Boolean values
* Keyword fields (exact match strings)
* Geo-points and geo-shapes

Unlike full-text fields, structured data has a consistent, predictable format, making it ideal for precise filtering operations.

Common filter applications include:

* Date range checks: for example is the `timestamp` field between 2015 and 2016
* Specific field value checks: for example is the `status` field equal to "published" or is the `author` field equal to "John Doe"

Filter context applies when a query clause is passed to a `filter` parameter, such as:

* `filter` or `must_not` parameters in <<query-dsl-bool-query,`bool`>> queries
* `filter` parameter in <<query-dsl-constant-score-query,`constant_score`>> queries
* <<search-aggregations-bucket-filter-aggregation,`filter`>> aggregations

Filters optimize query performance and efficiency, especially for structured data queries and when combined with full-text searches.

[discrete]
[[query-filter-context-ex]]
=== Example of query and filter contexts

Below is an example of query clauses being used in query and filter context
in the `search` API. This query will match documents where all of the following
conditions are met:
Expand Down Expand Up @@ -93,4 +112,4 @@ significand's precision will be converted to floats with loss of precision.

TIP: Use query clauses in query context for conditions which should affect the
score of matching documents (i.e. how well does the document match), and use
all other query clauses in filter context.
all other query clauses in filter context.
Loading

0 comments on commit 0d8d8bd

Please sign in to comment.