From 9de4fa5cc1a8c4f620ec6c9129ebedf9aeb25e01 Mon Sep 17 00:00:00 2001 From: YANGDB Date: Wed, 4 Dec 2024 14:14:20 -0800 Subject: [PATCH] add the following JSON functions - json_delete - json_append - json_extend Signed-off-by: YANGDB --- docs/ppl-lang/functions/ppl-json.md | 117 ++++++++++++++++++ .../src/main/antlr4/OpenSearchPPLLexer.g4 | 6 +- .../src/main/antlr4/OpenSearchPPLParser.g4 | 3 + 3 files changed, 123 insertions(+), 3 deletions(-) diff --git a/docs/ppl-lang/functions/ppl-json.md b/docs/ppl-lang/functions/ppl-json.md index 2c0c0ca67..27cc33d30 100644 --- a/docs/ppl-lang/functions/ppl-json.md +++ b/docs/ppl-lang/functions/ppl-json.md @@ -203,6 +203,123 @@ Example: +----------------+ +### `JSON_DELETE` + +**Description** + +`json_delete(json, [keys list])` Deletes json elements from a json object based on json specific keys. Return the updated object after keys deletion . + +**Argument type:** JSON, List + +**Return type:** JSON + +A JSON object format. + +Example: + + os> source=people | eval deleted = json_delete({"a":"valueA", "b":"valueB"}, ["a"]) + fetched rows / total rows = 1/1 + +----------------------------------+ + | deleted | + +----------------------------------+ + | {"a": "valueA" } | + +----------------------------------+ + + os> source=people | eval eval deleted = json_delete({"a":[{"b":1},{"b":2},{"c":3}]}, ["a.b"]) + fetched rows / total rows = 1/1 + +-----------------------------------------------------------+ + | deleted | + +-----------------------------------------------------------+ + | {"a":[{"c":3}] } | + +-----------------------------------------------------------+ + + os> source=people | eval `no_action` = json_delete({"a":[{"b":1},{"b":2},{"c":3}]}, ["b.b"]) + fetched rows / total rows = 1/1 + +-----------------------------------+ + | no_action | + +-----------------------------------+ + | {"a":[{"b":1},{"b":2},{"c":3}]} | + +-----------------------------------+ + +### `JSON_APPEND` + +**Description** + +`json_append(json, [path_value list])` appends values to end of an array within the json elements. Return the updated json object after appending . + +**Argument type:** JSON, List<[(STRING, STRING>)]> + +**Return type:** JSON + +A JSON object format. + +**Note** +Append adds the value to the end of the existing array with the following cases: + - path is an object value - append is ignored and the value is returned + - path is an existing array not empty - the value are added to the array's tail + - path is an existing array is empty - create a new array with the given value + +Example: + + os> source=people | eval append = json_append(`{"a":["valueA", "valueB"]}`, ["a","valueC"]) + fetched rows / total rows = 1/1 + +-------------------------------------------------+ + | append | + +-------------------------------------------------+ + | {"a":["valueA", "valueB", "valueC"]} | + +-------------------------------------------------+ + + os> source=people | eval append = json_append(`{"a":["valueA", "valueB"]}`, {"a":["valueC"]}) + fetched rows / total rows = 1/1 + +-----------------------------------------------+ + | append | + +-----------------------------------------------+ + | {"a":["valueA", "valueB", ["valueC"]]} | + +-----------------------------------------------+ + + os> source=people | eval append = json_append(`{"root":{ "a":["valueA", "valueB"]}}`, {"root.a":"valueC"}) + fetched rows / total rows = 1/1 + +-----------------------------------------------+ + | append | + +-----------------------------------------------+ + |{"root": {"a":["valueA", "valueB", "valueC"]}} | + +-----------------------------------------------+ + + + +### `JSON_EXTEND` + +**Description** + +`json_extend(json, [path_value_pairs list])` extend appends multiple (array) values to an existing array json elements. Return the updated object after extending. + +**Argument type:** JSON, List<[(STRING, List)]> + +**Return type:** JSON + +A JSON object format. + +**Note** +Extend arrays as individual values separates the `json_extend` functionality from the `json_append` - which is a similar function that appends the `` as a single element. + +Example: + + os> source=people | eval extend = json_extend(`{"a":["valueA", "valueB"]}`, ["valueC","valueD"]) + fetched rows / total rows = 1/1 + +-------------------------------------------------+ + | extend | + +-------------------------------------------------+ + | {"a":["valueA", "valueB", "valueC", "valueD"]} | + +-------------------------------------------------+ + + os> source=people | eval extend = json_extend(`{"a":["valueA", "valueB"]}`, {"b":["valueC","valueD"]}) + fetched rows / total rows = 1/1 + +-------------------------------------------------------------+ + | extend | + +-------------------------------------------------------------+ + | {"a":["valueA", "valueB", {"b":"valueC"}, {"b":"valueD"}]} | + +-------------------------------------------------------------+ + ### `JSON_KEYS` **Description** diff --git a/ppl-spark-integration/src/main/antlr4/OpenSearchPPLLexer.g4 b/ppl-spark-integration/src/main/antlr4/OpenSearchPPLLexer.g4 index d15f5c8e3..a8efffe71 100644 --- a/ppl-spark-integration/src/main/antlr4/OpenSearchPPLLexer.g4 +++ b/ppl-spark-integration/src/main/antlr4/OpenSearchPPLLexer.g4 @@ -385,11 +385,11 @@ JSON_ARRAY: 'JSON_ARRAY'; JSON_ARRAY_LENGTH: 'JSON_ARRAY_LENGTH'; TO_JSON_STRING: 'TO_JSON_STRING'; JSON_EXTRACT: 'JSON_EXTRACT'; +JSON_DELETE : 'JSON_DELETE'; +JSON_EXTEND : 'JSON_EXTEND'; JSON_KEYS: 'JSON_KEYS'; JSON_VALID: 'JSON_VALID'; -//JSON_APPEND: 'JSON_APPEND'; -//JSON_DELETE: 'JSON_DELETE'; -//JSON_EXTEND: 'JSON_EXTEND'; +JSON_APPEND: 'JSON_APPEND'; //JSON_SET: 'JSON_SET'; //JSON_ARRAY_ALL_MATCH: 'JSON_ARRAY_ALL_MATCH'; //JSON_ARRAY_ANY_MATCH: 'JSON_ARRAY_ANY_MATCH'; diff --git a/ppl-spark-integration/src/main/antlr4/OpenSearchPPLParser.g4 b/ppl-spark-integration/src/main/antlr4/OpenSearchPPLParser.g4 index eb6cd1a35..9a0926adf 100644 --- a/ppl-spark-integration/src/main/antlr4/OpenSearchPPLParser.g4 +++ b/ppl-spark-integration/src/main/antlr4/OpenSearchPPLParser.g4 @@ -880,6 +880,9 @@ jsonFunctionName | JSON_ARRAY_LENGTH | TO_JSON_STRING | JSON_EXTRACT + | JSON_DELETE + | JSON_EXTEND + | JSON_APPEND | JSON_KEYS | JSON_VALID // | JSON_APPEND