adding percolate query dsl docs #9798

AntonEliatra · 2025-04-30T23:49:31Z

Description

adding percolate query dsl docs

Version

all

Checklist

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Signed-off-by: Anton Rubin <anton.rubin@eliatra.com>

github-actions · 2025-04-30T23:49:41Z

Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged.

Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer.

When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review.

Signed-off-by: Anton Rubin <anton.rubin@eliatra.com>

…atra/documentation-website into adding-perculate-query-dsl-docs

kolchfa-aws · 2025-05-01T15:28:56Z

@kaushalmahi12 Could you please review this PR? Please carefully review the "Batch compared to named percolation" section and the table provided. The entry marked "Not possible" did not work - is there a way to get it working? Thanks!

kaushalmahi12

I have some minor comments

_query-dsl/specialized/percolate.md

kaushalmahi12 · 2025-07-02T20:14:40Z

_query-dsl/specialized/percolate.md

+
+You can percolate different documents inside a named query:


We should also mention the comparative performance of this ways vs multiple documents in single percolate query

@kaushalmahi12 Thank you for the review. Regarding this comment, is the difference not already sufficiently covers in "Batch compared to named percolation", later in the page?

Ah I see!, thanks

_query-dsl/specialized/percolate.md

Signed-off-by: Anton Rubin <anton.rubin@eliatra.com>

kaushalmahi12 · 2025-07-07T18:02:55Z

_query-dsl/specialized/percolate.md

+
+You can percolate different documents inside a named query:


Ah I see!, thanks

kolchfa-aws

Thank you, @AntonEliatra! Please see my comments and let me know if you have any questions.

kolchfa-aws · 2025-07-07T19:24:47Z

_field-types/supported-field-types/percolator.md

@@ -13,7 +13,7 @@ redirect_from:
 **Introduced 1.0**
 {: .label .label-purple }

-A percolator field type specifies to treat this field as a query. Any JSON object field can be marked as a percolator field. Normally, documents are indexed and searches are run against them. When you use a percolator field, you store a search, and later the percolate query matches documents to that search. 
+A percolator field type specifies to treat this field as a query. Any JSON object field can be marked as a percolator field. Normally, documents are indexed and searches are run against them. When you use a percolator field, you store a search, and later the percolate query matches documents to that search. For detailed example see [Percolate]({{site.url}}{{site.baseurl}}/query-dsl/specialized/percolate/)


Suggested change

A percolator field type specifies to treat this field as a query. Any JSON object field can be marked as a percolator field. Normally, documents are indexed and searches are run against them. When you use a percolator field, you store a search, and later the percolate query matches documents to that search. For detailed example see [Percolate]({{site.url}}{{site.baseurl}}/query-dsl/specialized/percolate/)

A percolator field type specifies to treat this field as a query. Any JSON object field can be marked as a percolator field. Normally, documents are indexed and searches are run against them. When you use a percolator field, you store a search, and later the percolate query matches documents to that search. For a detailed example see [Percolate]({{site.url}}{{site.baseurl}}/query-dsl/specialized/percolate/)

kolchfa-aws · 2025-07-07T19:25:41Z

_query-dsl/specialized/percolate.md

+
+# Percolate
+
+Use the `percolate` query to find stored queries that match a given document. This is the opposite of a regular search. Instead of finding documents that match a query, you find queries that match a document. Percolate queries are often used for alerting, notifications, and reverse search use cases.


Suggested change

Use the `percolate` query to find stored queries that match a given document. This is the opposite of a regular search. Instead of finding documents that match a query, you find queries that match a document. Percolate queries are often used for alerting, notifications, and reverse search use cases.

Use the `percolate` query to find stored queries that match a given document. This operation is the opposite of a regular search: instead of finding documents that match a query, you find queries that match a document. Percolate queries are often used for alerting, notifications, and reverse search use cases.

kolchfa-aws · 2025-07-07T19:26:05Z

_query-dsl/specialized/percolate.md

+
+Use the `percolate` query to find stored queries that match a given document. This is the opposite of a regular search. Instead of finding documents that match a query, you find queries that match a document. Percolate queries are often used for alerting, notifications, and reverse search use cases.
+
+- You can percolate a document provided inline or fetch an existing document from an index.


Please provide an intro sentence for this list.

kolchfa-aws · 2025-07-07T19:26:39Z

_query-dsl/specialized/percolate.md

+- You can percolate a document provided inline or fetch an existing document from an index.
+- The document and the stored queries must use the same field names and types.
+- You can combine percolation with filtering and scoring to build complex matching systems.
+- Percolate queries are considered expensive and will only run if the cluster setting `search.allow_expensive_queries` is set to `true` (default). If this setting is `false`, percolate queries will be rejected.


Link to expensive queries section on the main query DSL page

kolchfa-aws · 2025-07-07T19:29:17Z

_query-dsl/specialized/percolate.md

+
+Percolate queries are useful in a variety of real-time matching scenarios. Some common use cases include:
+
+- **E-commerce notifications**: Customers can register interest in products, for example: “Notify me when new Apple laptops are in stock”. When new product documents are indexed, the system finds all users with matching saved queries and sends alerts.


Suggested change

- **E-commerce notifications**: Customers can register interest in products, for example: “Notify me when new Apple laptops are in stock”. When new product documents are indexed, the system finds all users with matching saved queries and sends alerts.

- **E-commerce notifications**: Users can register interest in products, for example: “Notify me when new Apple laptops are in stock”. When new product documents are indexed, the system finds all users with matching saved queries and sends alerts.

kolchfa-aws · 2025-07-07T19:48:10Z

_query-dsl/specialized/percolate.md

