Google-cloud-ruby: Support BigQuery Query Parameters

[blowmage]

Query Parameters are no longer marked [experimental], so we should support them!

[bjwatson]

@blowmage I added the "blocking beta" flag to this issue.

You also said there was an issue dealing with a "new flag for legacy SQL". Which issue is that? Is it also "blocking beta"?

[blowmage]

The legacy sql feature was added in #720. @quartzmo was going to follow up with some additional tweaks and documentation changes, but I don't think there is an issue open for that yet.

[blowmage]

@bjwatson Just created #1086 to track the legacy SQL changes, and flagged it with "blocking beta".

[blowmage]

I think I would like to break backwards compatibility in order to better support this. Specifically I'd like to remove the current optional arguments from the various query methods and yield a Query object so those settings can be made.

That means that this code:

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

data = bigquery.query "SELECT name FROM my_table", max: 1000, cache: true
data.each do |row|
  puts row["name"]
end

Would instead look like this:

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

data = bigquery.query "SELECT name FROM my_table" do |q|
  q.max = 1000
  q.cache = true
end

data.each do |row|
  puts row["name"]
end

The benefit for making this backwards compatible change is that we may be able to support named SQL parameters in the method call:

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

data = bigquery.query "SELECT name FROM my_table WHERE organization = @name", name: "Google" do |q|
  q.max = 1000
  q.cache = true
end

data.each do |row|
  puts row["name"]
end

[quartzmo]

I agree that supporting arbitrary SQL parameter names as keyword arguments is nice. Do we expect most calls to query to use this new feature?

[blowmage]

IMO the closest comparison we have is Datastore's gql method. The GqlQuery class allows both positional and named query parameters (Datastore calls them bindings), but the gql convenience method makes it very easy to use named parameters/bindings.

If BigQuery yields the Query object then users can still configure the query while setting named parameters in the method arguments.

[danoscarmike]

@blowmage do you have anything blocking this solution? Please let me know if so. If not, do you have an estimate on time to completion?

[blowmage]

@danoscarmike Actively working on it now. Should be tonight or tomorrow.

[danoscarmike]

Thank you @blowmage and @quartzmo