feat(bigquery): add support for explicit query parameter type

[alvarowolfx]

Allow users to pass query parameter with an explicit data types instead of relying just on reflection of Go types. Right now the data type that is affect by this change is *big.Rat, which before was only converted to NUMERIC with 9 digits, and now can be send as a BIGNUMERIC.

This adds two methods:

• NewScalarQueryParameter(name string, paramType FieldType, value interface{}) QueryParameter
• NewArrayQueryParameter(name string, paramType FieldType, value interface{}) QueryParameter

Example usage:

ctx := context.Background()
client, err := bigquery.NewClient(ctx, projectID)
if err != nil {
        return fmt.Errorf("bigquery.NewClient: %v", err)
}
defer client.Close()

rat := big.NewRat(12345, 10e10)
q := client.Query("SELECT @bigval, @array")
q.Parameters = []bigquery.QueryParameter{
        {
                Value: NewScalarQueryParameter("bigval", "BIGNUMERIC", rat)
        },
        {
                Value: NewArrayQueryParameter("array", "STRING", []string{"a","b","c"}
        },
}

I'm still evaluating if we need something like NewStructQueryParameter to pass a list of QueryParameters with explicit data types for each field.

Most of this was inspired by the Python implementation that has the same kind of methods for creating query parameters.

see: https://cloud.google.com/bigquery/docs/parameterized-queries#python_1

Resolves #4704

[alvarowolfx]

I changed to a slight different approach, having some specific struct and interface that can be used explicitly or with the current QueryParameter struct.

ctx := context.Background()
client, err := bigquery.NewClient(ctx, projectID)
if err != nil {
        return fmt.Errorf("bigquery.NewClient: %v", err)
}
defer client.Close()

rat := big.NewRat(12345, 10e10)
q := client.Query("SELECT @bigval, @array, @struct")
q.Parameters = []bigquery.QueryParameter{
        {
                Value: ScalarQueryParameter{Name: "bigval", Type: "BIGNUMERIC", Value: rat}
        },
        ArrayQueryParameter{Name: "array", Value: []string{"a","b","c"}, Type: ScalarQueryParameter{Type: "STRING"}}.QueryParameter(),
        StructQueryParameter{
	        Name: "val",
	        Value: map[string]ParameterValue{
		        "Timestamp": ScalarQueryParameter{
			        Value: ts,
		        },
		        "BigNumericArray": ArrayQueryParameter{
			        Value: []string{
				        BigNumericString(bigRat),
				        BigNumericString(rat),
			        },
		        },
		        "SubStruct": StructQueryParameter{
			        Value: map[string]ParameterValue{
				        "String": ScalarQueryParameter{
					        Value: "c",
				        },
			        },
		        },
	        },
	        Schema: map[string]ParameterType{
		        "Timestamp": ScalarQueryParameter{
			        Type: "TIMESTAMP",
		        },
		        "BigNumericArray": ArrayQueryParameter{
			        Type: ScalarQueryParameter{
				        Type: "BIGNUMERIC",
			        },
		        },
		        "SubStruct": StructQueryParameter{
			        Schema: map[string]ParameterType{
				        "String": ScalarQueryParameter{
					        Type: "STRING",
				        },
			        },
		        },
	        },
        }.QueryParameter()
}

[shollyman]

Document these fields as appropriate.

[shollyman]

I'm still on the fence about the name due to the collision with the API, but it's a reasonable name otherwise.

Should we document the behavior for nested types as part of the type description? Specifically that you need to fully specify types and values for complex params?

[shollyman]

I think the only work remaining is to flesh out the documentation for QueryParameterValue (and it's fields) and ship it. Approving contingent on that.

[shollyman]

Looks good, and I like the explicit examples of usage. Thanks for putting this together!