Fix CHUNK and TOP_SNIPPETS documentation to include optional MapExpression params (elastic#139945)

* Fix TOP_SNIPPETS docs

* Fix CHUNK docs

* [CI] Auto commit changes from spotless

* Update x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/TopSnippets.java

Co-authored-by: Liam Thompson <[email protected]>

* Regenerate docs with updated link

* Spotless

* Replace missing period symbol

---------

Co-authored-by: elasticsearchmachine <[email protected]>
Co-authored-by: Liam Thompson <[email protected]>

Author: 3 people

docs/reference/query-languages/esql/_snippets/functions/parameters/top_snippets.md

@@ -92,16 +92,17 @@ public TopSnippets(
             """) Expression query,
         @MapParam(
             name = "options",
-            description = "Options to customize snippet extraction behavior.",
+            description = "(Optional) TopSnippets additional options as "
+                + "[function named parameters](/reference/query-languages/esql/esql-syntax.md#esql-function-named-params).",
             optional = true,
             params = {
                 @MapParam.MapParamEntry(
                     name = "num_snippets",
-                    type = { "integer" },
+                    type = "integer",
                     description = "The maximum number of matching snippets to return.",
                     valueHint = { "3" }
                 ),
-                @MapParam.MapParamEntry(name = "num_words", type = { "integer" }, description = """
+                @MapParam.MapParamEntry(name = "num_words", type = "integer", description = """
                     The maximum number of words to return in each snippet.
                     This allows better control of inference costs by limiting the size of tokens per snippet.
                     """, valueHint = { "300" }) }

docs/reference/query-languages/esql/_snippets/functions/types/chunk.md

@@ -36,6 +36,7 @@
 
 import static org.elasticsearch.compute.data.BlockUtils.toJavaObject;
 import static org.elasticsearch.xpack.core.inference.chunking.ChunkingSettingsTests.createRandomChunkingSettings;
+import static org.elasticsearch.xpack.esql.core.type.DataType.UNSUPPORTED;
 import static org.elasticsearch.xpack.esql.expression.function.scalar.string.Chunk.ALLOWED_CHUNKING_SETTING_OPTIONS;
 import static org.elasticsearch.xpack.esql.expression.function.scalar.string.Chunk.DEFAULT_CHUNKING_SETTINGS;
 import static org.elasticsearch.xpack.esql.expression.function.scalar.util.ChunkUtils.chunkText;
@@ -64,42 +65,70 @@ private static String randomWordsBetween(int min, int max) {
 
     @ParametersFactory
     public static Iterable<Object[]> parameters() {
-        return parameterSuppliersFromTypedDataWithDefaultChecks(
-            true,
-            List.of(new TestCaseSupplier("Chunk with defaults", List.of(DataType.KEYWORD), () -> {
-                String text = randomWordsBetween(25, 50);
-                ChunkingSettings chunkingSettings = new SentenceBoundaryChunkingSettings(Chunk.DEFAULT_CHUNK_SIZE, 0);
+        return parameterSuppliersFromTypedData(testCaseSuppliers());
+    }
 
-                List<String> chunks = chunkText(text, chunkingSettings);
-                Object expectedResult = chunks.size() == 1
-                    ? new BytesRef(chunks.get(0).trim())
-                    : chunks.stream().map(s -> new BytesRef(s.trim())).toList();
+    private static List<TestCaseSupplier> testCaseSuppliers() {
+        List<TestCaseSupplier> suppliers = new ArrayList<>();
+        suppliers.add(createTestCaseSupplier("Chunk with defaults", DataType.KEYWORD));
+        suppliers.add(createTestCaseSupplier("Chunk with defaults text input", DataType.TEXT));
+        return addFunctionNamedParams(suppliers);
+    }
 
-                return new TestCaseSupplier.TestCase(
-                    List.of(new TestCaseSupplier.TypedData(new BytesRef(text), DataType.KEYWORD, "str")),
-                    "ChunkBytesRefEvaluator[str=Attribute[channel=0], "
-                        + "chunkingSettings={\"strategy\":\"sentence\",\"max_chunk_size\":300,\"sentence_overlap\":0}]",
-                    DataType.KEYWORD,
-                    equalTo(expectedResult)
-                );
-            }), new TestCaseSupplier("Chunk with defaults text input", List.of(DataType.TEXT), () -> {
+    private static TestCaseSupplier createTestCaseSupplier(String description, DataType fieldDataType) {
+        return new TestCaseSupplier(description, List.of(fieldDataType), () -> {
+            String text = randomWordsBetween(25, 50);
+            ChunkingSettings chunkingSettings = new SentenceBoundaryChunkingSettings(Chunk.DEFAULT_CHUNK_SIZE, 0);
+
+            List<String> chunks = chunkText(text, chunkingSettings);
+            Object expectedResult = chunks.size() == 1
+                ? new BytesRef(chunks.get(0).trim())
+                : chunks.stream().map(s -> new BytesRef(s.trim())).toList();
+
+            return new TestCaseSupplier.TestCase(
+                List.of(new TestCaseSupplier.TypedData(new BytesRef(text), fieldDataType, "str")),
+                "ChunkBytesRefEvaluator[str=Attribute[channel=0], "
+                    + "chunkingSettings={\"strategy\":\"sentence\",\"max_chunk_size\":300,\"sentence_overlap\":0}]",
+                DataType.KEYWORD,
+                equalTo(expectedResult)
+            );
+        });
+    }
+
+    /**
+     * Adds function named parameters to all the test case suppliers provided
+     */
+    private static List<TestCaseSupplier> addFunctionNamedParams(List<TestCaseSupplier> suppliers) {
+        List<TestCaseSupplier> result = new ArrayList<>(suppliers);
+        for (TestCaseSupplier supplier : suppliers) {
+            List<DataType> dataTypes = new ArrayList<>(supplier.types());
+            dataTypes.add(UNSUPPORTED);
+            result.add(new TestCaseSupplier(supplier.name() + ", with chunking_settings", dataTypes, () -> {
                 String text = randomWordsBetween(25, 50);
-                ChunkingSettings chunkingSettings = new SentenceBoundaryChunkingSettings(Chunk.DEFAULT_CHUNK_SIZE, 0);
+                int chunkSize = 25;
+                ChunkingSettings chunkingSettings = new SentenceBoundaryChunkingSettings(chunkSize, 0);
 
                 List<String> chunks = chunkText(text, chunkingSettings);
                 Object expectedResult = chunks.size() == 1
                     ? new BytesRef(chunks.get(0).trim())
                     : chunks.stream().map(s -> new BytesRef(s.trim())).toList();
 
+                List<TestCaseSupplier.TypedData> values = List.of(
+                    new TestCaseSupplier.TypedData(new BytesRef(text), supplier.types().get(0), "str"),
+                    new TestCaseSupplier.TypedData(createChunkingSettings(chunkingSettings), UNSUPPORTED, "chunking_settings")
+                        .forceLiteral()
+                );
+
                 return new TestCaseSupplier.TestCase(
-                    List.of(new TestCaseSupplier.TypedData(new BytesRef(text), DataType.TEXT, "str")),
+                    values,
                     "ChunkBytesRefEvaluator[str=Attribute[channel=0], "
-                        + "chunkingSettings={\"strategy\":\"sentence\",\"max_chunk_size\":300,\"sentence_overlap\":0}]",
+                        + "chunkingSettings={\"strategy\":\"sentence\",\"max_chunk_size\":25,\"sentence_overlap\":0}]",
                     DataType.KEYWORD,
                     equalTo(expectedResult)
                 );
-            }))
-        );
+            }));
+        }
+        return result;
     }
 
     private static MapExpression createChunkingSettings(ChunkingSettings chunkingSettings) {
@@ -131,6 +160,16 @@ protected Expression build(Source source, List<Expression> args) {
         return new Chunk(source, args.get(0), options);
     }
 
+    @Override
+    public void testFold() {
+        Expression expression = buildFieldExpression(testCase);
+        // Skip testFold if the expression is not foldable (e.g., when chunking_settings contains MapExpression)
+        if (expression.foldable() == false) {
+            return;
+        }
+        super.testFold();
+    }
+
     public void testDefaults() {
         // Default of 300 is huge, only one chunk returned in this case
         verifyChunks(null, 1);