Updated PPL user manual with relevance function limitations (opensear…

…ch-project#283) * update user manual on relevanc function limitations Signed-off-by: chloe-zh <[email protected]> * update Signed-off-by: chloe-zh <[email protected]>
joshuali925 · Nov 12, 2021 · 603d953 · 603d953
1 parent 907019c
commit 603d953
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 0 deletions.
diff --git a/docs/user/ppl/functions/relevance.rst b/docs/user/ppl/functions/relevance.rst
@@ -56,3 +56,7 @@ Another example to show how to set custom values for the optional parameters::
     | Bond       |
     +------------+
 
+Limitations
+>>>>>>>>>>>
+
+The relevance functions are available to execute only in OpenSearch DSL but not in memory as of now, so the relevance search might fail for queries that are too complex to translate into DSL if the relevance function is following after a complex PPL query. To make your queries always work-able, it is recommended to place the relevance commands as close to the search command as possible, to ensure the relevance functions are eligible to push down. For example, a complex query like ``search source = people | rename firstname as name | dedup account_number | fields name, account_number, balance, employer | where match(employer, 'Open Search') | stats count() by city`` could fail because it is difficult to translate to DSL, but it would be better if we rewrite it to an equivalent query as ``search source = people | where match(employer, 'Open Search') | rename firstname as name | dedup account_number | fields name, account_number, balance, employer | stats count() by city`` by moving the where command with relevance function to the second command right after the search command, and the relevance would be optimized and executed smoothly in OpenSearch DSL. See `Optimization <../../optimization/optimization.rst>`_ to get more details about the query engine optimization.
diff --git a/docs/user/ppl/index.rst b/docs/user/ppl/index.rst
@@ -68,6 +68,8 @@ The query start with search command and then flowing a set of command delimited
 
   - `Condition Functions <functions/condition.rst>`_
 
+  - `Relevance Functions <functions/relevance.rst>`_
+
 * **Optimization**
 
   - `Optimization <../../user/optimization/optimization.rst>`_