Add comments

client/json.go

@@ -22,6 +22,20 @@ import (
 
 // JSONPathPart represents a part of a JSON path.
 // Json path can be either a property of an object or an index of an element in an array.
+// For example, the paths to both values 1 are very similar:
+//
+//	{
+//	  "0": {
+//		"val": 1
+//	  }
+//	}
+//	[
+//	  {
+//	    "val": 1
+//	  }
+//	]
+//
+// It can be described as "0.val" but they are different.
 type JSONPathPart interface {
 	// Property returns the property name if the part is a property, and a boolean indicating if the part is a property.
 	Property() (string, bool)

internal/db/fetcher/indexer_iterators.go

@@ -593,6 +593,10 @@ func (f *IndexFetcher) determineFieldFilterConditions() ([]fieldFilterCond, erro
 	return result, nil
 }
 
+// determineJSONFilterCondition determines the condition and its corresponding operation for a
+// JSON filter condition.
+// It mutates the given condition to make it match the filter value and JSON path so that
+// it can be used to fetch the indexed data.
 func determineJSONFilterCondition(cond *fieldFilterCond, filterVal any, jsonPath client.JSONPath) error {
 	var jsonVal client.JSON
 	var err error
@@ -605,7 +609,7 @@ func determineJSONFilterCondition(cond *fieldFilterCond, filterVal any, jsonPath
 			if err == nil {
 				cond.val = client.NewNormalJSON(jsonVal)
 			}
-			// the sub condition is supposed to have only 1 record
+			// the array sub condition (_any, _all or _none) is supposed to have only 1 record
 			break
 		}
 	} else if cond.op == opIn {

internal/db/index.go

@@ -130,8 +130,12 @@ func (g *JSONFieldGenerator) Generate(value client.NormalValue, f func(client.No
 		}
 		return f(val)
 	},
+		// we don't want to traverse intermediate nodes
 		client.TraverseJSONOnlyLeaves(),
+		// we want to include array elements' indexes in json path
 		client.TraverseJSONWithArrayIndexInPath(),
+		// we want to traverse array elements, but not recurse into them
+		// this effectively means that we traverse only leave array elements (string, float, bool, null)
 		client.TraverseJSONVisitArrayElements(false),
 	)
 }