From 598f3e071fe5382b23628ed83cbf80894df2609e Mon Sep 17 00:00:00 2001
From: Ayesha <ayesha.firdaus@tigergraph.com>
Date: Thu, 16 Oct 2025 03:30:28 +0530
Subject: [PATCH] DOC-2200 supporting null val

---
 .../pages/keywords-and-reserved-words.adoc    |  1 +
 .../pages/attribute-data-types.adoc           | 15 +++++
 .../pages/creating-a-loading-job.adoc         | 66 +++++++++++++++++++
 .../pages/modifying-a-graph-schema.adoc       | 36 +++++++++-
 .../pages/data-modification-statements.adoc   | 17 +++++
 5 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/modules/appendix/pages/keywords-and-reserved-words.adoc b/modules/appendix/pages/keywords-and-reserved-words.adoc
index c674975d..44a51030 100644
--- a/modules/appendix/pages/keywords-and-reserved-words.adoc
+++ b/modules/appendix/pages/keywords-and-reserved-words.adoc
@@ -136,6 +136,7 @@ The compiler will reject the use of a reserved word as well as any word beginnin
 * NOT
 * NOW
 * NULL
+* NULLABLE
 * OFFSET
 * ON
 * OPENCYPHER
diff --git a/modules/ddl-and-loading/pages/attribute-data-types.adoc b/modules/ddl-and-loading/pages/attribute-data-types.adoc
index 9a5856a5..fa270861 100644
--- a/modules/ddl-and-loading/pages/attribute-data-types.adoc
+++ b/modules/ddl-and-loading/pages/attribute-data-types.adoc
@@ -120,6 +120,10 @@ Existing schemas that are using `STRING COMPRESS` can continue to function norma
 If you need reference for `STRING COMPRESS`, please refer to GSQL Language Reference version 3.5 or older.
 ====
 
+[NOTE]
+====
+Primitive data types used as attributes of a vertex or edge, can be set to `NULL`.
+====
 Additionally, GSQL also supports the following complex data types:
 
 == Collection types
@@ -143,6 +147,17 @@ Due to multithreaded GSQL loading, the initial order of elements loaded into a l
 ** Supported value types: `INT`, `DOUBLE`, `STRING`, `DATETIME`, and `UDT`.
 ** To declare a map type, use `<>` to enclose the types, with a comma to separate the key and value types, e.g., `MAP<INT, DOUBLE>`.
 
+[NOTE]
+====
+* `LIST`, `SET`, `MAP` can be assigned `NULL` as an attribute.
+* For `LIST` or `SET`:
+** `NULL` is different from [NULL, NULL] or {NULL}.
+** Elements inside `LIST` or `SET` cannot be `NULL`.
+* For `MAP`:
+** Keys and Values cannot be `NULL`.
+
+====
+
 == User-defined tuples
 
 A *User-Defined Tuple (UDT)*  represents an ordered structure of several fields of the same or different types.
diff --git a/modules/ddl-and-loading/pages/creating-a-loading-job.adoc b/modules/ddl-and-loading/pages/creating-a-loading-job.adoc
index df94cfcd..991fc824 100644
--- a/modules/ddl-and-loading/pages/creating-a-loading-job.adoc
+++ b/modules/ddl-and-loading/pages/creating-a-loading-job.adoc
@@ -108,6 +108,72 @@ RUN LOADING JOB job1 USING file1="m1:/data/v1_1.csv", file2="m2:/data/e2.csv" <2
 <1> File path specified at compile time.
 <2> Run-time specification will override path specified at compile time.
 
+=== Loading NULL Values
+`NULL` values can be loaded to vertex/edge attributes using a loading job either by parsing from source file or during creation of loading job.
+
+==== Loading NULL from source file
+If an attribute is defined as *nullable* in the schema, any of the following in a CSV or JSON file are treated as `NULL`:
+
+* The value `NULL` or `null`
+* A missing value (empty field)
+
+.Example: CSV file containing NULL values
+[source,csv]
+----
+id,att
+1,null     // valid null and will be parsed to storage
+2,NULL     // valid null and will be parsed to storage
+3,         // missing value and will be parsed as null to storage
+4,Null     // invalid attribute
+----
+
+.Example: JSON file containing NULL values
+[source,json]
+----
+{"id":1,"att":null}         // valid null and will be parsed to storage
+{"id":2,"att":NULL}         // valid null and will be parsed to storage
+{"id":3,"att":Null}         // invalid like Null except for string
+{"id":4,"att":}             // invalid JSON
+----
+
+Sample Output
+[source,json]
+----
+"results": [
+  { "1,null": null },
+  { "2,NULL": null },
+  { "3,": null },
+  { "4,Null": "Null" }
+]
+----
+
+==== Loading NULL during creation of loading job
+
+`NULL` can be stored in the following situations:
+
+* When the attribute is nullable and the vertex or edge does not exist:
+** The default value for that attribute in the schema is `NULL`, or
+** No default value is defined in the schema.
+* If the attribute is nullable, NULL will be stored for this attribute for all vertices/edges loaded in this job.
+* If the attribute is not nullable, the GSQL shell shows a *semantic error*.
+
+For example:
+[source,gsql]
+----
+CREATE LOADING JOB load_nullable FOR GRAPH g {
+  DEFINE FILENAME f;
+
+  // Implicit NULL using underscore
+  LOAD f TO VERTEX v0 VALUES($0, _);
+  LOAD f TO EDGE e0 VALUES ($0, $1, _);
+
+  // Explicit NULL using NULL keyword
+  LOAD f TO VERTEX v1 VALUES ($0, NULL);
+  LOAD f TO EDGE e1 VALUES ($0, $1, NULL);
+}
+----
+
+
 == `DROP JOB` statement
 
 To drop (remove) a job, run `DROP JOB job_name`. The job will be removed from GSQL.
