getNamedWriteables() {
entries.add(Greatest.ENTRY);
entries.add(CopySign.ENTRY);
entries.add(Hash.ENTRY);
+ entries.add(JsonExtract.ENTRY);
entries.add(Hypot.ENTRY);
entries.add(In.ENTRY);
entries.add(InsensitiveEquals.ENTRY);
diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtract.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtract.java
new file mode 100644
index 0000000000000..13c2921e35949
--- /dev/null
+++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtract.java
@@ -0,0 +1,414 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.scalar.string;
+
+import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.common.io.stream.NamedWriteableRegistry;
+import org.elasticsearch.common.io.stream.StreamInput;
+import org.elasticsearch.common.io.stream.StreamOutput;
+import org.elasticsearch.compute.ann.Evaluator;
+import org.elasticsearch.compute.data.BytesRefBlock;
+import org.elasticsearch.compute.operator.EvalOperator.ExpressionEvaluator;
+import org.elasticsearch.xcontent.XContentParseException;
+import org.elasticsearch.xcontent.XContentParser;
+import org.elasticsearch.xcontent.XContentParserConfiguration;
+import org.elasticsearch.xcontent.json.JsonXContent;
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.NodeInfo;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.Example;
+import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
+import org.elasticsearch.xpack.esql.expression.function.Param;
+import org.elasticsearch.xpack.esql.expression.function.scalar.EsqlScalarFunction;
+import org.elasticsearch.xpack.esql.io.stream.PlanStreamInput;
+
+import java.io.IOException;
+import java.util.Arrays;
+import java.util.List;
+
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.ParamOrdinal.FIRST;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.ParamOrdinal.SECOND;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isString;
+import static org.elasticsearch.xpack.esql.core.expression.TypeResolutions.isType;
+
+public class JsonExtract extends EsqlScalarFunction {
+ /**
+ * Internal exception used to distinguish application-level errors (path not found,
+ * array index out of bounds) from JSON parser errors (malformed JSON).
+ *
+ * This is necessary because {@link XContentParseException} extends {@link IllegalArgumentException}.
+ * Without a separate exception type, we couldn't differentiate between:
+ *
+ * - Our errors (should preserve the specific message like "path [x] does not exist")
+ * - Parser errors (should be converted to generic "invalid JSON input")
+ *
+ */
+ private static class JsonExtractException extends Exception {
+ JsonExtractException(String message) {
+ super(message);
+ }
+ }
+
+ public static final NamedWriteableRegistry.Entry ENTRY = new NamedWriteableRegistry.Entry(
+ Expression.class,
+ "JsonExtract",
+ JsonExtract::new
+ );
+
+ private final Expression jsonInput;
+ private final Expression path;
+
+ @FunctionInfo(
+ returnType = "keyword",
+ description = """
+ Extracts a value from a JSON string using a dot-notation path expression.
+ Path matching is case-sensitive (per the JSON specification).
+ Returns the extracted value as a keyword string. String values are returned without
+ surrounding quotes, numbers and booleans are returned as their string representation,
+ and objects or arrays are returned as JSON strings. Returns `null` if either parameter
+ is `null` or if the extracted JSON value is `null`. Returns `null` and emits a warning
+ if the input is not valid JSON, the path does not exist, the array index is out of bounds,
+ or the path attempts to traverse through a non-object/non-array value.""",
+ examples = {
+ @Example(file = "json_extract", tag = "json_extract"),
+ @Example(file = "json_extract", tag = "json_extract_nested", description = "Extract a nested value using dot-notation:") }
+ )
+ public JsonExtract(
+ Source source,
+ @Param(
+ name = "json_input",
+ type = { "keyword", "text", "_source" },
+ description = "A string containing valid JSON, or the `_source` field. If `null`, the function returns `null`."
+ ) Expression jsonInput,
+ @Param(
+ name = "path",
+ type = { "keyword", "text" },
+ description = "A dot-notation path expression identifying the value to extract. "
+ + "Use dot notation for nested fields (e.g., `user.name`) and bracket notation "
+ + "for array indices (e.g., `items[0]`). If `null`, the function returns `null`."
+ ) Expression path
+ ) {
+ super(source, Arrays.asList(jsonInput, path));
+ this.jsonInput = jsonInput;
+ this.path = path;
+ }
+
+ private JsonExtract(StreamInput in) throws IOException {
+ this(Source.readFrom((PlanStreamInput) in), in.readNamedWriteable(Expression.class), in.readNamedWriteable(Expression.class));
+ }
+
+ @Override
+ public void writeTo(StreamOutput out) throws IOException {
+ source().writeTo(out);
+ out.writeNamedWriteable(jsonInput);
+ out.writeNamedWriteable(path);
+ }
+
+ @Override
+ public String getWriteableName() {
+ return ENTRY.name;
+ }
+
+ @Override
+ public DataType dataType() {
+ return DataType.KEYWORD;
+ }
+
+ /**
+ * Returns true if the given type is a string type or SOURCE (for _source field).
+ */
+ private static boolean isStringOrSource(DataType t) {
+ return DataType.isString(t) || t == DataType.SOURCE;
+ }
+
+ @Override
+ protected TypeResolution resolveType() {
+ if (childrenResolved() == false) {
+ return new TypeResolution("Unresolved children");
+ }
+
+ // First parameter accepts string types or SOURCE (for _source field)
+ TypeResolution resolution = isType(jsonInput, JsonExtract::isStringOrSource, sourceText(), FIRST, "keyword", "text", "_source");
+ if (resolution.unresolved()) {
+ return resolution;
+ }
+ resolution = isString(path, sourceText(), SECOND);
+ if (resolution.unresolved()) {
+ return resolution;
+ }
+
+ return TypeResolution.TYPE_RESOLVED;
+ }
+
+ @Override
+ public boolean foldable() {
+ return jsonInput.foldable() && path.foldable();
+ }
+
+ /**
+ * Parses a path string into segments, converting bracket notation to segments.
+ * E.g., "orders[1].item" -> ["orders", "1", "item"]
+ */
+ private static String[] parsePath(String path) {
+ if (path.isEmpty()) {
+ return new String[0];
+ }
+ // Convert bracket notation to dot notation: "orders[1].item" -> "orders.1.item"
+ String converted = path.replace("[", ".").replace("]", "");
+ return converted.split("\\.");
+ }
+
+ @Evaluator(warnExceptions = IllegalArgumentException.class)
+ static void process(BytesRefBlock.Builder builder, BytesRef jsonInput, BytesRef path) {
+ String jsonStr = jsonInput.utf8ToString();
+ String pathStr = path.utf8ToString();
+ String[] pathSegments = parsePath(pathStr);
+
+ try (XContentParser parser = JsonXContent.jsonXContent.createParser(XContentParserConfiguration.EMPTY, jsonStr)) {
+ XContentParser.Token token = parser.nextToken();
+ if (token == null) {
+ throw new JsonExtractException("invalid JSON input");
+ }
+ extractValue(builder, parser, pathSegments, 0, pathStr);
+ } catch (JsonExtractException e) {
+ throw new IllegalArgumentException(e.getMessage());
+ } catch (IOException | XContentParseException e) {
+ // JSON parsing errors
+ throw new IllegalArgumentException("invalid JSON input");
+ }
+ }
+
+ /**
+ * Recursively navigates the JSON stream to extract the value at the given path.
+ *
+ * This method uses streaming parsing to avoid creating intermediate objects for paths
+ * we don't need. It walks through the JSON structure one token at a time, descending
+ * only into the path segments we care about and skipping everything else.
+ *
+ * The recursion works as follows:
+ *
+ * - If we've consumed all path segments ({@code depth == pathSegments.length}),
+ * we've reached the target value - extract it.
+ * - If the current token is an object, iterate through its fields looking for
+ * a key matching the current segment. Skip non-matching fields entirely.
+ * - If the current token is an array, the segment must be a numeric index.
+ * Iterate through elements, skipping until we reach the target index.
+ * - If the current token is a scalar (string, number, boolean, null) but we
+ * still have path segments to consume, the path is invalid.
+ *
+ *
+ * @param builder the block builder to append the extracted value to
+ * @param parser the JSON parser positioned at the current token
+ * @param pathSegments the path split into segments (e.g., ["user", "address", "city"])
+ * @param depth current position in pathSegments (0-indexed)
+ * @param originalPath the original path string for error messages
+ */
+ private static void extractValue(
+ BytesRefBlock.Builder builder,
+ XContentParser parser,
+ String[] pathSegments,
+ int depth,
+ String originalPath
+ ) throws IOException, JsonExtractException {
+ XContentParser.Token token = parser.currentToken();
+
+ // Base case: we've consumed all path segments, so the parser is now positioned
+ // at the value we want to extract
+ if (depth == pathSegments.length) {
+ extractCurrentValue(builder, parser);
+ return;
+ }
+
+ String segment = pathSegments[depth];
+
+ if (token == XContentParser.Token.START_OBJECT) {
+ // Current value is an object - look for a field matching the current path segment.
+ // We iterate through all fields: FIELD_NAME token followed by the field's value.
+ while ((token = parser.nextToken()) != XContentParser.Token.END_OBJECT) {
+ if (token == XContentParser.Token.FIELD_NAME) {
+ String fieldName = parser.currentName();
+ parser.nextToken(); // Advance from FIELD_NAME to the field's value
+ if (fieldName.equals(segment)) {
+ // Found the matching key - recurse to process the next path segment
+ extractValue(builder, parser, pathSegments, depth + 1, originalPath);
+ return;
+ } else {
+ // Not the key we want - skip this field's entire value (including nested structures)
+ parser.skipChildren();
+ }
+ }
+ }
+ // Exhausted all fields without finding a match
+ throw new JsonExtractException("path [" + originalPath + "] does not exist");
+
+ } else if (token == XContentParser.Token.START_ARRAY) {
+ // Current value is an array - the path segment must be a numeric index.
+ int targetIndex;
+ try {
+ targetIndex = Integer.parseInt(segment);
+ } catch (NumberFormatException e) {
+ // Path segment isn't a number, but we're at an array - path is invalid
+ throw new JsonExtractException("path [" + originalPath + "] does not exist");
+ }
+ if (targetIndex < 0) {
+ throw new JsonExtractException("array index out of bounds");
+ }
+
+ // Iterate through array elements until we reach the target index
+ int currentIndex = 0;
+ while ((token = parser.nextToken()) != XContentParser.Token.END_ARRAY) {
+ if (currentIndex == targetIndex) {
+ // Found the target element - recurse to process the next path segment
+ extractValue(builder, parser, pathSegments, depth + 1, originalPath);
+ return;
+ }
+ // Not the index we want - skip this element entirely
+ parser.skipChildren();
+ currentIndex++;
+ }
+ // Reached end of array without finding the target index
+ throw new JsonExtractException("array index out of bounds");
+
+ } else {
+ // Current value is a scalar (string, number, boolean, null), but we still have
+ // path segments to consume. Can't traverse into a scalar value.
+ throw new JsonExtractException("path [" + originalPath + "] does not exist");
+ }
+ }
+
+ /**
+ * Extracts the current value from the parser and appends it to the builder.
+ */
+ private static void extractCurrentValue(BytesRefBlock.Builder builder, XContentParser parser) throws IOException {
+ XContentParser.Token token = parser.currentToken();
+
+ switch (token) {
+ case VALUE_STRING -> builder.appendBytesRef(new BytesRef(parser.text()));
+ case VALUE_NUMBER -> builder.appendBytesRef(new BytesRef(parser.text()));
+ case VALUE_BOOLEAN -> builder.appendBytesRef(new BytesRef(Boolean.toString(parser.booleanValue())));
+ case VALUE_NULL -> builder.appendNull();
+ case START_OBJECT, START_ARRAY -> {
+ // For objects and arrays, we need to serialize them back to JSON
+ // Use the parser's built-in copyCurrentStructure would require an XContentBuilder
+ // Instead, we'll read the raw text - but XContentParser doesn't give us that easily
+ // So we fall back to building the structure
+ StringBuilder sb = new StringBuilder();
+ copyCurrentStructure(sb, parser);
+ builder.appendBytesRef(new BytesRef(sb.toString()));
+ }
+ default -> throw new IllegalArgumentException("unexpected token: " + token);
+ }
+ }
+
+ /**
+ * Copies the current JSON structure (object or array) to a StringBuilder.
+ */
+ private static void copyCurrentStructure(StringBuilder sb, XContentParser parser) throws IOException {
+ XContentParser.Token token = parser.currentToken();
+
+ if (token == XContentParser.Token.START_OBJECT) {
+ sb.append('{');
+ boolean first = true;
+ while ((token = parser.nextToken()) != XContentParser.Token.END_OBJECT) {
+ if (token == XContentParser.Token.FIELD_NAME) {
+ if (first == false) {
+ sb.append(',');
+ }
+ first = false;
+ sb.append('"').append(escapeJson(parser.currentName())).append("\":");
+ parser.nextToken();
+ copyValue(sb, parser);
+ }
+ }
+ sb.append('}');
+ } else if (token == XContentParser.Token.START_ARRAY) {
+ sb.append('[');
+ boolean first = true;
+ while ((token = parser.nextToken()) != XContentParser.Token.END_ARRAY) {
+ if (first == false) {
+ sb.append(',');
+ }
+ first = false;
+ copyValue(sb, parser);
+ }
+ sb.append(']');
+ }
+ }
+
+ /**
+ * Copies the current value to a StringBuilder.
+ */
+ private static void copyValue(StringBuilder sb, XContentParser parser) throws IOException {
+ XContentParser.Token token = parser.currentToken();
+
+ switch (token) {
+ case VALUE_STRING -> sb.append('"').append(escapeJson(parser.text())).append('"');
+ case VALUE_NUMBER -> sb.append(parser.text());
+ case VALUE_BOOLEAN -> sb.append(parser.booleanValue());
+ case VALUE_NULL -> sb.append("null");
+ case START_OBJECT, START_ARRAY -> copyCurrentStructure(sb, parser);
+ default -> throw new IllegalArgumentException("unexpected token: " + token);
+ }
+ }
+
+ /**
+ * Escapes special characters in a JSON string.
+ */
+ private static String escapeJson(String s) {
+ StringBuilder sb = null;
+ for (int i = 0; i < s.length(); i++) {
+ char c = s.charAt(i);
+ String escape = switch (c) {
+ case '"' -> "\\\"";
+ case '\\' -> "\\\\";
+ case '\b' -> "\\b";
+ case '\f' -> "\\f";
+ case '\n' -> "\\n";
+ case '\r' -> "\\r";
+ case '\t' -> "\\t";
+ default -> null;
+ };
+ if (escape != null) {
+ if (sb == null) {
+ sb = new StringBuilder(s.length() + 16);
+ sb.append(s, 0, i);
+ }
+ sb.append(escape);
+ } else if (sb != null) {
+ sb.append(c);
+ }
+ }
+ return sb == null ? s : sb.toString();
+ }
+
+ @Override
+ public Expression replaceChildren(List newChildren) {
+ return new JsonExtract(source(), newChildren.get(0), newChildren.get(1));
+ }
+
+ @Override
+ protected NodeInfo info() {
+ return NodeInfo.create(this, JsonExtract::new, jsonInput, path);
+ }
+
+ @Override
+ public ExpressionEvaluator.Factory toEvaluator(ToEvaluator toEvaluator) {
+ ExpressionEvaluator.Factory jsonInputExpr = toEvaluator.apply(jsonInput);
+ ExpressionEvaluator.Factory pathExpr = toEvaluator.apply(path);
+ return new JsonExtractEvaluator.Factory(source(), jsonInputExpr, pathExpr);
+ }
+
+ Expression jsonInput() {
+ return jsonInput;
+ }
+
+ Expression path() {
+ return path;
+ }
+}
diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractErrorTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractErrorTests.java
new file mode 100644
index 0000000000000..edcbf192be93d
--- /dev/null
+++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractErrorTests.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.scalar.string;
+
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.ErrorsForCasesWithoutExamplesTestCase;
+import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
+import org.hamcrest.Matcher;
+
+import java.util.List;
+import java.util.Set;
+
+import static org.hamcrest.Matchers.equalTo;
+
+public class JsonExtractErrorTests extends ErrorsForCasesWithoutExamplesTestCase {
+ @Override
+ protected List cases() {
+ return paramsToSuppliers(JsonExtractTests.parameters());
+ }
+
+ @Override
+ protected Expression build(Source source, List args) {
+ return new JsonExtract(source, args.get(0), args.get(1));
+ }
+
+ @Override
+ protected Matcher expectedTypeErrorMatcher(List> validPerPosition, List signature) {
+ // First parameter accepts keyword, text, or _source; second parameter accepts string
+ return equalTo(typeErrorMessage(true, validPerPosition, signature, (v, p) -> p == 0 ? "keyword, text or _source" : "string"));
+ }
+}
diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractSerializationTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractSerializationTests.java
new file mode 100644
index 0000000000000..dd7f8f06a70d7
--- /dev/null
+++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractSerializationTests.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.scalar.string;
+
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.expression.AbstractExpressionSerializationTests;
+
+import java.io.IOException;
+
+public class JsonExtractSerializationTests extends AbstractExpressionSerializationTests {
+ @Override
+ protected JsonExtract createTestInstance() {
+ Source source = randomSource();
+ Expression jsonInput = randomChild();
+ Expression path = randomChild();
+ return new JsonExtract(source, jsonInput, path);
+ }
+
+ @Override
+ protected JsonExtract mutateInstance(JsonExtract instance) throws IOException {
+ Source source = instance.source();
+ Expression jsonInput = instance.jsonInput();
+ Expression path = instance.path();
+ switch (between(0, 1)) {
+ case 0 -> jsonInput = randomValueOtherThan(jsonInput, AbstractExpressionSerializationTests::randomChild);
+ case 1 -> path = randomValueOtherThan(path, AbstractExpressionSerializationTests::randomChild);
+ }
+ return new JsonExtract(source, jsonInput, path);
+ }
+}
diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractTests.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractTests.java
new file mode 100644
index 0000000000000..07f01d5d817fd
--- /dev/null
+++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/JsonExtractTests.java
@@ -0,0 +1,199 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+
+package org.elasticsearch.xpack.esql.expression.function.scalar.string;
+
+import com.carrotsearch.randomizedtesting.annotations.Name;
+import com.carrotsearch.randomizedtesting.annotations.ParametersFactory;
+
+import org.apache.lucene.util.BytesRef;
+import org.elasticsearch.xpack.esql.core.expression.Expression;
+import org.elasticsearch.xpack.esql.core.tree.Source;
+import org.elasticsearch.xpack.esql.core.type.DataType;
+import org.elasticsearch.xpack.esql.expression.function.AbstractScalarFunctionTestCase;
+import org.elasticsearch.xpack.esql.expression.function.TestCaseSupplier;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.Supplier;
+
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.nullValue;
+
+/**
+ * Tests for {@link JsonExtract} function.
+ */
+public class JsonExtractTests extends AbstractScalarFunctionTestCase {
+ public JsonExtractTests(@Name("TestCase") Supplier testCaseSupplier) {
+ this.testCase = testCaseSupplier.get();
+ }
+
+ @ParametersFactory
+ public static Iterable parameters() {
+ List suppliers = new ArrayList<>();
+
+ // Randomized test across string type combinations
+ for (DataType jsonType : DataType.stringTypes()) {
+ for (DataType pathType : DataType.stringTypes()) {
+ suppliers.add(
+ new TestCaseSupplier(
+ "extract string " + TestCaseSupplier.nameFromTypes(types(jsonType, pathType)),
+ types(jsonType, pathType),
+ () -> new TestCaseSupplier.TestCase(
+ List.of(
+ new TestCaseSupplier.TypedData(new BytesRef("{\"name\":\"Alice\"}"), jsonType, "jsonInput"),
+ new TestCaseSupplier.TypedData(new BytesRef("name"), pathType, "path")
+ ),
+ expectedToString(),
+ DataType.KEYWORD,
+ equalTo(new BytesRef("Alice"))
+ )
+ )
+ );
+ }
+ }
+
+ // String value extraction
+ suppliers.add(supplier("{\"name\":\"Alice\",\"age\":30}", "name", new BytesRef("Alice")));
+
+ // Number extraction (returned as keyword string)
+ suppliers.add(supplier("{\"name\":\"Alice\",\"age\":30}", "age", new BytesRef("30")));
+
+ // Boolean extraction
+ suppliers.add(supplier("{\"active\":true}", "active", new BytesRef("true")));
+ suppliers.add(supplier("{\"active\":false}", "active", new BytesRef("false")));
+
+ // Nested field extraction
+ suppliers.add(supplier("{\"user\":{\"address\":{\"city\":\"London\"}}}", "user.address.city", new BytesRef("London")));
+
+ // Array index extraction
+ suppliers.add(supplier("{\"tags\":[\"a\",\"b\",\"c\"]}", "tags[0]", new BytesRef("a")));
+ suppliers.add(supplier("{\"tags\":[\"a\",\"b\",\"c\"]}", "tags[2]", new BytesRef("c")));
+
+ // Mixed nesting
+ suppliers.add(
+ supplier("{\"orders\":[{\"id\":1,\"item\":\"book\"},{\"id\":2,\"item\":\"pen\"}]}", "orders[1].item", new BytesRef("pen"))
+ );
+
+ // Missing path returns null with warning
+ suppliers.add(new TestCaseSupplier("missing path", types(DataType.KEYWORD, DataType.KEYWORD), () -> {
+ return new TestCaseSupplier.TestCase(
+ List.of(
+ new TestCaseSupplier.TypedData(new BytesRef("{\"name\":\"Alice\"}"), DataType.KEYWORD, "jsonInput"),
+ new TestCaseSupplier.TypedData(new BytesRef("nonexistent"), DataType.KEYWORD, "path")
+ ),
+ expectedToString(),
+ DataType.KEYWORD,
+ nullValue()
+ ).withWarning("Line 1:1: evaluation of [source] failed, treating result as null. Only first 20 failures recorded.")
+ .withWarning("Line 1:1: java.lang.IllegalArgumentException: path [nonexistent] does not exist");
+ }));
+
+ // JSON null returns ES|QL null (no warning)
+ suppliers.add(supplier("{\"value\":null}", "value", null));
+
+ // Array out of bounds returns null with warning
+ suppliers.add(new TestCaseSupplier("array out of bounds", types(DataType.KEYWORD, DataType.KEYWORD), () -> {
+ return new TestCaseSupplier.TestCase(
+ List.of(
+ new TestCaseSupplier.TypedData(new BytesRef("{\"tags\":[\"a\",\"b\"]}"), DataType.KEYWORD, "jsonInput"),
+ new TestCaseSupplier.TypedData(new BytesRef("tags[5]"), DataType.KEYWORD, "path")
+ ),
+ expectedToString(),
+ DataType.KEYWORD,
+ nullValue()
+ ).withWarning("Line 1:1: evaluation of [source] failed, treating result as null. Only first 20 failures recorded.")
+ .withWarning("Line 1:1: java.lang.IllegalArgumentException: array index out of bounds");
+ }));
+
+ // Traversal through non-object returns null with warning
+ suppliers.add(new TestCaseSupplier("non-object traversal", types(DataType.KEYWORD, DataType.KEYWORD), () -> {
+ return new TestCaseSupplier.TestCase(
+ List.of(
+ new TestCaseSupplier.TypedData(new BytesRef("{\"name\":\"Alice\"}"), DataType.KEYWORD, "jsonInput"),
+ new TestCaseSupplier.TypedData(new BytesRef("name.nested"), DataType.KEYWORD, "path")
+ ),
+ expectedToString(),
+ DataType.KEYWORD,
+ nullValue()
+ ).withWarning("Line 1:1: evaluation of [source] failed, treating result as null. Only first 20 failures recorded.")
+ .withWarning("Line 1:1: java.lang.IllegalArgumentException: path [name.nested] does not exist");
+ }));
+
+ // Extract nested object as JSON string
+ suppliers.add(supplier("{\"user\":{\"name\":\"Alice\",\"age\":30}}", "user", new BytesRef("{\"name\":\"Alice\",\"age\":30}")));
+
+ // Extract array as JSON string
+ suppliers.add(supplier("{\"tags\":[\"a\",\"b\",\"c\"]}", "tags", new BytesRef("[\"a\",\"b\",\"c\"]")));
+
+ // Invalid JSON - warning case
+ suppliers.add(new TestCaseSupplier("invalid json", types(DataType.KEYWORD, DataType.KEYWORD), () -> {
+ return new TestCaseSupplier.TestCase(
+ List.of(
+ new TestCaseSupplier.TypedData(new BytesRef("not valid json"), DataType.KEYWORD, "jsonInput"),
+ new TestCaseSupplier.TypedData(new BytesRef("field"), DataType.KEYWORD, "path")
+ ),
+ expectedToString(),
+ DataType.KEYWORD,
+ nullValue()
+ ).withWarning("Line 1:1: evaluation of [source] failed, treating result as null. Only first 20 failures recorded.")
+ .withWarning("Line 1:1: java.lang.IllegalArgumentException: invalid JSON input");
+ }));
+
+ // SOURCE type support (for _source field)
+ for (DataType pathType : DataType.stringTypes()) {
+ suppliers.add(
+ new TestCaseSupplier(
+ "extract from source " + TestCaseSupplier.nameFromTypes(types(DataType.SOURCE, pathType)),
+ types(DataType.SOURCE, pathType),
+ () -> new TestCaseSupplier.TestCase(
+ List.of(
+ new TestCaseSupplier.TypedData(new BytesRef("{\"name\":\"Alice\"}"), DataType.SOURCE, "jsonInput"),
+ new TestCaseSupplier.TypedData(new BytesRef("name"), pathType, "path")
+ ),
+ expectedToString(),
+ DataType.KEYWORD,
+ equalTo(new BytesRef("Alice"))
+ )
+ )
+ );
+ }
+
+ return parameterSuppliersFromTypedDataWithDefaultChecks(true, suppliers);
+ }
+
+ @Override
+ protected Expression build(Source source, List args) {
+ return new JsonExtract(source, args.get(0), args.get(1));
+ }
+
+ private static TestCaseSupplier supplier(String json, String path, BytesRef expectedValue) {
+ String name = String.format("extract \"%s\" from json", path);
+ return new TestCaseSupplier(name, types(DataType.KEYWORD, DataType.KEYWORD), () -> {
+ return new TestCaseSupplier.TestCase(
+ List.of(
+ new TestCaseSupplier.TypedData(new BytesRef(json), DataType.KEYWORD, "jsonInput"),
+ new TestCaseSupplier.TypedData(new BytesRef(path), DataType.KEYWORD, "path")
+ ),
+ expectedToString(),
+ DataType.KEYWORD,
+ expectedValue == null ? nullValue() : equalTo(expectedValue)
+ );
+ });
+ }
+
+ private static String expectedToString() {
+ return "JsonExtractEvaluator[jsonInput=Attribute[channel=0], path=Attribute[channel=1]]";
+ }
+
+ private static List types(DataType firstType, DataType secondType) {
+ List types = new ArrayList<>();
+ types.add(firstType);
+ types.add(secondType);
+ return types;
+ }
+}
diff --git a/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/60_usage.yml b/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/60_usage.yml
index 18c9034c2597c..b3f32a1955e7d 100644
--- a/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/60_usage.yml
+++ b/x-pack/plugin/src/yamlRestTest/resources/rest-api-spec/test/esql/60_usage.yml
@@ -59,6 +59,7 @@ setup:
- cosine_vector_similarity_function
- inline_stats
- promql_command_v0
+ - fn_json_extract
reason: "Test that should only be executed on snapshot versions"
- do: { xpack.usage: { } }
@@ -361,6 +362,7 @@ setup:
# There's one of these per function but that's a ton of things to check. So we just spot check that a few exist.
- not_exists: esql.functions.delay
+ - not_exists: esql.functions.json_extract
- exists: esql.functions.idelta
- exists: esql.functions.mv_sum
- exists: esql.functions.to_dateperiod