Include Pinned Retriever in 8.19 Documentation (#129217)

* Document pinned retriever in 8.19 retrievers overview

* updated the changes in the doc

* made changes

* Added pinned to retrievers overview doc

* Pinned example added to the asciidoc

* Modified & fixed issues

* Fixed PR docs

* Ascii files modified

* Fixing formatting issues

* Just fixed the formatting overall

Author: mridula-s109

docs/reference/search/search-your-data/retrievers-examples.asciidoc

@@ -1478,7 +1478,6 @@ GET /retrievers_example/_search
 [discrete]
 [[retrievers-examples-chaining-text-similarity-reranker-retrievers]]
 ==== Example: Chaining multiple semantic rerankers
-
 Full composability means we can chain together multiple retrievers of the same type. For instance,
 imagine we have a computationally expensive reranker that's specialized for AI content. We can rerank the results of a `text_similarity_reranker` using another `text_similarity_reranker` retriever. Each reranker can operate on different fields and/or use different inference services.
 
@@ -1523,3 +1522,33 @@ Note that our example applies two reranking steps. First, we rerank the top 100
 documents from the `knn` search using the `my-rerank-model` reranker. Then we
 pick the top 10 results and rerank them using the more fine-grained
 `my-other-more-expensive-rerank-model`.
+
+[discrete]
+[[retrievers-examples-pinned-retriever]]
+==== Example: Using the pinned retriever
+
+Pinned Retriever example using `docs`
+
+[source,console]
+----
+GET /retrievers_example/_search
+{
+  "retriever": {
+    "pinned": {
+      "docs": [
+        { "_id": "1" },
+        { "_id": "2" }
+      ],
+      "retriever": {
+        "standard": {
+          "query": {
+            "match": {
+              "text": "elasticsearch"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+----

docs/reference/search/search-your-data/retrievers-overview.asciidoc

@@ -27,8 +27,8 @@ Returns top documents from a <<search-api-knn,knn search>>, in the context of a
 Combines the top results from multiple sub-retrievers using a weighted sum of their scores. Allows to specify different
 weights for each retriever, as well as independently normalize the scores from each result set.
 
-  [discrete]
-  [[retrievers-overview-linear-retriever-parameters]]
+[discrete]
+[[retrievers-overview-linear-retriever-parameters]]
 ==== Linear Retriever Parameters
 
 `retrievers`
@@ -69,6 +69,29 @@ Applies <<query-rules,query rules>> to the query before returning results.
 * <<text-similarity-reranker-retriever,*Text Similarity Re-ranker Retriever*>>.
 Used for <<semantic-reranking,semantic reranking>>.
 Requires first creating a `rerank` task using the <<put-inference-api,{es} Inference API>>.
+* <<retrievers-overview-pinned-retriever-parameters,*Pinned Retriever*>>.
+Returns top documents by always placing specific documents at the top of the results, with the remaining hits provided by a secondary retriever.
+
+[discrete]
+[[retrievers-overview-pinned-retriever-parameters]]
+==== Pinned Retriever Parameters
+
+`ids`::
+(Optional, array of strings)
++
+A list of document IDs to pin at the top of the results, in the order provided.
+
+`docs`::
+(Optional, array of objects)
++
+List of objects specifying documents to pin. Each object must contain at least an `_id` field, and may also specify `_index` if pinning documents across multiple indices.
+
+`retriever`::
+(Optional, retriever object)
++
+A retriever (for example a `standard` retriever or a specialized retriever such as `rrf` retriever) used to retrieve the remaining documents after the pinned ones.
+
+Either `ids` or `docs` must be specified.
 
 [discrete]
 [[retrievers-overview-why-are-they-useful]]