Support types table in lookup join docs

Author: craigtaverner

docs/reference/query-languages/esql/_snippets/commands/layout/lookup-join.md

@@ -81,3 +81,6 @@ before the lookup when possible.
 
 :::{include} ../examples/lookup-join.csv-spec/filterOnRightSide.md
 :::
+
+:::{include} ../types/lookup-join.md
+:::

docs/reference/query-languages/esql/_snippets/commands/types/lookup-join.md

@@ -0,0 +1,77 @@
+% This is generated by ESQL's AbstractFunctionTestCase. Do not edit it. See ../README.md for how to regenerate it.
+
+**Supported types**
+
+| main | join | result |
+| --- | --- | --- |
+| boolean | boolean | boolean |
+| byte | byte | byte |
+| byte | double | double |
+| byte | float | float |
+| byte | half_float | half_float |
+| byte | integer | integer |
+| byte | long | long |
+| byte | scaled_float | scaled_float |
+| byte | short | short |
+| date | date | date |
+| date_nanos | date_nanos | date_nanos |
+| double | byte | double |
+| double | double | double |
+| double | float | double |
+| double | half_float | double |
+| double | integer | double |
+| double | long | double |
+| double | scaled_float | scaled_float |
+| double | short | double |
+| float | byte | float |
+| float | double | double |
+| float | float | float |
+| float | half_float | half_float |
+| float | integer | float |
+| float | long | float |
+| float | scaled_float | scaled_float |
+| float | short | float |
+| half_float | byte | half_float |
+| half_float | double | double |
+| half_float | float | float |
+| half_float | half_float | half_float |
+| half_float | integer | half_float |
+| half_float | long | half_float |
+| half_float | scaled_float | scaled_float |
+| half_float | short | half_float |
+| integer | byte | integer |
+| integer | double | double |
+| integer | float | float |
+| integer | half_float | half_float |
+| integer | integer | integer |
+| integer | long | long |
+| integer | scaled_float | scaled_float |
+| integer | short | integer |
+| ip | ip | ip |
+| keyword | keyword | keyword |
+| long | byte | long |
+| long | double | double |
+| long | float | float |
+| long | half_float | half_float |
+| long | integer | long |
+| long | long | long |
+| long | scaled_float | scaled_float |
+| long | short | long |
+| scaled_float | byte | scaled_float |
+| scaled_float | double | double |
+| scaled_float | float | scaled_float |
+| scaled_float | half_float | scaled_float |
+| scaled_float | integer | scaled_float |
+| scaled_float | long | scaled_float |
+| scaled_float | scaled_float | scaled_float |
+| scaled_float | short | scaled_float |
+| short | byte | short |
+| short | double | double |
+| short | float | float |
+| short | half_float | half_float |
+| short | integer | integer |
+| short | long | long |
+| short | scaled_float | scaled_float |
+| short | short | short |
+| text | keyword | keyword |
+

docs/reference/query-languages/esql/esql-lookup-join.md

@@ -153,8 +153,16 @@ To use `LOOKUP JOIN`, the following requirements must be met:
   * For text fields: You can only use text fields as the join key on the left-hand side of the join and only if they have a `.keyword` subfield
 
 To obtain a join key with a compatible type, use a [conversion function](/reference/query-languages/esql/functions-operators/type-conversion-functions.md) if needed.
+* Both `KEYWORD` and `TEXT` are supported in the main index, but can only join against `KEYWORD` in the join index.
+* All numerical types are supported as join keys, using the same rules as applicable to the `==` operator when performing the join. FOr example, a `double` can be joined with an `integer`.
+* `DATE` and `DATE_NONES` can only be joined against the exact same type.
+* `IP` is supported, but `VERSION` is not.
 
