From af1d9a5795f1d207d75819dc58c6124018018b79 Mon Sep 17 00:00:00 2001
From: "opensearch-trigger-bot[bot]"
 <98922864+opensearch-trigger-bot[bot]@users.noreply.github.com>
Date: Wed, 18 Dec 2024 11:27:22 -0800
Subject: [PATCH] Add JSONPath examples / details in relevant modals (#542)
 (#543)

* Tune wording on jsonarray too large



* Add JSONPath details table to all relevant modals



---------


(cherry picked from commit 67c0bf9ceb58846b912a8e1ae16248540ae1fb2b)

Signed-off-by: Tyler Ohlsen <ohltyler@amazon.com>
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
---
 common/constants.ts                           |  1 +
 .../jsonpath_examples_table.tsx               | 63 ++++++++++++++-
 .../ml_processor_inputs.tsx                   | 26 +++---
 .../modals/configure_expression_modal.tsx     | 79 +++++++++++++------
 .../configure_multi_expression_modal.tsx      | 43 ++++++++--
 .../modals/configure_template_modal.tsx       | 52 +++++++++++-
 public/utils/config_to_schema_utils.ts        |  2 +-
 7 files changed, 212 insertions(+), 54 deletions(-)

diff --git a/common/constants.ts b/common/constants.ts
index b8c51b85..76435d0b 100644
--- a/common/constants.ts
+++ b/common/constants.ts
@@ -185,6 +185,7 @@ export const NORMALIZATION_PROCESSOR_LINK =
   'https://opensearch.org/docs/latest/search-plugins/search-pipelines/normalization-processor/';
 export const GITHUB_FEEDBACK_LINK =
   'https://github.com/opensearch-project/dashboards-flow-framework/issues/new/choose';
+export const JSONPATH_DOCS_LINK = 'https://www.npmjs.com/package/jsonpath';
 
 /**
  * Text chunking algorithm constants
diff --git a/public/general_components/jsonpath_examples_table.tsx b/public/general_components/jsonpath_examples_table.tsx
index b05c9eb6..4b40c3b0 100644
--- a/public/general_components/jsonpath_examples_table.tsx
+++ b/public/general_components/jsonpath_examples_table.tsx
@@ -11,7 +11,10 @@ import {
   EuiText,
   EuiFlexGroup,
   EuiFlexItem,
+  EuiLink,
+  EuiSpacer,
 } from '@elastic/eui';
+import { JSONPATH_DOCS_LINK } from '../../common';
 
 interface JsonPathExamplesTableProps {
   headerText?: string;
@@ -25,9 +28,55 @@ type JSONPathExample = {
 
 const examples = [
   {
-    expression: '$.data',
-    meaning: 'The entire input',
-    example: '$.data',
+    expression: '$',
+    meaning: 'The root object / element',
+    example: '$.my_field',
+  },
+  {
+    expression: '.',
+    meaning: 'Child member operator',
+    example: 'my_field.my_sub_field',
+  },
+  {
+    expression: '..',
+    meaning:
+      'Recursive descendant operator, to specify an object field in an array of objects',
+    example: '$..my_field',
+  },
+  {
+    expression: '*',
+    meaning: 'Wildcard matching all objects',
+    example: 'my_array.*',
+  },
+  {
+    expression: '[]',
+    meaning: 'Subscript operator',
+    example: 'my_array[0]',
+  },
+  {
+    expression: '[,]',
+    meaning: 'Union operator for alternate names or array indices as a set',
+    example: 'my_array[0,1]',
+  },
+  {
+    expression: '[start:end:step]',
+    meaning: 'Array slice operator borrowed from ES4 / Python',
+    example: 'my_array[0:5]',
+  },
+  {
+    expression: '@',
+    meaning: 'The current object / element in an array',
+    example: 'my_array[?(@.price<10)]',
+  },
+  {
+    expression: '()',
+    meaning: 'Script expression via static evaluation',
+    example: 'my_array[?(@.price<10)]',
+  },
+  {
+    expression: '?()',
+    meaning: 'Applies a filter (script) expression via static evaluation',
+    example: 'my_array[?(@.price<10)]',
   },
 ] as JSONPathExample[];
 
@@ -61,7 +110,7 @@ const columns = [
  */
 export function JsonPathExamplesTable(props: JsonPathExamplesTableProps) {
   return (
-    <EuiFlexItem style={{ width: '20vw' }}>
+    <EuiFlexItem style={{ width: '40vw' }}>
       <EuiFlexGroup direction="column" gutterSize="xs">
         {!isEmpty(props.headerText) && (
           <EuiFlexItem grow={false}>
@@ -77,6 +126,12 @@ export function JsonPathExamplesTable(props: JsonPathExamplesTableProps) {
             hasActions={false}
           />
         </EuiFlexItem>
+        <EuiSpacer size="s" />
+        <EuiFlexItem grow={false}>
+          <EuiLink href={JSONPATH_DOCS_LINK} target="_blank">
+            More examples & documentation
+          </EuiLink>
+        </EuiFlexItem>
       </EuiFlexGroup>
     </EuiFlexItem>
   );
diff --git a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/ml_processor_inputs.tsx b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/ml_processor_inputs.tsx
index 995f39f6..c9286dcf 100644
--- a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/ml_processor_inputs.tsx
+++ b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/ml_processor_inputs.tsx
@@ -194,19 +194,11 @@ export function MLProcessorInputs(props: MLProcessorInputsProps) {
                 </EuiFlexItem>
                 <EuiFlexItem grow={false}>
                   <EuiIconTip
-                    content={`Specify a ${
+                    content={`Specify how to transform your input ${
                       props.context === PROCESSOR_CONTEXT.SEARCH_REQUEST
                         ? 'query'
-                        : 'document'
-                    } field or define JSONPath to transform the ${
-                      props.context === PROCESSOR_CONTEXT.SEARCH_REQUEST
-                        ? 'query'
-                        : 'document'
-                    } to map to a model input field.${
-                      props.context === PROCESSOR_CONTEXT.SEARCH_RESPONSE
-                        ? ` Or, if you'd like to include data from the the original query request, prefix your mapping with "${REQUEST_PREFIX}" or "${REQUEST_PREFIX_WITH_JSONPATH_ROOT_SELECTOR}" - for example, "_request.query.match.my_field"`
-                        : ''
-                    }`}
+                        : 'documents'
+                    } and map to your model input fields`}
                     position="right"
                   />
                 </EuiFlexItem>
@@ -222,13 +214,23 @@ export function MLProcessorInputs(props: MLProcessorInputsProps) {
             isDataFetchingAvailable={isInputPreviewAvailable}
           />
           <EuiSpacer size="l" />
-          <EuiFlexGroup direction="row" justifyContent="spaceBetween">
+          <EuiFlexGroup direction="row" gutterSize="xs">
             <EuiFlexItem grow={false}>
               <EuiText
                 size="m"
                 style={{ marginTop: '4px' }}
               >{`Outputs`}</EuiText>
             </EuiFlexItem>
+            <EuiFlexItem grow={false}>
+              <EuiIconTip
+                content={`Specify how to transform your model outputs to new ${
+                  props.context === PROCESSOR_CONTEXT.SEARCH_REQUEST
+                    ? 'query'
+                    : 'document'
+                } fields`}
+                position="right"
+              />
+            </EuiFlexItem>
           </EuiFlexGroup>
           <EuiSpacer size="s" />
           <ModelOutputs
diff --git a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_expression_modal.tsx b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_expression_modal.tsx
index fdd37618..9dbad4da 100644
--- a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_expression_modal.tsx
+++ b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_expression_modal.tsx
@@ -22,6 +22,7 @@ import {
   EuiSmallButtonEmpty,
   EuiSpacer,
   EuiIconTip,
+  EuiPopover,
 } from '@elastic/eui';
 import {
   customStringify,
@@ -38,7 +39,6 @@ import {
   WorkflowConfig,
   WorkflowFormValues,
   REQUEST_PREFIX,
-  REQUEST_PREFIX_WITH_JSONPATH_ROOT_SELECTOR,
   QueryParam,
 } from '../../../../../../../common';
 import {
@@ -61,7 +61,10 @@ import {
   useAppDispatch,
 } from '../../../../../../store';
 import { getCore } from '../../../../../../services';
-import { QueryParamsList } from '../../../../../../general_components';
+import {
+  JsonPathExamplesTable,
+  QueryParamsList,
+} from '../../../../../../general_components';
 
 interface ConfigureExpressionModalProps {
   uiConfig: WorkflowConfig;
@@ -135,6 +138,9 @@ export function ConfigureExpressionModal(props: ConfigureExpressionModalProps) {
   // button updating state
   const [isUpdating, setIsUpdating] = useState<boolean>(false);
 
+  // JSONPath details popover state
+  const [popoverOpen, setPopoverOpen] = useState<boolean>(false);
+
   // validation state utilizing the model interface, if applicable. undefined if
   // there is no model interface and/or no source input
   const [isValid, setIsValid] = useState<boolean | undefined>(undefined);
@@ -306,27 +312,39 @@ export function ConfigureExpressionModal(props: ConfigureExpressionModalProps) {
                     <EuiFlexItem grow={false}>
                       <EuiFlexGroup direction="row" gutterSize="m">
                         <EuiFlexItem grow={KEY_FLEX_RATIO}>
-                          <EuiFlexGroup direction="row" gutterSize="none">
+                          <EuiFlexGroup
+                            direction="row"
+                            justifyContent="spaceBetween"
+                          >
                             <EuiFlexItem grow={false}>
-                              <EuiText size="xs" color="subdued">
+                              <EuiText size="s" color="subdued">
                                 {`Expression`}
                               </EuiText>
                             </EuiFlexItem>
                             <EuiFlexItem grow={false}>
-                              <EuiIconTip
-                                content={`Define JSONPath to transform the ${
-                                  props.context ===
-                                  PROCESSOR_CONTEXT.SEARCH_REQUEST
-                                    ? 'query'
-                                    : 'document'
-                                } to map to a model input field.${
-                                  props.context ===
-                                  PROCESSOR_CONTEXT.SEARCH_RESPONSE
-                                    ? ` Or, if you'd like to include data from the the original query request, prefix your mapping with "${REQUEST_PREFIX}" or "${REQUEST_PREFIX_WITH_JSONPATH_ROOT_SELECTOR}" - for example, "_request.query.match.my_field"`
-                                    : ''
-                                }`}
-                                position="right"
-                              />
+                              <EuiPopover
+                                isOpen={popoverOpen}
+                                initialFocus={false}
+                                anchorPosition="downCenter"
+                                closePopover={() => setPopoverOpen(false)}
+                                button={
+                                  <EuiSmallButtonEmpty
+                                    style={{ marginTop: '-4px' }}
+                                    onClick={() => setPopoverOpen(!popoverOpen)}
+                                  >
+                                    Learn more
+                                  </EuiSmallButtonEmpty>
+                                }
+                              >
+                                <JsonPathExamplesTable
+                                  headerText={`Define JSONPath to transform your input ${
+                                    props.context ===
+                                    PROCESSOR_CONTEXT.SEARCH_REQUEST
+                                      ? 'query'
+                                      : 'documents'
+                                  } to map to a model input field.`}
+                                />
+                              </EuiPopover>
                             </EuiFlexItem>
                           </EuiFlexGroup>
                         </EuiFlexItem>
@@ -339,18 +357,29 @@ export function ConfigureExpressionModal(props: ConfigureExpressionModalProps) {
                       <EuiSpacer size="s" />
                       <EuiFlexGroup direction="row" gutterSize="m">
                         <EuiFlexItem grow={KEY_FLEX_RATIO}>
-                          <TextField
-                            fullWidth={true}
-                            fieldPath={`expression`}
-                            placeholder={`$.data`}
-                            showError={true}
-                          />
+                          <EuiFlexGroup direction="column" gutterSize="xs">
+                            <EuiFlexItem grow={false}>
+                              <TextField
+                                fullWidth={true}
+                                fieldPath={`expression`}
+                                placeholder={`$.data`}
+                                showError={true}
+                              />
+                            </EuiFlexItem>
+                            {props.context ===
+                              PROCESSOR_CONTEXT.SEARCH_RESPONSE && (
+                              <EuiFlexItem grow={false}>
+                                <EuiText size="xs" color="subdued">
+                                  {`Tip: to include data from the the original query request, prefix your expression with "${REQUEST_PREFIX}" - for example, "_request.query.match.my_field"`}
+                                </EuiText>
+                              </EuiFlexItem>
+                            )}
+                          </EuiFlexGroup>
                         </EuiFlexItem>
                         <EuiFlexItem grow={VALUE_FLEX_RATIO}>
                           <EuiText>{props.modelInputFieldName}</EuiText>
                         </EuiFlexItem>
                       </EuiFlexGroup>
-                      <EuiSpacer size="s" />
                     </EuiFlexItem>
                   </EuiFlexGroup>
                 </EuiFlexItem>
diff --git a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_multi_expression_modal.tsx b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_multi_expression_modal.tsx
index a640a1ed..882c62fb 100644
--- a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_multi_expression_modal.tsx
+++ b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_multi_expression_modal.tsx
@@ -21,7 +21,7 @@ import {
   EuiSmallButtonEmpty,
   EuiSpacer,
   EuiSmallButtonIcon,
-  EuiIconTip,
+  EuiPopover,
 } from '@elastic/eui';
 import {
   customStringify,
@@ -59,7 +59,10 @@ import {
   useAppDispatch,
 } from '../../../../../../store';
 import { getCore } from '../../../../../../services';
-import { QueryParamsList } from '../../../../../../general_components';
+import {
+  JsonPathExamplesTable,
+  QueryParamsList,
+} from '../../../../../../general_components';
 
 interface ConfigureMultiExpressionModalProps {
   uiConfig: WorkflowConfig;
@@ -143,6 +146,9 @@ export function ConfigureMultiExpressionModal(
   // button updating state
   const [isUpdating, setIsUpdating] = useState<boolean>(false);
 
+  // JSONPath details popover state
+  const [popoverOpen, setPopoverOpen] = useState<boolean>(false);
+
   // source input / transformed input state
   const [sourceInput, setSourceInput] = useState<string>('{}');
   const [transformedInput, setTransformedInput] = useState<string>('{}');
@@ -278,18 +284,39 @@ export function ConfigureMultiExpressionModal(
                     <EuiFlexItem grow={false}>
                       <EuiFlexGroup direction="row" gutterSize="s">
                         <EuiFlexItem grow={KEY_FLEX_RATIO}>
-                          <EuiFlexGroup direction="row" gutterSize="xs">
+                          <EuiFlexGroup
+                            direction="row"
+                            justifyContent="spaceBetween"
+                          >
                             <EuiFlexItem grow={false}>
                               <EuiText size="s" color="subdued">
                                 {`Expression`}
                               </EuiText>
                             </EuiFlexItem>
                             <EuiFlexItem grow={false}>
-                              <EuiIconTip
-                                content={`Define any number of JSONPath transforms to extract out parts of the model output's source data and 
-                              store in new document fields.`}
-                                position="right"
-                              />
+                              <EuiPopover
+                                isOpen={popoverOpen}
+                                initialFocus={false}
+                                anchorPosition="downCenter"
+                                closePopover={() => setPopoverOpen(false)}
+                                button={
+                                  <EuiSmallButtonEmpty
+                                    style={{ marginTop: '-4px' }}
+                                    onClick={() => setPopoverOpen(!popoverOpen)}
+                                  >
+                                    Learn more
+                                  </EuiSmallButtonEmpty>
+                                }
+                              >
+                                <JsonPathExamplesTable
+                                  headerText={`Define JSONPath to transform your model outputs to new ${
+                                    props.context ===
+                                    PROCESSOR_CONTEXT.SEARCH_REQUEST
+                                      ? 'query'
+                                      : 'document'
+                                  } fields.`}
+                                />
+                              </EuiPopover>
                             </EuiFlexItem>
                           </EuiFlexGroup>
                         </EuiFlexItem>
diff --git a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_template_modal.tsx b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_template_modal.tsx
index dc0ab268..eb5612dc 100644
--- a/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_template_modal.tsx
+++ b/public/pages/workflow_detail/workflow_inputs/processor_inputs/ml_processor_inputs/modals/configure_template_modal.tsx
@@ -65,7 +65,10 @@ import {
   useAppDispatch,
 } from '../../../../../../store';
 import { getCore } from '../../../../../../services';
-import { QueryParamsList } from '../../../../../../general_components';
+import {
+  JsonPathExamplesTable,
+  QueryParamsList,
+} from '../../../../../../general_components';
 
 interface ConfigureTemplateModalProps {
   uiConfig: WorkflowConfig;
@@ -166,6 +169,9 @@ export function ConfigureTemplateModal(props: ConfigureTemplateModalProps) {
 
   // popover states
   const [presetsPopoverOpen, setPresetsPopoverOpen] = useState<boolean>(false);
+  const [jsonPathPopoverOpen, setJsonPathPopoverOpen] = useState<boolean>(
+    false
+  );
 
   // source input / transformed input state
   const [sourceInput, setSourceInput] = useState<string>('{}');
@@ -448,9 +454,47 @@ export function ConfigureTemplateModal(props: ConfigureTemplateModalProps) {
                           </EuiText>
                         </EuiFlexItem>
                         <EuiFlexItem grow={VALUE_FLEX_RATIO}>
-                          <EuiText size="s" color="subdued">
-                            {`Expression`}
-                          </EuiText>
+                          <EuiFlexGroup
+                            direction="row"
+                            justifyContent="spaceBetween"
+                          >
+                            <EuiFlexItem grow={false}>
+                              <EuiText size="s" color="subdued">
+                                {`Expression`}
+                              </EuiText>
+                            </EuiFlexItem>
+                            <EuiFlexItem grow={false}>
+                              <EuiPopover
+                                isOpen={jsonPathPopoverOpen}
+                                initialFocus={false}
+                                anchorPosition="downCenter"
+                                closePopover={() =>
+                                  setJsonPathPopoverOpen(false)
+                                }
+                                button={
+                                  <EuiSmallButtonEmpty
+                                    style={{ marginTop: '-4px' }}
+                                    onClick={() =>
+                                      setJsonPathPopoverOpen(
+                                        !jsonPathPopoverOpen
+                                      )
+                                    }
+                                  >
+                                    Learn more
+                                  </EuiSmallButtonEmpty>
+                                }
+                              >
+                                <JsonPathExamplesTable
+                                  headerText={`Define JSONPath to transform your input ${
+                                    props.context ===
+                                    PROCESSOR_CONTEXT.SEARCH_REQUEST
+                                      ? 'query'
+                                      : 'documents'
+                                  } to map to input variables that can be dynamically injected in your template.`}
+                                />
+                              </EuiPopover>
+                            </EuiFlexItem>
+                          </EuiFlexGroup>
                         </EuiFlexItem>
                       </EuiFlexGroup>
                       <EuiSpacer size="s" />
diff --git a/public/utils/config_to_schema_utils.ts b/public/utils/config_to_schema_utils.ts
index 3d3b3c98..8bcfb007 100644
--- a/public/utils/config_to_schema_utils.ts
+++ b/public/utils/config_to_schema_utils.ts
@@ -177,7 +177,7 @@ export function getFieldSchema(
         )
         .test(
           'jsonArray',
-          `Too large. Exceeds OpenSearch Dashboards limit of ${MAX_BYTES} bytes.`,
+          `The data size exceeds the limit of ${MAX_BYTES} bytes`,
           (value) => {
             try {
               // @ts-ignore