Add docs for ENRICH command (ESQL-1313)

Co-authored-by: Abdon Pijpelink <abdon.pijpelink@elastic.co>

docs/reference/esql/esql-processing-commands.asciidoc

@@ -16,6 +16,7 @@ ESQL supports these processing commands:
 
 * <<esql-dissect>>
 * <<esql-drop>>
+* <<esql-enrich>>
 * <<esql-eval>>
 * <<esql-grok>>
 * <<esql-keep>>
@@ -28,6 +29,7 @@ ESQL supports these processing commands:
 
 include::processing-commands/dissect.asciidoc[]
 include::processing-commands/drop.asciidoc[]
+include::processing-commands/enrich.asciidoc[]
 include::processing-commands/eval.asciidoc[]
 include::processing-commands/grok.asciidoc[]
 include::processing-commands/keep.asciidoc[]

docs/reference/esql/processing-commands/enrich.asciidoc

@@ -0,0 +1,60 @@
+[[esql-enrich]]
+=== `ENRICH`
+You can use `ENRICH` to add data from your existing indices to incoming records.
+It's similar to <<ingest-enriching-data, ingest enrich>>, but it works at query time.
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich-result]
+|===
+
+`ENRICH` requires an <<enrich-policy,enrich policy>> to be executed.
+The enrich policy defines a match field (a key field) and a set of enrich fields.
+
+`ENRICH` will look for records in the <<enrich-index,enrich index>> based on the match field value.
+The matching key in the input dataset can be defined using `ON <field-name>`; if it's not specified,
+the match will be performed on a field with the same name as the match field defined in the <<enrich-policy,enrich policy>>.
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_on]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_on-result]
+|===
+
+
+You can specify which attributes (between those defined as enrich fields in the policy) have to be added to the result,
+using `WITH <field1>, <field2>...` syntax.
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_with]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_with-result]
+|===
+
+
+Attributes can also be renamed using `WITH new_name=<field1>`
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_rename]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs-ignoreCsvTests.csv-spec[tag=enrich_rename-result]
+|===
+
+
+By default (if no `WITH` is defined), `ENRICH` will add all the enrich fields defined in the <<enrich-policy,enrich policy>>
+to the result.
+
+In case of name collisions, the newly created fields will override the existing fields.

x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs-ignoreCsvTests.csv-spec

@@ -0,0 +1,54 @@
+enrich
+// tag::enrich[]
+ROW language_code = "1"  
+| ENRICH languages_policy
+// end::enrich[]
+;
+
+// tag::enrich-result[]
+language_code:keyword  | language_name:keyword 
+1                      | English 
+// end::enrich-result[]       
+;
+
+
+enrichOn
+// tag::enrich_on[]
+ROW a = "1"  
+| ENRICH languages_policy ON a
+// end::enrich_on[]
+;
+
+// tag::enrich_on-result[]
+a:keyword  | language_name:keyword 
+1          | English 
+// end::enrich_on-result[]       
+;
+
+
+enrichWith
+// tag::enrich_with[]
+ROW a = "1"  
+| ENRICH languages_policy ON a WITH language_name
+// end::enrich_with[]
+;
+
+// tag::enrich_with-result[]
+a:keyword  | language_name:keyword 
+1          | English 
+// end::enrich_with-result[]       
+;
+
+
+enrichRename
+// tag::enrich_rename[]
+ROW a = "1"  
+| ENRICH languages_policy ON a WITH name = language_name
+// end::enrich_rename[]
+;
+
+// tag::enrich_rename-result[]
+a:keyword  | name:keyword 
+1          | English 
+// end::enrich_rename-result[]       
+;

x-pack/plugin/esql/qa/testFixtures/src/main/resources/enrich-ignoreCsvTests.csv-spec

@@ -1,4 +1,14 @@
 simple
+row language_code = "1"  
+| enrich languages_policy
+;
+
+language_code:keyword  | language_name:keyword 
+1                      | English 
+;
+
+
+enrichOn
 from employees  | sort emp_no | limit 1 | eval x = to_string(languages) | enrich languages_policy on x  | keep emp_no, language_name;
 
 emp_no:integer | language_name:keyword
@@ -6,7 +16,7 @@ emp_no:integer | language_name:keyword
 ;
 
 
-simple2
+enrichOn2
 from employees | eval x = to_string(languages) | enrich languages_policy on x  | keep emp_no, language_name | sort emp_no | limit 1 ;
 
 emp_no:integer | language_name:keyword

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

@@ -10,6 +10,7 @@ package org.elasticsearch.xpack.esql.plan.logical;
 import org.elasticsearch.xpack.esql.enrich.EnrichPolicyResolution;
 import org.elasticsearch.xpack.ql.capabilities.Resolvables;
 import org.elasticsearch.xpack.ql.expression.Attribute;
+import org.elasticsearch.xpack.ql.expression.EmptyAttribute;
 import org.elasticsearch.xpack.ql.expression.Expression;
 import org.elasticsearch.xpack.ql.expression.NamedExpression;
 import org.elasticsearch.xpack.ql.plan.logical.LogicalPlan;
@@ -62,7 +63,10 @@ public class Enrich extends UnaryPlan {
 
     @Override
     public boolean expressionsResolved() {
-        return policyName.resolved() && matchField.resolved() && Resolvables.resolved(enrichFields());
+        return policyName.resolved()
+            && matchField instanceof EmptyAttribute == false // matchField not defined in the query, needs to be resolved from the policy
+            && matchField.resolved()
+            && Resolvables.resolved(enrichFields());
     }
 
     @Override