81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
---
|
||
mapped_pages:
|
||
- https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-pinned-query.html
|
||
---
|
||
|
||
# Pinned query [query-dsl-pinned-query]
|
||
|
||
Promotes selected documents to rank higher than those matching a given query. This feature is typically used to guide searchers to curated documents that are promoted over and above any "organic" matches for a search. The promoted or "pinned" documents are identified using the document IDs stored in the [`_id`](/reference/elasticsearch/mapping-reference/mapping-id-field.md) field.
|
||
|
||
## Example request [_example_request]
|
||
|
||
```console
|
||
GET /_search
|
||
{
|
||
"query": {
|
||
"pinned": {
|
||
"ids": [ "1", "4", "100" ],
|
||
"organic": {
|
||
"match": {
|
||
"description": "iphone"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## Top-level parameters for `pinned` [pinned-query-top-level-parameters]
|
||
|
||
`ids`
|
||
: (Optional, array) [Document IDs](/reference/elasticsearch/mapping-reference/mapping-id-field.md) listed in the order they are to appear in results. Required if `docs` is not specified.
|
||
|
||
`docs`
|
||
: (Optional, array) Documents listed in the order they are to appear in results. Required if `ids` is not specified. You can specify the following attributes for each document:
|
||
|
||
`_id`
|
||
: (Required, string) The unique [document ID](/reference/elasticsearch/mapping-reference/mapping-id-field.md).
|
||
|
||
`_index`
|
||
: (Optional, string) The index that contains the document.
|
||
|
||
|
||
`organic`
|
||
: Any choice of query used to rank documents which will be ranked below the "pinned" documents.
|
||
|
||
|
||
## Pin documents in a specific index [_pin_documents_in_a_specific_index]
|
||
|
||
If you’re searching over multiple indices, you can pin a document within a specific index using `docs`:
|
||
|
||
```console
|
||
GET /_search
|
||
{
|
||
"query": {
|
||
"pinned": {
|
||
"docs": [
|
||
{
|
||
"_index": "my-index-000001", <1>
|
||
"_id": "1"
|
||
},
|
||
{
|
||
"_id": "4" <2>
|
||
}
|
||
],
|
||
"organic": {
|
||
"match": {
|
||
"description": "iphone"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
1. The document with id `1` from `my-index-000001` will be the first result.
|
||
2. When `_index` is missing, all documents with id `4` from the queried indices will be pinned with the same score.
|
||
|
||
|
||
|