Skip to content

Commit

Permalink
[DOCS] Reformat rank feature query. Add relevance score section. (ela…
Browse files Browse the repository at this point in the history
  • Loading branch information
jrodewig committed Jul 31, 2019
1 parent faa47b5 commit d9b2d8d
Show file tree
Hide file tree
Showing 2 changed files with 190 additions and 93 deletions.
51 changes: 32 additions & 19 deletions docs/reference/query-dsl/query_filter_context.asciidoc
Original file line number Diff line number Diff line change
@@ -1,27 +1,38 @@
[[query-filter-context]]
== Query and filter context

The behaviour of a query clause depends on whether it is used in _query context_ or
in _filter context_:
[float]
[[relevance-scores]]
=== Relevance scores

Query context::
+
--
A query clause used in query context answers the question ``__How well does this
By default, Elasticsearch sorts matching search results by **relevance
score**, which measures how well each document matches a query.

The relevance score is a positive floating point number, returned in the
`_score` meta-field of the <<search-request-body,search>> API. The higher the
`_score`, the more relevant the document. While each query type can calculate
relevance scores differently, score calculation also depends on whether the
query clause is run in a **query** or **filter** context.

[float]
[[query-context]]
=== Query context
In the query context, a query clause answers the question ``__How well does this
document match this query clause?__'' Besides deciding whether or not the
document matches, the query clause also calculates a `_score` representing how
well the document matches, relative to other documents.
document matches, the query clause also calculates a relevance score in the
`_score` meta-field.

Query context is in effect whenever a query clause is passed to a `query` parameter,
such as the `query` parameter in the <<request-body-search-query,`search`>> API.
--
Query context is in effect whenever a query clause is passed to a `query`
parameter, such as the `query` parameter in the
<<request-body-search-query,search>> API.

Filter context::
+
--
In _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.
[float]
[[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"++__?
Expand All @@ -34,8 +45,10 @@ 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.
--

[float]
[[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 @@ -80,4 +93,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 d9b2d8d

Please sign in to comment.