feat(spanner): add metadata to RowIterator

Adds ResultSetMetaData to the RowIterator struct. The metadata
are available after the first call to RowIterator.Next() as long
as that call did not return any other error than iterator.Done.

Fixes #1805

spanner/client_test.go

@@ -1880,6 +1880,51 @@ func TestClient_QueryWithCallOptions(t *testing.T) {
 	}
 }
 
+func TestClient_ShouldReceiveMetadataForEmptyResultSet(t *testing.T) {
+	t.Parallel()
+
+	server, client, teardown := setupMockedTestServer(t)
+	// This creates an empty result set.
+	res := server.CreateSingleRowSingersResult(SelectSingerIDAlbumIDAlbumTitleFromAlbumsRowCount)
+	sql := "SELECT SingerId, AlbumId, AlbumTitle FROM Albums WHERE 1=2"
+	server.TestSpanner.PutStatementResult(sql, res)
+	defer teardown()
+	ctx := context.Background()
+	iter := client.Single().Query(ctx, NewStatement(sql))
+	defer iter.Stop()
+	row, err := iter.Next()
+	if err != iterator.Done {
+		t.Errorf("Query result mismatch:\nGot: %v\nWant: <no rows>", row)
+	}
+	metadata := iter.Metadata
+	if metadata == nil {
+		t.Fatalf("Missing ResultSet Metadata")
+	}
+	if metadata.RowType == nil {
+		t.Fatalf("Missing ResultSet RowType")
+	}
+	if metadata.RowType.Fields == nil {
+		t.Fatalf("Missing ResultSet Fields")
+	}
+	if g, w := len(metadata.RowType.Fields), 3; g != w {
+		t.Fatalf("Field count mismatch\nGot: %v\nWant: %v", g, w)
+	}
+	wantFieldNames := []string{"SingerId", "AlbumId", "AlbumTitle"}
+	for i, w := range wantFieldNames {
+		g := metadata.RowType.Fields[i].Name
+		if g != w {
+			t.Fatalf("Field[%v] name mismatch\nGot: %v\nWant: %v", i, g, w)
+		}
+	}
+	wantFieldTypes := []sppb.TypeCode{sppb.TypeCode_INT64, sppb.TypeCode_INT64, sppb.TypeCode_STRING}
+	for i, w := range wantFieldTypes {
+		g := metadata.RowType.Fields[i].Type.Code
+		if g != w {
+			t.Fatalf("Field[%v] type mismatch\nGot: %v\nWant: %v", i, g, w)
+		}
+	}
+}
+
 func TestClient_EncodeCustomFieldType(t *testing.T) {
 	t.Parallel()
 

spanner/integration_test.go

@@ -3156,6 +3156,11 @@ func readAllTestTable(iter *RowIterator) ([]testTableRow, error) {
 	for {
 		row, err := iter.Next()
 		if err == iterator.Done {
+			if iter.Metadata == nil {
+				// All queries should always return metadata, regardless whether
+				// they return any rows or not.
+				return nil, errors.New("missing metadata from query")
+			}
 			return vals, nil
 		}
 		if err != nil {

spanner/internal/testutil/inmem_spanner_server.go

@@ -148,6 +148,10 @@ func (s *StatementResult) ToPartialResultSets(resumeToken []byte) (result []*spa
 				break
 			}
 		}
+	} else {
+		result = append(result, &spannerpb.PartialResultSet{
+			Metadata: s.ResultSet.Metadata,
+		})
 	}
 	return result, nil
 }

spanner/read.go

@@ -102,6 +102,11 @@ type RowIterator struct {
 	// iterator.Done.
 	RowCount int64
 
+	// The metadata of the results of the query. The metadata are available
+	// after the first call to RowIterator.Next(), unless the first call to
+	// RowIterator.Next() returned an error that is not equal to iterator.Done.
+	Metadata *sppb.ResultSetMetadata
+
 	streamd      *resumableStreamDecoder
 	rowd         *partialResultSetDecoder
 	setTimestamp func(time.Time)
@@ -133,7 +138,11 @@ func (r *RowIterator) Next() (*Row, error) {
 				r.RowCount = rc
 			}
 		}
-		r.rows, r.err = r.rowd.add(prs)
+		var metadata *sppb.ResultSetMetadata
+		r.rows, metadata, r.err = r.rowd.add(prs)
+		if metadata != nil {
+			r.Metadata = metadata
+		}
 		if r.err != nil {
 			return nil, r.err
 		}
@@ -648,7 +657,7 @@ func errChunkedEmptyRow() error {
 
 // add tries to merge a new PartialResultSet into buffered Row. It returns any
 // rows that have been completed as a result.
-func (p *partialResultSetDecoder) add(r *sppb.PartialResultSet) ([]*Row, error) {
+func (p *partialResultSetDecoder) add(r *sppb.PartialResultSet) ([]*Row, *sppb.ResultSetMetadata, error) {
 	var rows []*Row
 	if r.Metadata != nil {
 		// Metadata should only be returned in the first result.
@@ -663,20 +672,20 @@ func (p *partialResultSetDecoder) add(r *sppb.PartialResultSet) ([]*Row, error)
 		}
 	}
 	if len(r.Values) == 0 {
-		return nil, nil
+		return nil, r.Metadata, nil
 	}
 	if p.chunked {
 		p.chunked = false
 		// Try to merge first value in r.Values into uncompleted row.
 		last := len(p.row.vals) - 1
 		if last < 0 { // confidence check
-			return nil, errChunkedEmptyRow()
+			return nil, nil, errChunkedEmptyRow()
 		}
 		var err error
 		// If p is chunked, then we should always try to merge p.last with
 		// r.first.
 		if p.row.vals[last], err = p.merge(p.row.vals[last], r.Values[0]); err != nil {
-			return nil, err
+			return nil, r.Metadata, err
 		}
 		r.Values = r.Values[1:]
 		// Merge is done, try to yield a complete Row.
@@ -698,7 +707,7 @@ func (p *partialResultSetDecoder) add(r *sppb.PartialResultSet) ([]*Row, error)
 		// also chunked.
 		p.chunked = true
 	}
-	return rows, nil
+	return rows, r.Metadata, nil
 }
 
 // isMergeable returns if a protobuf Value can be potentially merged with other

spanner/read_test.go

@@ -584,7 +584,7 @@ nextTest:
 		var rows []*Row
 		p := &partialResultSetDecoder{}
 		for j, v := range test.input {
-			rs, err := p.add(v)
+			rs, _, err := p.add(v)
 			if err != nil {
 				t.Errorf("test %d.%d: partialResultSetDecoder.add(%v) = %v; want nil", i, j, v, err)
 				continue nextTest