From 5b3716dce9e684a0080e256aed3d95907a71d1c3 Mon Sep 17 00:00:00 2001
From: YANGDB <yang.db.dev@gmail.com>
Date: Fri, 4 Oct 2024 13:55:27 -0700
Subject: [PATCH] add planned commands folder

Signed-off-by: YANGDB <yang.db.dev@gmail.com>
---
 docs/ppl-lang/PPL-Example-Commands.md         | 13 +++++
 docs/ppl-lang/README.md                       |  4 ++
 .../ppl-lang/planning/ppl-fillnull-command.md | 50 +++++++++++++++++++
 3 files changed, 67 insertions(+)
 create mode 100644 docs/ppl-lang/planning/ppl-fillnull-command.md

diff --git a/docs/ppl-lang/PPL-Example-Commands.md b/docs/ppl-lang/PPL-Example-Commands.md
index 76e4267fb..f68865f75 100644
--- a/docs/ppl-lang/PPL-Example-Commands.md
+++ b/docs/ppl-lang/PPL-Example-Commands.md
@@ -353,3 +353,16 @@ source = supplier
 
 > ppl-correlation-command is an experimental command - it may be removed in future versions
 
+---
+### Planned Commands:
+
+#### **fillnull**
+
+```sql
+   -  `source=accounts | fillnull fields status_code=101`
+   -  `source=accounts | fillnull fields request_path='/not_found', timestamp='*'`
+    - `source=accounts | fillnull using field1=101`
+    - `source=accounts | fillnull using field1=concat(field2, field3), field4=2*pi()*field5`
+    - `source=accounts | fillnull using field1=concat(field2, field3), field4=2*pi()*field5, field6 = 'N/A'`
+```
+[See additional command details](planning/ppl-fillnull-command.md)
diff --git a/docs/ppl-lang/README.md b/docs/ppl-lang/README.md
index efbeafe91..16ff636f7 100644
--- a/docs/ppl-lang/README.md
+++ b/docs/ppl-lang/README.md
@@ -89,6 +89,10 @@ For additional examples see the next [documentation](PPL-Example-Commands.md).
 See samples of [PPL queries](PPL-Example-Commands.md) 
 
 ---
+### Planned PPL Commands
 
+ - [`FillNull`](planning/ppl-fillnull-command.md)
+
+---
 ### PPL Project Roadmap
 [PPL Github Project Roadmap](https://github.com/orgs/opensearch-project/projects/214)
\ No newline at end of file
diff --git a/docs/ppl-lang/planning/ppl-fillnull-command.md b/docs/ppl-lang/planning/ppl-fillnull-command.md
new file mode 100644
index 000000000..a9897fb4d
--- /dev/null
+++ b/docs/ppl-lang/planning/ppl-fillnull-command.md
@@ -0,0 +1,50 @@
+## fillnull syntax proposal
+
+1. **Proposed syntax changes with `null` replacement with the same values in various fields**
+    - `... | fillnull with 0 in field1`
+    - `... | fillnull with 'N/A' in field1, field2, field3`
+    - `... | fillnull with 2*pi() + field1 in field2`
+    - `... | fillnull with concat(field1, field2) in field3, field4`
+    - `... | fillnull with 'N/A'`
+        - incorrect syntax
+    - `... | fillnull with 'N/A' in`
+        - validation error related to missing columns
+
+2. **Proposed syntax changes with `null` replacement with the various values in various fields**
+* currently implemented, not conform to previous syntax proposal (`fields` addition)
+    - `... | fillnull fields status_code=101`
+    -  `... | fillnull fields request_path='/not_found', timestamp='*'`
+* New syntax proposal
+    - `... | fillnull using field1=101`
+    - `... | fillnull using field1=concat(field2, field3), field4=2*pi()*field5`
+    - `... | fillnull using field1=concat(field2, field3), field4=2*pi()*field5, field6 = 'N/A'`
+    - `... | fillnull using`
+        -  validation error related to missing columns
+
+### New syntax definition in ANTLR
+
+```ANTLR
+  
+fillnullCommand
+   : FILLNULL (fillNullWithTheSameValue
+   | fillNullWithFieldVariousValues)
+   ;
+
+ fillNullWithTheSameValue
+ : WITH nullReplacement IN nullableField (COMMA nullableField)*
+ ;
+
+ fillNullWithFieldVariousValues
+ : USING nullableField EQUAL nullReplacement (COMMA nullableField EQUAL nullReplacement)*
+ ;
+
+
+   nullableField
+   : fieldExpression
+   ;
+
+   nullReplacement
+   : expression
+   ;
+
+```
\ No newline at end of file