feat(bigquery): Add session support

[quartzmo]

• Add create_session and session_id params to Project#query_job
• Add session_id param to Project#query
• Add create_session and session_id params to Dataset#query_job
• Add session_id param to Dataset#query
• Add Job#session_id
• Add QueryJob::Updater#create_session=
• Add QueryJob::Updater#session_id=

closes: #15553

[quartzmo]

acceptance test failure is a flake:

Google::Cloud::Bigquery::Dataset::ddl_dml::bigquery#test_0002_creates and populates and drops a table with ddl/dml queries:
Google::Cloud::PermissionDeniedError: Exceeded rate limits: too many table update operations for this table. For more information, see https://cloud.google.com/bigquery/docs/troubleshoot-quotas

[dazuma]

If this is deprecated, can you include a note suggesting what to use instead?
(There's a similar place in project.rb.)

[quartzmo]

Yes, will do, thanks.

[quartzmo]

Updated.

[shollyman]

It looks like this change hides the connection properties and only exposes session_id as it's own property? How much more work is it to expose the connection properties in a more general fashion?

[quartzmo]

@shollyman Thanks for asking about this. Typically in the handwritten Ruby clients we try to simplify and flatten the API surface to make things easier for users by managing intermediate value objects that only have a field or two. The current list of connection properties, which is described as having only two simple properties (time_zone and session_id) is a candidate for this. Compare:

data = dataset.query "SELECT * FROM temptable", session_id: job.session_id

with

data = dataset.query "SELECT * FROM temptable", connection_properties: [{ "session_id": job.session_id }]

Composing this connection_properties array isn't too bad, but you might not understand from the param docs how it should look and need to locate a sample from which to copy/paste it. Historically we've tried to save users the trouble. Also, if we add session_id now, it doesn't prevent us from adding connection_properties in the future. The duplication would be especially acceptable if session_id is a popular argument that is commonly passed without the other properties.

It really depends on whether more properties will be added, and how many? Are time_zone and other possible future properties as likely as session_id to be passed with each and every query call? If so, I suppose real-world usage might look like this:

conn_props = [
  { "session_id": job.session_id },
  { "time_zone": time_zone },
  { "new_prop": "abc" }
]

data_a = dataset.query "SELECT * FROM temptable_a", connection_properties: conn_props
data_b = dataset.query "SELECT * FROM temptable_b", connection_properties: conn_props
data_c = dataset.query "SELECT * FROM temptable_c", connection_properties: conn_props

Given the examples above, let me know your guesses about the future and your preference!

[shollyman]

RE: other properties, I know of a third one coming soon for associating queries to specific workload profiles. So the number remains small, but is growing.

I think it's reasonable to just expose session now, and expand to a more general connectionproperties feature later, if there's no conflict/oddity with having both specific property and the general access to connection properties hung off the query config.

[quartzmo]

@dazuma Any thoughts on this? Does it seem worth it to have a session_id keyword arg just for user convenience in addition to the harder-to-use array of hashes connection_properties param that will also be needed?

[dazuma]

I think it makes sense to keep the separate session_id keyword argument, in keeping with our practice of flattening commonly used arguments like this. It doesn't preclude us from adding the more general argument in the future.

[quartzmo]

@shollyman Does this sound good? If so, any other concerns on this PR?

[meredithslota]

@quartzmo Seth is currently OOO but will reply shortly. :)

[quartzmo]

Merging with guidance from @d-torres.