-For a complete list of supported data types and their internal representations, see the [Supported Field Types documentation](/reference/query-languages/esql/limitations.md#_supported_types).
+The list of unsupported fields includes all types not supported by {{esql}} as described in the [Unsupported Field Types documentation](/reference/query-languages/esql/limitations.md#_unsupported_types).
+as well as the following: `VERSION`, `UNSIGNED_LONG`, all spatial types like `GEO_POINT`, `GEO_SHAPE`, and all
+temporal periods like `DURATION` and `PERIOD`.
+
+For a complete list of all types supported in `LOOKUP JOIN`, refer to the [`LOOKUP JOIN` supported types table](/reference/query-languages/esql/commands/processing-commands#esql-lookup-join).
 
 ## Usage notes
 

x-pack/plugin/esql/build.gradle

@@ -226,6 +226,45 @@ tasks.named("test").configure {
   }
 }
 
+tasks.named("internalClusterTest").configure {
+  if (buildParams.ci == false) {
+    systemProperty 'generateDocs', true
+    def injected = project.objects.newInstance(Injected)
+    // Define the folder to delete and recreate
+    def tempDir = file("build/testrun/internalClusterTest/temp/esql")
+    doFirst {
+      injected.fs.delete {
+        it.delete(tempDir)
+      }
+      // Re-create this folder so we can save a table of generated examples to extract from csv-spec tests
+      tempDir.mkdirs() // Recreate the folder
+    }
+    File snippetsFolder = file("build/testrun/internalClusterTest/temp/esql/_snippets")
+    def snippetsDocFolder = file("${rootDir}/docs/reference/query-languages/esql/_snippets")
+    def snippetsTree = fileTree(snippetsFolder).matching {
+      include "**/types/*.md"  // Recursively include all types/*.md files (effectively counting functions and operators)
+    }
+
+    doLast {
+      def snippets = snippetsTree.files.collect { it.name }
+      int countSnippets = snippets.size()
+      if (countSnippets == 0) {
+        logger.quiet("ESQL Docs: No function/operator snippets created. Skipping sync.")
+      } else {
+        logger.quiet("ESQL Docs: Found $countSnippets generated function/operator snippets to patch into docs")
+        injected.fs.sync {
+          from snippetsFolder
+          into snippetsDocFolder
+          include '**/*.md'
+          preserve {
+            include '**/*.md'
+          }
+        }
+      }
+    }
+  }
+}
+
 /****************************************************************
  *  Enable QA/rest integration tests for snapshot builds only   *
  *  TODO: Enable for all builds upon this feature release       *

x-pack/plugin/esql/src/internalClusterTest/java/org/elasticsearch/xpack/esql/action/LookupJoinTypesIT.java

@@ -19,8 +19,11 @@
 import org.elasticsearch.xpack.core.esql.action.ColumnInfo;
 import org.elasticsearch.xpack.esql.VerificationException;
 import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.DocsV3Support;
+import org.elasticsearch.xpack.esql.expression.function.EsqlFunctionRegistry;
 import org.elasticsearch.xpack.esql.plan.logical.join.Join;
 import org.elasticsearch.xpack.esql.plugin.EsqlPlugin;
+import org.elasticsearch.xpack.esql.type.EsqlDataTypeConverter;
 import org.elasticsearch.xpack.spatial.SpatialPlugin;
 import org.elasticsearch.xpack.unsignedlong.UnsignedLongMapperPlugin;
 import org.elasticsearch.xpack.versionfield.VersionFieldPlugin;
@@ -36,6 +39,7 @@
 import java.util.Map;
 import java.util.Set;
 import java.util.function.Consumer;
+import java.util.function.Supplier;
 import java.util.stream.Collectors;
 
 import static org.elasticsearch.test.ESIntegTestCase.Scope.SUITE;
@@ -265,6 +269,22 @@ private static boolean existingIndex(Collection<TestConfigs> existing, DataType
         return existing.stream().anyMatch(c -> c.exists(indexName));
     }
 
+    public void testOutputSupportedTypes() throws Exception {
+        Map<List<DataType>, DataType> signatures = new LinkedHashMap<>();
+        for (TestConfigs configs : testConfigurations.values()) {
+            if (configs.group.equals("unsupported") || configs.group.equals("union-types")) {
+                continue;
+            }
+            for (TestConfig config : configs.configs.values()) {
+                if (config instanceof TestConfigPasses) {
+                    DataType commonType = EsqlDataTypeConverter.commonType(config.mainType(), config.lookupType());
+                    signatures.put(List.of(config.mainType(), config.lookupType()), commonType);
+                }
+            }
+        }
+        saveJoinTypes(() -> signatures);
+    }
+
     public void testLookupJoinStrings() {
         testLookupJoinTypes("strings");
     }
@@ -747,4 +767,18 @@ public void doTest() {
     private boolean isValidDataType(DataType dataType) {
         return UNDER_CONSTRUCTION.get(dataType) == null || UNDER_CONSTRUCTION.get(dataType).isEnabled();
     }
+
+    private static void saveJoinTypes(Supplier<Map<List<DataType>, DataType>> signatures) throws Exception {
+        ArrayList<EsqlFunctionRegistry.ArgSignature> args = new ArrayList<>();
+        args.add(new EsqlFunctionRegistry.ArgSignature("main", null, "Field from the main index", false, false));
+        args.add(new EsqlFunctionRegistry.ArgSignature("join", null, "Field from the join index", false, false));
+        DocsV3Support.CommandsDocsSupport docs = new DocsV3Support.CommandsDocsSupport(
+            "lookup-join",
+            LookupJoinTypesIT.class,
+            null,
+            args,
+            signatures
+        );
+        docs.renderDocs();
+    }
 }

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/DocsV3Support.java

@@ -836,23 +836,45 @@ void renderDetailedDescription(String detailedDescription, String note) throws I
     /** Command specific docs generating, currently very empty since we only render kibana definition files */
     public static class CommandsDocsSupport extends DocsV3Support {
         private final LogicalPlan command;
+        private List<EsqlFunctionRegistry.ArgSignature> args;
         private final XPackLicenseState licenseState;
 
+        /** Used in CommandLicenseTests to generate Kibana docs with licensing information for commands */
         public CommandsDocsSupport(String name, Class<?> testClass, LogicalPlan command, XPackLicenseState licenseState) {
             super("commands", name, testClass, Map::of);
             this.command = command;
             this.licenseState = licenseState;
         }
 
+        /** Used in LookupJoinTypesIT to generate table of supported types for join field */
+        public CommandsDocsSupport(
+            String name,
+            Class<?> testClass,
+            LogicalPlan command,
+            List<EsqlFunctionRegistry.ArgSignature> args,
+            Supplier<Map<List<DataType>, DataType>> signatures
+        ) {
+            super("commands", name, testClass, signatures);
+            this.command = command;
+            this.args = args;
+            this.licenseState = null;
+        }
+
         @Override
         public void renderSignature() throws IOException {
             // Unimplemented until we make command docs dynamically generated
         }
 
         @Override
         public void renderDocs() throws Exception {
-            // Currently we only render kibana definition files, but we could expand to rendering much more if we decide to
-            renderKibanaCommandDefinition();
+            // Currently we only render either signatures or kibana definition files,
+            // but we could expand to rendering much more if we decide to
+            if (args != null) {
+                renderTypes(name, args);
+            }
+            if (licenseState != null) {
+                renderKibanaCommandDefinition();
+            }
         }
 
         void renderKibanaCommandDefinition() throws Exception {