+| `field` | Required | Field containing the stored percolator queries. |
+| `document` | Optional | Single inline document to match against saved queries. |
+| `documents` | Optional | Array of multiple inline documents to match. |
+| `index` | Optional | Index containing the document you want to match. |


kolchfa-aws · 2025-07-07T19:48:18Z

_query-dsl/specialized/percolate.md

+| `document` | Optional | Single inline document to match against saved queries. |
+| `documents` | Optional | Array of multiple inline documents to match. |
+| `index` | Optional | Index containing the document you want to match. |
+| `id` | Optional | ID of the document to fetch from the index. |


kolchfa-aws · 2025-07-07T19:48:26Z

_query-dsl/specialized/percolate.md

+| `documents` | Optional | Array of multiple inline documents to match. |
+| `index` | Optional | Index containing the document you want to match. |
+| `id` | Optional | ID of the document to fetch from the index. |
+| `routing` | Optional | Routing value to use when fetching the document. |


kolchfa-aws · 2025-07-07T19:48:35Z

_query-dsl/specialized/percolate.md

+| `index` | Optional | Index containing the document you want to match. |
+| `id` | Optional | ID of the document to fetch from the index. |
+| `routing` | Optional | Routing value to use when fetching the document. |
+| `preference` | Optional | Preference for the shard routing when fetching the document. |


kolchfa-aws · 2025-07-07T19:49:03Z

_query-dsl/specialized/percolate.md

+| `id` | Optional | ID of the document to fetch from the index. |
+| `routing` | Optional | Routing value to use when fetching the document. |
+| `preference` | Optional | Preference for the shard routing when fetching the document. |
+| `name` | Optional | Name assigned to a percolate clause, helpful when using multiple percolates in a `bool` query. |


adding percolate query dsl docs

8d76dea

Signed-off-by: Anton Rubin <anton.rubin@eliatra.com>

AntonEliatra requested review from kolchfa-aws, Naarcha-AWS, AMoo-Miki, natebower, dlvenable and epugh as code owners April 30, 2025 23:49

github-actions bot assigned kolchfa-aws Apr 30, 2025

AntonEliatra added 3 commits May 1, 2025 00:49

Merge branch 'main' into adding-perculate-query-dsl-docs

da9a00c

fixing vale errors

e8802d2

Signed-off-by: Anton Rubin <anton.rubin@eliatra.com>

Merge branch 'adding-perculate-query-dsl-docs' of github.com:AntonEli…

33286fa

…atra/documentation-website into adding-perculate-query-dsl-docs

kolchfa-aws added 3 - Tech review PR: Tech review in progress Content gap backport 2.19 backport 3.0 and removed backport 2.19 labels May 1, 2025

kaushalmahi12 reviewed Jul 2, 2025

View reviewed changes

addressing the PR comments

e749e62

Signed-off-by: Anton Rubin <anton.rubin@eliatra.com>

AntonEliatra requested a review from sumobrian as a code owner July 3, 2025 15:08

kolchfa-aws added backport 3.1 and removed backport 3.0 labels Jul 3, 2025

kaushalmahi12 approved these changes Jul 7, 2025

View reviewed changes

kolchfa-aws reviewed Jul 7, 2025

View reviewed changes

kolchfa-aws added 4 - Doc review PR: Doc review in progress and removed 3 - Tech review PR: Tech review in progress labels Jul 7, 2025


		# Percolate

		Use the `percolate` query to find stored queries that match a given document. This is the opposite of a regular search. Instead of finding documents that match a query, you find queries that match a document. Percolate queries are often used for alerting, notifications, and reverse search use cases.


		Use the `percolate` query to find stored queries that match a given document. This is the opposite of a regular search. Instead of finding documents that match a query, you find queries that match a document. Percolate queries are often used for alerting, notifications, and reverse search use cases.

		- You can percolate a document provided inline or fetch an existing document from an index.


		Percolate queries are useful in a variety of real-time matching scenarios. Some common use cases include:

		- E-commerce notifications: Customers can register interest in products, for example: “Notify me when new Apple laptops are in stock”. When new product documents are indexed, the system finds all users with matching saved queries and sends alerts.

	- E-commerce notifications: Customers can register interest in products, for example: “Notify me when new Apple laptops are in stock”. When new product documents are indexed, the system finds all users with matching saved queries and sends alerts.
	- E-commerce notifications: Users can register interest in products, for example: “Notify me when new Apple laptops are in stock”. When new product documents are indexed, the system finds all users with matching saved queries and sends alerts.

	\| `index` \| Optional \| Index containing the document you want to match. \|
	\| `index` \| Optional \| An index containing the document you want to match. \|

	\| `id` \| Optional \| ID of the document to fetch from the index. \|
	\| `id` \| Optional \| The ID of the document to fetch from the index. \|

	\| `routing` \| Optional \| Routing value to use when fetching the document. \|
	\| `routing` \| Optional \| The routing value to use when fetching the document. \|

	\| `preference` \| Optional \| Preference for the shard routing when fetching the document. \|
	\| `preference` \| Optional \| The preference for the shard routing when fetching the document. \|

	\| `name` \| Optional \| Name assigned to a percolate clause, helpful when using multiple percolates in a `bool` query. \|
	\| `name` \| Optional \| The name assigned to a `percolate` clause. Helpful when using multiple `percolate` clauses in a `bool` query. \|

adding percolate query dsl docs #9798

Are you sure you want to change the base?

adding percolate query dsl docs #9798

Conversation

AntonEliatra commented Apr 30, 2025

Description

Version

Checklist

Uh oh!

github-actions bot commented Apr 30, 2025

Uh oh!

kolchfa-aws commented May 1, 2025

Uh oh!

kaushalmahi12 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AntonEliatra Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kolchfa-aws left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AntonEliatra Jul 3, 2025 •

edited

Loading