Reword lookup join error messages (#129312)

Author: idegtiarenko

x-pack/plugin/build.gradle

@@ -134,6 +134,8 @@ tasks.named("yamlRestCompatTestTransform").configure({ task ->
   task.skipTest("esql/90_non_indexed/fetch", "Temporary until backported")
   task.skipTest("esql/63_enrich_int_range/Invalid age as double", "TODO: require disable allow_partial_results")
   task.skipTest("esql/191_lookup_join_on_datastreams/data streams not supported in LOOKUP JOIN", "Added support for aliases in JOINs")
+  task.skipTest("esql/190_lookup_join/non-lookup index", "Error message changed")
+  task.skipTest("esql/192_lookup_join_on_aliases/alias-pattern-multiple", "Error message changed")
 })
 
 tasks.named('yamlRestCompatTest').configure {

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/action/EsqlCapabilities.java

@@ -1182,6 +1182,11 @@ public enum Cap {
          */
         ENABLE_LOOKUP_JOIN_ON_ALIASES,
 
+        /**
+         * Lookup error messages were updated to make them a bit easier to understand.
+         */
+        UPDATE_LOOKUP_JOIN_ERROR_MESSAGES,
+
         /**
          * Allows RLIKE to correctly handle the "empty language" flag, `#`.
          */

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/plan/logical/join/LookupJoin.java

@@ -90,15 +90,24 @@ public void postAnalysisVerification(Failures failures) {
             var indexNameWithModes = esr.indexNameWithModes();
             if (indexNameWithModes.size() != 1) {
                 failures.add(
-                    fail(esr, "invalid [{}] resolution in lookup mode to [{}] indices", esr.indexPattern(), indexNameWithModes.size())
+                    fail(
+                        esr,
+                        "Lookup Join requires a single lookup mode index; [{}] resolves to [{}] indices",
+                        esr.indexPattern(),
+                        indexNameWithModes.size()
+                    )
                 );
-            } else if (indexNameWithModes.values().iterator().next() != IndexMode.LOOKUP) {
+                return;
+            }
+            var indexAndMode = indexNameWithModes.entrySet().iterator().next();
+            if (indexAndMode.getValue() != IndexMode.LOOKUP) {
                 failures.add(
                     fail(
                         esr,
-                        "invalid [{}] resolution in lookup mode to an index in [{}] mode",
+                        "Lookup Join requires a single lookup mode index; [{}] resolves to [{}] in [{}] mode",
                         esr.indexPattern(),
-                        indexNameWithModes.values().iterator().next()
+                        indexAndMode.getKey(),
+                        indexAndMode.getValue()
                     )
                 );
             }

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/analysis/AnalyzerTests.java

@@ -2306,12 +2306,18 @@ public void testLookupJoinIndexMode() {
                 AnalyzerTestUtils.analyzer(lookupResolutionAsIndex, indexResolutionAsLookup)
             )
         );
-        assertThat(e.getMessage(), containsString("1:70: invalid [test] resolution in lookup mode to an index in [standard] mode"));
+        assertThat(
+            e.getMessage(),
+            containsString("1:70: Lookup Join requires a single lookup mode index; [test] resolves to [test] in [standard] mode")
+        );
         e = expectThrows(
             VerificationException.class,
             () -> analyze("FROM test | LOOKUP JOIN test ON languages", AnalyzerTestUtils.analyzer(indexResolution, indexResolutionAsLookup))
         );
-        assertThat(e.getMessage(), containsString("1:25: invalid [test] resolution in lookup mode to an index in [standard] mode"));
+        assertThat(
+            e.getMessage(),
+            containsString("1:25: Lookup Join requires a single lookup mode index; [test] resolves to [test] in [standard] mode")
+        );
     }
 
     public void testImplicitCasting() {

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/190_lookup_join.yml

@@ -145,15 +145,22 @@ basic:
   - match: {values.1: [2, "yellow"]}
 
 ---
-non-lookup index:
+fails with non-lookup index:
+  - requires:
+      capabilities:
+        - method: POST
+          path: /_query
+          parameters: []
+          capabilities: [update_lookup_join_error_messages]
+      reason: "checks updated error messages"
   - do:
       esql.query:
         body:
           query: 'FROM test-lookup-1 | SORT key | LOOKUP JOIN test ON key | LIMIT 3'
       catch: "bad_request"
 
   - match: { error.type: "verification_exception" }
-  - contains: { error.reason: "Found 1 problem\nline 1:45: invalid [test] resolution in lookup mode to an index in [standard] mode" }
+  - contains: { error.reason: "Found 1 problem\nline 1:45: Lookup Join requires a single lookup mode index; [test] resolves to [test] in [standard] mode" }
 
 ---
 pattern-multiple:

x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/192_lookup_join_on_aliases.yml

@@ -186,15 +186,22 @@ alias-repeated-index:
   - match: {values.1: [2, "yellow"]}
 
 ---
-alias-pattern-multiple:
+fails when alias or pattern resolves to multiple:
+  - requires:
+      capabilities:
+        - method: POST
+          path: /_query
+          parameters: []
+          capabilities: [update_lookup_join_error_messages]
+      reason: "checks updated error messages"
   - do:
       esql.query:
         body:
           query: 'FROM test-lookup-1 | LOOKUP JOIN test-lookup-alias-pattern-multiple ON key'
       catch: "bad_request"
 
   - match: { error.type: "verification_exception" }
-  - contains: { error.reason: "Found 1 problem\nline 1:34: invalid [test-lookup-alias-pattern-multiple] resolution in lookup mode to [4] indices" }
+  - contains: { error.reason: "Found 1 problem\nline 1:34: Lookup Join requires a single lookup mode index; [test-lookup-alias-pattern-multiple] resolves to [4] indices" }
 
 ---
 alias-pattern-single: