« Wrapper query Rule query »
Elastic Docs ›Elasticsearch Guide [8.15] ›Query DSL ›Specialized queries

Pinned Query

edit

Pinned Query

edit

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 field.

Example request

edit
resp = client.search(
    query={
        "pinned": {
            "ids": [
                "1",
                "4",
                "100"
            ],
            "organic": {
                "match": {
                    "description": "iphone"
                }
            }
        }
    },
)
print(resp)
response = client.search(
  body: {
    query: {
      pinned: {
        ids: [
          '1',
          '4',
          '100'
        ],
        organic: {
          match: {
            description: 'iphone'
          }
        }
      }
    }
  }
)
puts response
const response = await client.search({
  query: {
    pinned: {
      ids: ["1", "4", "100"],
      organic: {
        match: {
          description: "iphone",
        },
      },
    },
  },
});
console.log(response);
GET /_search
{
  "query": {
    "pinned": {
      "ids": [ "1", "4", "100" ],
      "organic": {
        "match": {
          "description": "iphone"
        }
      }
    }
  }
}

Top-level parameters for pinned

edit
ids
(Optional, array) 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 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

edit

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

resp = client.search(
    query={
        "pinned": {
            "docs": [
                {
                    "_index": "my-index-000001",
                    "_id": "1"
                },
                {
                    "_id": "4"
                }
            ],
            "organic": {
                "match": {
                    "description": "iphone"
                }
            }
        }
    },
)
print(resp)
response = client.search(
  body: {
    query: {
      pinned: {
        docs: [
          {
            _index: 'my-index-000001',
            _id: '1'
          },
          {
            _id: '4'
          }
        ],
        organic: {
          match: {
            description: 'iphone'
          }
        }
      }
    }
  }
)
puts response
const response = await client.search({
  query: {
    pinned: {
      docs: [
        {
          _index: "my-index-000001",
          _id: "1",
        },
        {
          _id: "4",
        },
      ],
      organic: {
        match: {
          description: "iphone",
        },
      },
    },
  },
});
console.log(response);
GET /_search
{
  "query": {
    "pinned": {
      "docs": [
        {
          "_index": "my-index-000001", 
          "_id": "1"
        },
        {
          "_id": "4" 
        }
      ],
      "organic": {
        "match": {
          "description": "iphone"
        }
      }
    }
  }
}

The document with id 1 from my-index-000001 will be the first result.

When _index is missing, all documents with id 4 from the queried indices will be pinned with the same score.
« Wrapper query Rule query »