diff --git a/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc b/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc
index 7b6ce40c..13e40dae 100644
--- a/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc
+++ b/modules/ddl-and-loading/pages/modifying-a-graph-schema.adoc
@@ -167,7 +167,7 @@ ADD VERTEX::
 --
 ----
 ADD VERTEX Vertex_Type_Name ( PRIMARY_ID id_name id_type
-    [, attribute_name type [DEFAULT default_value] ]* )
+    [, attribute_name type  [NULLABLE][DEFAULT default_value] ]* )
     [WITH [STATS="none"|"outdegree_by_edgetype"][primary_id_as_attribute="true"]]
 ----
 --
@@ -179,7 +179,7 @@ ADD UNDIRECTED EDGE Edge_Type_Name (
     FROM Vertex_Type_Name "," TO Vertex_Type_Name
     [ "|" FROM Vertex_Type_Name "," TO Vertex_Type_Name]*
     [ "," DISCRIMINATOR "(" attribute_name type ["," attribute_name type]* ")" ]
-    [ "," attribute_name type [DEFAULT default_value]]*
+    [ "," attribute_name type  [NULLABLE][DEFAULT default_value]]*
 )
 ----
 --
@@ -192,7 +192,39 @@ For example, the following statement in a schema change job adds a directed edge
 ADD DIRECTED EDGE Study_At (From Person, To University,
     DISCRIMINATOR(class_year INT, class_month INT));
 ----
+Starting in 4.3, vertex/edge attributes can be defined as `NULLABLE` to accept `NULL` values.
 
+For example:
+[tabs]
+====
+ADD VERTEX::
++
+--
+----
+ADD VERTEX Student (
+PRIMARY_ID id INT,
+name STRING NULLABLE,
+age INT NULLABLE
+);
+----
+--
+ADD EDGE::
++
+--
+----
+ADD DIRECTED EDGE Enrolled_In (
+FROM Student,
+TO Course,
+grade STRING NULLABLE
+);
+----
+--
+====
+
+[NOTE]
+====
+ Attributes used for `PRIMARY_KEY` or `COMPOSITE_KEY` or `DISCRIMINATOR` cannot be declared `NULLABLE`.
+====
 
 == `ALTER VERTEX | EDGE`
 
diff --git a/modules/querying/pages/data-modification-statements.adoc b/modules/querying/pages/data-modification-statements.adoc
index bfaca6ca..f5a11ad7 100644
--- a/modules/querying/pages/data-modification-statements.adoc
+++ b/modules/querying/pages/data-modification-statements.adoc
@@ -340,6 +340,23 @@ VALUES (value_for_from_vertex, value_for_to_vertex, <1>
 For each attribute value, provide either an expression _expr_ or `_`, which means the default value for that attribute type.
 The optional _name_ which follows the first two (id) values is to specify the source vertex type and target vertex type, if the edge type had been defined with wildcard vertex types.
 
++
+.NULL Value Ingestion
++
+The `INSERT INTO` statement supports inserting `NULL` values for attributes defined as `NULLABLE` in the schema.
+*  `NULL` or `null` can be used in the `VALUES` clause to insert a NULL value.
+
+.Example
+[source,gsql]
+----
+CREATE VERTEX Student (
+  PRIMARY_ID id INT,
+  name STRING NULLABLE,
+  age INT NULLABLE
+);
+INSERT INTO Student VALUES (1001, "Alice", NULL);
+----
+
 === Query-Body INSERT
 
 The following query illustrates query-body level `INSERT` statements: insert new `Company` vertices and `Works_For` edges into the `Works_Net` graph.