From 7c4390affd845d0b99b2886fc99a309897e11610 Mon Sep 17 00:00:00 2001 From: Alvaro Viebrantz Date: Tue, 15 Aug 2023 11:27:04 -0400 Subject: [PATCH 1/3] docs(bigquery): improve RowIterator docs in regards to jobs.query API --- bigquery/doc.go | 4 +++- bigquery/iterator.go | 10 ++++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/bigquery/doc.go b/bigquery/doc.go index c1525b02d534..39ca839043cc 100644 --- a/bigquery/doc.go +++ b/bigquery/doc.go @@ -104,7 +104,9 @@ To retrieve the job's results from the ID, first look up the Job: } Use the Job.Read method to obtain an iterator, and loop over the rows. -Query.Read is just a convenience method that combines Query.Run and Job.Read. +Calling Query.Read is preferred for queries with a relatively small result set, +as it will call BigQuery jobs.query API for a optimized query path. If the query +doesn't meet that criteria, the method will just combine Query.Run and Job.Read. it, err = job.Read(ctx) if err != nil { diff --git a/bigquery/iterator.go b/bigquery/iterator.go index 7c358e288dd7..45de0f01dbf7 100644 --- a/bigquery/iterator.go +++ b/bigquery/iterator.go @@ -54,10 +54,16 @@ type RowIterator struct { // is also set, StartIndex is ignored. StartIndex uint64 - // The schema of the table. Available after the first call to Next. + // The schema of the table. + // In some scenarios it will only be available after the first + // call to Next(), like when a call to Query.Read uses + // the jobs.query API for an optimized query path. Schema Schema - // The total number of rows in the result. Available after the first call to Next. + // The total number of rows in the result. + // In some scenarios it will only be available after the first + // call to Next(), like when a call to Query.Read uses + // the jobs.query API for an optimized query path. // May be zero just after rows were inserted. TotalRows uint64 From 68fe0f848cb50140614f46a29c4ca8b9345aeac1 Mon Sep 17 00:00:00 2001 From: Alvaro Viebrantz Date: Tue, 15 Aug 2023 11:33:27 -0400 Subject: [PATCH 2/3] docs(bigquery): pagination incompatibility with Storage API --- bigquery/bigquery.go | 2 ++ bigquery/iterator.go | 4 +++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/bigquery/bigquery.go b/bigquery/bigquery.go index 698f895edefa..a71c4faa3673 100644 --- a/bigquery/bigquery.go +++ b/bigquery/bigquery.go @@ -101,6 +101,8 @@ func NewClient(ctx context.Context, projectID string, opts ...option.ClientOptio // EnableStorageReadClient sets up Storage API connection to be used when fetching // large datasets from tables, jobs or queries. +// Currently out of pagination methods like PageInfo().Token and RowIterator.StartIndex +// are not supported when the Storage API is enabled. // Calling this method twice will return an error. func (c *Client) EnableStorageReadClient(ctx context.Context, opts ...option.ClientOption) error { if c.isStorageReadAvailable() { diff --git a/bigquery/iterator.go b/bigquery/iterator.go index 45de0f01dbf7..dbf56db0e407 100644 --- a/bigquery/iterator.go +++ b/bigquery/iterator.go @@ -51,7 +51,8 @@ type RowIterator struct { pf pageFetcher // StartIndex can be set before the first call to Next. If PageInfo().Token - // is also set, StartIndex is ignored. + // is also set, StartIndex is ignored. If Storage API is enabled, + // StartIndex is also ignored because is not supported. StartIndex uint64 // The schema of the table. @@ -175,6 +176,7 @@ func isStructPtr(x interface{}) bool { } // PageInfo supports pagination. See the google.golang.org/api/iterator package for details. +// Currently pagination is not supported when the Storage API is enabled. func (it *RowIterator) PageInfo() *iterator.PageInfo { return it.pageInfo } func (it *RowIterator) fetch(pageSize int, pageToken string) (string, error) { From 674495e48775ccf70723ac6d964e3ed825404161 Mon Sep 17 00:00:00 2001 From: Alvaro Viebrantz Date: Tue, 15 Aug 2023 13:59:19 -0400 Subject: [PATCH 3/3] docs: mention IsAccelerated method to check if Storage API is enabled --- bigquery/iterator.go | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/bigquery/iterator.go b/bigquery/iterator.go index dbf56db0e407..b5823e7f4a73 100644 --- a/bigquery/iterator.go +++ b/bigquery/iterator.go @@ -52,7 +52,8 @@ type RowIterator struct { // StartIndex can be set before the first call to Next. If PageInfo().Token // is also set, StartIndex is ignored. If Storage API is enabled, - // StartIndex is also ignored because is not supported. + // StartIndex is also ignored because is not supported. IsAccelerated() + // method can be called to check if Storage API is enabled for the RowIterator. StartIndex uint64 // The schema of the table. @@ -176,7 +177,8 @@ func isStructPtr(x interface{}) bool { } // PageInfo supports pagination. See the google.golang.org/api/iterator package for details. -// Currently pagination is not supported when the Storage API is enabled. +// Currently pagination is not supported when the Storage API is enabled. IsAccelerated() +// method can be called to check if Storage API is enabled for the RowIterator. func (it *RowIterator) PageInfo() *iterator.PageInfo { return it.pageInfo } func (it *RowIterator) fetch(pageSize int, pageToken string) (string, error) {