You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by dw...@apache.org on 2025/02/26 13:16:51 UTC
(flink) 03/04: [FLINK-37374][docs] Add documentation for JSON in JSON_ARRAY
This is an automated email from the ASF dual-hosted git repository.
dwysakowicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flink.git
commit 582920a38188296f78a7470d35e22904ef58f7da
Author: Gustavo de Morais <gd...@confluent.io>
AuthorDate: Mon Feb 24 10:25:33 2025 +0100
[FLINK-37374][docs] Add documentation for JSON in JSON_ARRAY
---
docs/data/sql_functions.yml | 27 ++++++++++++++++------
flink-python/pyflink/table/expressions.py | 26 ++++++++++++++++-----
.../org/apache/flink/table/api/Expressions.java | 15 ++++++++----
3 files changed, 50 insertions(+), 18 deletions(-)
diff --git a/docs/data/sql_functions.yml b/docs/data/sql_functions.yml
index 99e5de30d9f..1059ab023e1 100644
--- a/docs/data/sql_functions.yml
+++ b/docs/data/sql_functions.yml
@@ -1066,8 +1066,8 @@ json:
JSON_OBJECT(KEY 'K1' VALUE CAST(NULL AS STRING) NULL ON NULL) -- '{"K1":null}'
JSON_OBJECT(KEY 'K1' VALUE CAST(NULL AS STRING) ABSENT ON NULL) -- '{}'
- -- '{"K1":{"K2":{"value":42}}}'
- JSON_OBJECT('K1' VALUE JSON('{"K2": {"value": 42}}'))
+ -- '{"K1":{"nested_json":{"value":42}}}'
+ JSON_OBJECT('K1' VALUE JSON('{"nested_json": {"value": 42}}'))
-- '{"K1":{"K2":"V"}}'
JSON_OBJECT(
@@ -1083,11 +1083,12 @@ json:
description: |
Expects a raw, pre-formatted JSON string and returns its values as-is without escaping it as a string.
- This function can currently only be used within the `JSON_OBJECT` function. It allows passing
- pre-formatted JSON strings that will be inserted directly into the resulting JSON structure
- rather than being escaped as a string value. This allows storing nested JSON structures in a
- JSON_OBJECT without processing them as strings, which is often useful when ingesting already
- formatted json data. If the value is NULL or empty, the function returns NULL.
+ This function can currently only be used within the `JSON_OBJECT` and `JSON_ARRAY` functions.
+ It allows passing pre-formatted JSON strings that will be inserted directly into the
+ resulting JSON structure rather than being escaped as a string value. This allows storing
+ nested JSON structures in a `JSON_OBJECT` or `JSON_ARRAY` without processing them as strings,
+ which is often useful when ingesting already formatted json data. If the value is NULL or empty,
+ the function returns NULL.
```sql
-- {"K":{"K2":42}}
@@ -1098,6 +1099,15 @@ json:
-- {"K": null}
JSON_OBJECT('K' VALUE JSON(''))
+
+ -- [{"K2":42}]
+ JSON_ARRAY(JSON('{"K2": 42}'))
+
+ -- [{"K2":{"K3":42}}]
+ JSON_ARRAY(JSON('{"K2":{"K3":42}}'))
+
+ -- [null]
+ JSON_ARRAY(JSON('') NULL ON NULL)
-- Invalid - JSON function can only be used within JSON_OBJECT
JSON('{"value": 42}')
@@ -1130,6 +1140,9 @@ json:
-- '[[1]]'
JSON_ARRAY(JSON_ARRAY(1))
+
+ -- [{"nested_json":{"value":42}}]
+ JSON_ARRAY(JSON('{"nested_json": {"value": 42}}'))
```
valueconstruction:
diff --git a/flink-python/pyflink/table/expressions.py b/flink-python/pyflink/table/expressions.py
index 3c531289248..2f0c7675e6d 100644
--- a/flink-python/pyflink/table/expressions.py
+++ b/flink-python/pyflink/table/expressions.py
@@ -775,12 +775,12 @@ def json(value) -> Expression:
Expects a raw, pre-formatted JSON string and returns its values as-is without escaping
it as a string.
- This function can currently only be used within the `JSON_OBJECT` function. It allows passing
- pre-formatted JSON strings that will be inserted directly into the resulting JSON structure
- rather than being escaped as a string value. This allows storing nested JSON structures in a
- JSON_OBJECT without processing them as strings, which is often useful when ingesting already
- formatted json data. If the value is NULL or empty, the function
- returns NULL.
+ This function can currently only be used within the `JSON_OBJECT` and `JSON_ARRAY` functions.
+ It allows passing pre-formatted JSON strings that will be inserted directly into the
+ resulting JSON structure rather than being escaped as a string value. This allows storing
+ nested JSON structures in a `JSON_OBJECT` or `JSON_ARRAY` without processing them as strings,
+ which is often useful when ingesting already formatted json data. If the value is NULL or
+ empty, the function returns NULL.
Examples:
::
@@ -791,6 +791,12 @@ def json(value) -> Expression:
>>> # {"K": null}
>>> json_object(JsonOnNull.NULL, "K", json(''))
+ >>> # [{"nested":{"value":42}}]
+ >>> json_array(JsonOnNull.NULL, json('{"nested":{"value": 42}}'))
+
+ >>> # [null]
+ >>> json_array(JsonOnNull.NULL, json(''))
+
>>> # Invalid - JSON function can only be used within JSON_OBJECT
>>> json('{"value": 42}')
"""
@@ -842,9 +848,13 @@ def json_object(on_null: JsonOnNull = JsonOnNull.NULL, *args) -> Expression:
>>> json_object(JsonOnNull.NULL, "K1", null_of(DataTypes.STRING())) # '{"K1":null}'
>>> json_object(JsonOnNull.ABSENT, "K1", null_of(DataTypes.STRING())) # '{}'
+ >>> # '{"K1":{"K2":"V"}}'
+ >>> json_object(JsonOnNull.NULL, "K1", json('{"K2":"V"}'))
+
>>> # '{"K1":{"K2":"V"}}'
>>> json_object(JsonOnNull.NULL, "K1", json_object(JsonOnNull.NULL, "K2", "V"))
+ .. seealso:: :func:`~pyflink.table.expressions.json`
.. seealso:: :func:`~pyflink.table.expressions.json_array`
"""
return _varargs_op("jsonObject", *(on_null._to_j_json_on_null(), *args))
@@ -898,6 +908,10 @@ def json_array(on_null: JsonOnNull = JsonOnNull.ABSENT, *args) -> Expression:
>>> json_array(JsonOnNull.NULL, json_array(JsonOnNull.NULL, 1)) # '[[1]]'
+ # '[{"nested_json":{"value":42}}]'
+ >>> json_array(JsonOnNull.NULL, json('{"nested_json": {"value": 42}}'))
+
+ .. seealso:: :func:`~pyflink.table.expressions.json`
.. seealso:: :func:`~pyflink.table.expressions.json_object`
"""
return _varargs_op("jsonArray", *(on_null._to_j_json_on_null(), *args))
diff --git a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Expressions.java b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Expressions.java
index c6febab9d13..86b80c27f46 100644
--- a/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Expressions.java
+++ b/flink-table/flink-table-api-java/src/main/java/org/apache/flink/table/api/Expressions.java
@@ -883,11 +883,12 @@ public final class Expressions {
* a string.
*
* <p>This function can currently only be used within the {@link #jsonObject(JsonOnNull,
- * Object...)} function. It allows passing pre-formatted JSON strings that will be inserted
- * directly into the resulting JSON structure rather than being escaped as a string value. This
- * allows storing nested JSON structures in a JSON_OBJECT without processing them as strings,
- * which is often useful when ingesting already formatted json data. If the value is null or
- * empty, the function returns {@code null}.
+ * Object...)} and {@link #jsonArray(JsonOnNull, Object...)} function. It allows passing
+ * pre-formatted JSON strings that will be inserted directly into the resulting JSON structure
+ * rather than being escaped as a string value. This allows storing nested JSON structures in a
+ * `JSON_OBJECT` or `JSON_ARRAY` without processing them as strings, which is often useful when
+ * ingesting already formatted json data. If the value is null or empty, the function returns
+ * {@code null}.
*
* <p>Examples:
*
@@ -1003,8 +1004,12 @@ public final class Expressions {
*
* // "[[1]]"
* jsonArray(JsonOnNull.NULL, jsonArray(JsonOnNull.NULL, 1))
+ *
+ * // "[{\"nested_json\":{\"value\":42}}]"
+ * jsonArray(JsonOnNull.NULL, json("{\"nested_json\": {\"value\": 42}}"))
* }</pre>
*
+ * @see #json(Object)
* @see #jsonObject(JsonOnNull, Object...)
*/
public static ApiExpression jsonArray(JsonOnNull onNull, Object... values) {