[role="xpack"]
[[query-dsl-pinned-query]]
=== 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 <<mapping-id-field,`_id`>> field.

==== Example request

[source,console]
--------------------------------------------------
GET /_search
{
  "query": {
    "pinned": {
      "ids": [ "1", "4", "100" ],
      "organic": {
        "match": {
          "description": "iphone"
        }
      }
    }
  }
}
--------------------------------------------------

[[pinned-query-top-level-parameters]]
==== Top-level parameters for `pinned`

`ids`::
(Optional, array) <<mapping-id-field, Document IDs>> 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 <<mapping-id-field, document ID>>.

`_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

If you're searching over multiple indices, you can pin a document within a specific index using `docs`:

[source,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.