BigQuery: document proper use of run_async_query/QueryJob/QueryResult

[bits01]

If I run an async query using run_async_query(), get a QueryJob from it and a QueryResult from that by calling job.query_results(), the rows attribute of QR is empty. It seems that when the GET request is sent a parameter maxResults=0 is automatically added, in the client code, which explains why rows is empty.

But this is confusing and not how it behaves for sync queries. I think it should allow getting some rows in that first GET request.

Can you please document the proper use of async queries and QueryResult? Thank you.

[lukesneeringer]

@tswast @jba Assigning you two since I am pretty sure this is likely already fixed in the BigQuery work you are doing, but please verify.

[tswast]

We still need to update the docs, but yes, it's covered by the work we're doing.

The sample at https://github.com/GoogleCloudPlatform/python-docs-samples/blob/master/bigquery/cloud-client/query.py has the current best practices for async queries.

The gist is to ignore QueryResult for the most part. We are doing some work to make this easier in a future version.

[bits01]

How does one get a count of the rows returned by a query without using QueryResult? Not possible it seems from the destination_table.fetch_data() iterator, even though the REST API does return a totalRows property. Will this also be addressed in the future improvements?

[tswast]

Thanks for the feedback. I'll double-check that this property is covered.

[tswast]

I believe #4153 (comment) is a duplicate of #4152. The problem is that the total_rows property is only updated after doing the first request to fetch the first page.

I plan to address this by prefetching the first page of results when doing the function call to list rows.