docs(search): state that omitted match maps decode nil, and test it

The runtime omits primary_key, data and metadata from a match that has
none, so json.Unmarshal leaves those maps nil. The doc comments said
"Empty", which reads as an allocated empty map and hides that assigning
into one panics.

Say nil explicitly and assert it in the test: len == 0 also passes for an
allocated empty map, so it did not pin down what a caller receives.

Author: claudespice

search.go

@@ -39,6 +39,11 @@ type SearchRequest struct {
 }
 
 // SearchMatch is a single document matched by Search.
+//
+// The runtime omits primary_key, data and metadata from a match that has
+// none, so PrimaryKey, Data and Metadata are nil rather than empty in that
+// case. Reading from a nil map is safe and reports no entries; assigning into
+// one panics, so allocate before writing.
 type SearchMatch struct {
 	// Dataset is the dataset the match was found in.
 	Dataset string `json:"dataset"`
@@ -51,14 +56,16 @@ type SearchMatch struct {
 	// to a single match.
 	Matches map[string][]any `json:"matches"`
 
-	// PrimaryKey identifies the matched row. Empty when the dataset declares
-	// no primary key.
+	// PrimaryKey identifies the matched row. Nil when the dataset declares no
+	// primary key.
 	PrimaryKey map[string]any `json:"primary_key"`
 
-	// Data holds any AdditionalColumns that were requested.
+	// Data holds any AdditionalColumns that were requested. Nil when none were
+	// requested.
 	Data map[string]any `json:"data"`
 
-	// Metadata holds extra per-match metadata the runtime attached.
+	// Metadata holds extra per-match metadata the runtime attached. Nil when
+	// it attached none.
 	Metadata map[string]any `json:"metadata"`
 }
 

search_test.go

@@ -173,11 +173,23 @@ func TestSearchResponseDecoding(t *testing.T) {
 		t.Errorf("Metadata[chunk] = %v, want 2", first.Metadata["chunk"])
 	}
 
-	// The runtime omits data, primary_key, and metadata when they are empty.
+	// The runtime omits data, primary_key, and metadata from a match that has
+	// none, and an absent JSON key leaves the map nil. Assert nil rather than
+	// len == 0, which would also pass for an allocated empty map and so would
+	// not pin down what a caller actually receives.
 	second := resp.Results[1]
-	if len(second.PrimaryKey) != 0 || len(second.Data) != 0 || len(second.Metadata) != 0 {
-		t.Errorf("omitted fields should decode empty, got PrimaryKey=%v Data=%v Metadata=%v",
-			second.PrimaryKey, second.Data, second.Metadata)
+	if second.PrimaryKey != nil {
+		t.Errorf("omitted primary_key should decode nil, got %v", second.PrimaryKey)
+	}
+	if second.Data != nil {
+		t.Errorf("omitted data should decode nil, got %v", second.Data)
+	}
+	if second.Metadata != nil {
+		t.Errorf("omitted metadata should decode nil, got %v", second.Metadata)
+	}
+	// A nil map is still safe to read, which is what the doc comment promises.
+	if got := second.PrimaryKey["id"]; got != nil {
+		t.Errorf("reading a nil PrimaryKey should yield nil, got %v", got)
 	}
 }