Quick question for you about usage: is the client intended to be a singleton (pretty typical and understandable if so)? Anecdotally, I know that it's already usable this way (despite the context arg) without issue.

From the readme:

First create a bigquery.Client to use throughout your application: [snip]:# (bq-1)

However, I noticed that the client itself takes a context (for me, a bit unusual for something long-lived in an app's dependency graph). My first glance at this PR made me wonder about the new short query optimization optional job creation option being an option of the client (and in turn every query one generates) rather than to the function(s) that perform query execution. The answer is pretty simple if the readme is inaccurate and it is in fact intended to construct new clients on-demand at query time (which I could see, given that it's a wrapper around the HTTP API) .

Not a big deal either way, because currently-using applications with mixed query workloads could just add one more singleton to their dependency graph (an identical construction of NewClient, but setting this new option) for usage in places where there's an explicit intent/need to execute with optional job creation.

@zcross Apologies, missed your comment initially.

While it would be nice if a client could be truly singleton and stateless, in practice it's not really the case. One of the less obvious things going on under the hood is authentication, which, depending on the particular protocol, can be doing things like refreshing credentials in the background.

Thanks for reading! By the way, does the minimalJob (stub?) returned on the fast path actually work for retrieving query statistics? And on the topic, what would be the best way for a caller to distinguish whether the fast path was exercised or not, e.g., through RowIterator.SourceJob which naturally points to this minimalJob result?

If the minimal job is strictly there to support the iterator that's returned, and not other access patterns (which I'd understand), I'm wondering if there's a reasonable way to include query metadata (e.g., statistics like bytes processed, if available) for observability by the caller.

Related to above question: the docs suggest that the iterator will have a nil SourceJob if no job was created, but it doesn't seem like that's the case (instead, source job is set to the minimalJob object that seems synthetic – not a "real" job naturally)

https://cloud.google.com/bigquery/docs/running-queries#optional-job-creation
From the code snippet for Go ^

	// The iterator provides information about the query execution.
	// Queries that were run in short query mode will not have the source job
	// populated.
	if it.SourceJob() == nil {
		fmt.Fprintf(w, "Query was run in optional job mode.  Query ID: %q\n", it.QueryID())
	} else {
		j := it.SourceJob()
		qualifiedJobID := fmt.Sprintf("%s:%s.%s", j.ProjectID(), j.Location(), j.ID())
		fmt.Fprintf(w, "Query was run with job state.  Job ID: %q, Query ID: %q\n",
			qualifiedJobID, it.QueryID())
	}