# Copyright 2015 Google LLC

#

# Licensed under the Apache License, Version 2.0 (the "License");

# you may not use this file except in compliance with the License.

# You may obtain a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing, software

# distributed under the License is distributed on an "AS IS" BASIS,

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

# See the License for the specific language governing permissions and

# limitations under the License.

"""BigQuery query processing."""

from collections import OrderedDict

import copy

import datetime

import decimal

from typing import Any, cast, Optional, Dict, Union

from google.cloud.bigquery.table import _parse_schema_resource

from google.cloud.bigquery import _helpers

from google.cloud.bigquery._helpers import _rows_from_json

from google.cloud.bigquery._helpers import _SCALAR_VALUE_TO_JSON_PARAM

from google.cloud.bigquery._helpers import _SUPPORTED_RANGE_ELEMENTS

_SCALAR_VALUE_TYPE = Optional[

Union[str, int, float, decimal.Decimal, bool, datetime.datetime, datetime.date]

]

class ConnectionProperty:

"""A connection-level property to customize query behavior.

See

https://cloud.google.com/bigquery/docs/reference/rest/v2/ConnectionProperty

Args:

key:

The key of the property to set, for example, ``'time_zone'`` or

``'session_id'``.

value: The value of the property to set.

"""

def __init__(self, key: str = "", value: str = ""):

self._properties = {

"key": key,

"value": value,

}

@property

def key(self) -> str:

"""Name of the property.

For example:

* ``time_zone``

* ``session_id``

"""

return self._properties["key"]

@property

def value(self) -> str:

"""Value of the property."""

return self._properties["value"]

@classmethod

def from_api_repr(cls, resource) -> "ConnectionProperty":

"""Construct :class:`~google.cloud.bigquery.query.ConnectionProperty`

from JSON resource.

Args:

resource: JSON representation.

Returns:

A connection property.

"""

value = cls()

value._properties = resource

return value

def to_api_repr(self) -> Dict[str, Any]:

"""Construct JSON API representation for the connection property.

Returns:

JSON mapping

"""

return self._properties

class UDFResource(object):

"""Describe a single user-defined function (UDF) resource.

Args:

udf_type (str): The type of the resource ('inlineCode' or 'resourceUri')

value (str): The inline code or resource URI.

See:

https://cloud.google.com/bigquery/user-defined-functions#api

"""

def __init__(self, udf_type, value):

self.udf_type = udf_type

self.value = value

def __eq__(self, other):

if not isinstance(other, UDFResource):

return NotImplemented

return self.udf_type == other.udf_type and self.value == other.value

def __ne__(self, other):

return not self == other

class _AbstractQueryParameterType:

"""Base class for representing query parameter types.

https://cloud.google.com/bigquery/docs/reference/rest/v2/QueryParameter#queryparametertype

"""

@classmethod

def from_api_repr(cls, resource):

"""Factory: construct parameter type from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.QueryParameterType: Instance

"""

raise NotImplementedError

def to_api_repr(self):

"""Construct JSON API representation for the parameter type.

Returns:

Dict: JSON mapping

"""

raise NotImplementedError

class ScalarQueryParameterType(_AbstractQueryParameterType):

"""Type representation for scalar query parameters.

Args:

type_ (str):

One of 'STRING', 'INT64', 'FLOAT64', 'NUMERIC', 'BOOL', 'TIMESTAMP',

'DATETIME', or 'DATE'.

name (Optional[str]):

The name of the query parameter. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

description (Optional[str]):

The query parameter description. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

"""

def __init__(self, type_, *, name=None, description=None):

self._type = type_

self.name = name

self.description = description

@classmethod

def from_api_repr(cls, resource):

"""Factory: construct parameter type from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.ScalarQueryParameterType: Instance

"""

type_ = resource["type"]

return cls(type_)

def to_api_repr(self):

"""Construct JSON API representation for the parameter type.

Returns:

Dict: JSON mapping

"""

# Name and description are only used if the type is a field inside a struct

# type, but it's StructQueryParameterType's responsibilty to use these two

# attributes in the API representation when needed. Here we omit them.

return {"type": self._type}

def with_name(self, new_name: Union[str, None]):

"""Return a copy of the instance with ``name`` set to ``new_name``.

Args:

name (Union[str, None]):

The new name of the query parameter type. If ``None``, the existing

name is cleared.

Returns:

google.cloud.bigquery.query.ScalarQueryParameterType:

A new instance with updated name.

"""

return type(self)(self._type, name=new_name, description=self.description)

def __repr__(self):

name = f", name={self.name!r}" if self.name is not None else ""

description = (

f", description={self.description!r}"

if self.description is not None

else ""

)

return f"{self.__class__.__name__}({self._type!r}{name}{description})"

class ArrayQueryParameterType(_AbstractQueryParameterType):

"""Type representation for array query parameters.

Args:

array_type (Union[ScalarQueryParameterType, StructQueryParameterType]):

The type of array elements.

name (Optional[str]):

The name of the query parameter. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

description (Optional[str]):

The query parameter description. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

"""

def __init__(self, array_type, *, name=None, description=None):

self._array_type = array_type

self.name = name

self.description = description

@classmethod

def from_api_repr(cls, resource):

"""Factory: construct parameter type from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.ArrayQueryParameterType: Instance

"""

array_item_type = resource["arrayType"]["type"]

if array_item_type in {"STRUCT", "RECORD"}:

klass = StructQueryParameterType

else:

klass = ScalarQueryParameterType

item_type_instance = klass.from_api_repr(resource["arrayType"])

return cls(item_type_instance)

def to_api_repr(self):

"""Construct JSON API representation for the parameter type.

Returns:

Dict: JSON mapping

"""

# Name and description are only used if the type is a field inside a struct

# type, but it's StructQueryParameterType's responsibilty to use these two

# attributes in the API representation when needed. Here we omit them.

return {

"type": "ARRAY",

"arrayType": self._array_type.to_api_repr(),

}

def __repr__(self):

name = f", name={self.name!r}" if self.name is not None else ""

description = (

f", description={self.description!r}"

if self.description is not None

else ""

)

return f"{self.__class__.__name__}({self._array_type!r}{name}{description})"

class StructQueryParameterType(_AbstractQueryParameterType):

"""Type representation for struct query parameters.

Args:

fields (Iterable[Union[ \

ArrayQueryParameterType, ScalarQueryParameterType, StructQueryParameterType \

]]):

An non-empty iterable describing the struct's field types.

name (Optional[str]):

The name of the query parameter. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

description (Optional[str]):

The query parameter description. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

"""

def __init__(self, *fields, name=None, description=None):

if not fields:

raise ValueError("Struct type must have at least one field defined.")

self._fields = fields # fields is a tuple (immutable), no shallow copy needed

self.name = name

self.description = description

@property

def fields(self):

return self._fields # no copy needed, self._fields is an immutable sequence

@classmethod

def from_api_repr(cls, resource):

"""Factory: construct parameter type from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.StructQueryParameterType: Instance

"""

fields = []

for struct_field in resource["structTypes"]:

type_repr = struct_field["type"]

if type_repr["type"] in {"STRUCT", "RECORD"}:

klass = StructQueryParameterType

elif type_repr["type"] == "ARRAY":

klass = ArrayQueryParameterType

else:

klass = ScalarQueryParameterType

type_instance = klass.from_api_repr(type_repr)

type_instance.name = struct_field.get("name")

type_instance.description = struct_field.get("description")

fields.append(type_instance)

return cls(*fields)

def to_api_repr(self):

"""Construct JSON API representation for the parameter type.

Returns:

Dict: JSON mapping

"""

fields = []

for field in self._fields:

item = {"type": field.to_api_repr()}

if field.name is not None:

item["name"] = field.name

if field.description is not None:

item["description"] = field.description

fields.append(item)

return {

"type": "STRUCT",

"structTypes": fields,

}

def __repr__(self):

name = f", name={self.name!r}" if self.name is not None else ""

description = (

f", description={self.description!r}"

if self.description is not None

else ""

)

items = ", ".join(repr(field) for field in self._fields)

return f"{self.__class__.__name__}({items}{name}{description})"

class RangeQueryParameterType(_AbstractQueryParameterType):

"""Type representation for range query parameters.

Args:

type_ (Union[ScalarQueryParameterType, str]):

Type of range element, must be one of 'TIMESTAMP', 'DATETIME', or

'DATE'.

name (Optional[str]):

The name of the query parameter. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

description (Optional[str]):

The query parameter description. Primarily used if the type is

one of the subfields in ``StructQueryParameterType`` instance.

"""

@classmethod

def _parse_range_element_type(self, type_):

"""Helper method that parses the input range element type, which may

be a string, or a ScalarQueryParameterType object.

Returns:

google.cloud.bigquery.query.ScalarQueryParameterType: Instance

"""

if isinstance(type_, str):

if type_ not in _SUPPORTED_RANGE_ELEMENTS:

raise ValueError(

"If given as a string, range element type must be one of "

"'TIMESTAMP', 'DATE', or 'DATETIME'."

)

return ScalarQueryParameterType(type_)

elif isinstance(type_, ScalarQueryParameterType):

if type_._type not in _SUPPORTED_RANGE_ELEMENTS:

raise ValueError(

"If given as a ScalarQueryParameter object, range element "

"type must be one of 'TIMESTAMP', 'DATE', or 'DATETIME' "

"type."

)

return type_

else:

raise ValueError(

"range_type must be a string or ScalarQueryParameter object, "

"of 'TIMESTAMP', 'DATE', or 'DATETIME' type."

)

def __init__(self, type_, *, name=None, description=None):

self.type_ = self._parse_range_element_type(type_)

self.name = name

self.description = description

@classmethod

def from_api_repr(cls, resource):

"""Factory: construct parameter type from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.RangeQueryParameterType: Instance

"""

type_ = resource["rangeElementType"]["type"]

name = resource.get("name")

description = resource.get("description")

return cls(type_, name=name, description=description)

def to_api_repr(self):

"""Construct JSON API representation for the parameter type.

Returns:

Dict: JSON mapping

"""

# Name and description are only used if the type is a field inside a struct

# type, but it's StructQueryParameterType's responsibilty to use these two

# attributes in the API representation when needed. Here we omit them.

return {

"type": "RANGE",

"rangeElementType": self.type_.to_api_repr(),

}

def with_name(self, new_name: Union[str, None]):

"""Return a copy of the instance with ``name`` set to ``new_name``.

Args:

name (Union[str, None]):

The new name of the range query parameter type. If ``None``,

the existing name is cleared.

Returns:

google.cloud.bigquery.query.RangeQueryParameterType:

A new instance with updated name.

"""

return type(self)(self.type_, name=new_name, description=self.description)

def __repr__(self):

name = f", name={self.name!r}" if self.name is not None else ""

description = (

f", description={self.description!r}"

if self.description is not None

else ""

)

return f"{self.__class__.__name__}({self.type_!r}{name}{description})"

def _key(self):

"""A tuple key that uniquely describes this field.

Used to compute this instance's hashcode and evaluate equality.

Returns:

Tuple: The contents of this

:class:`~google.cloud.bigquery.query.RangeQueryParameterType`.

"""

type_ = self.type_.to_api_repr()

return (self.name, type_, self.description)

def __eq__(self, other):

if not isinstance(other, RangeQueryParameterType):

return NotImplemented

return self._key() == other._key()

def __ne__(self, other):

return not self == other

class _AbstractQueryParameter(object):

"""Base class for named / positional query parameters."""

@classmethod

def from_api_repr(cls, resource: dict) -> "_AbstractQueryParameter":

"""Factory: construct parameter from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

A new instance of _AbstractQueryParameter subclass.

"""

raise NotImplementedError

def to_api_repr(self) -> dict:

"""Construct JSON API representation for the parameter.

Returns:

Dict: JSON representation for the parameter.

"""

raise NotImplementedError

class ScalarQueryParameter(_AbstractQueryParameter):

"""Named / positional query parameters for scalar values.

Args:

name:

Parameter name, used via ``@foo`` syntax. If None, the

parameter can only be addressed via position (``?``).

type_:

Name of parameter type. See

:class:`google.cloud.bigquery.enums.SqlTypeNames` and

:class:`google.cloud.bigquery.query.SqlParameterScalarTypes` for

supported types.

value:

The scalar parameter value.

"""

def __init__(

self,

name: Optional[str],

type_: Optional[Union[str, ScalarQueryParameterType]],

value: _SCALAR_VALUE_TYPE,

):

self.name = name

if isinstance(type_, ScalarQueryParameterType):

self.type_ = type_._type

else:

self.type_ = type_

self.value = value

@classmethod

def positional(

cls, type_: Union[str, ScalarQueryParameterType], value: _SCALAR_VALUE_TYPE

) -> "ScalarQueryParameter":

"""Factory for positional paramater.

Args:

type_:

Name of parameter type. One of 'STRING', 'INT64',

'FLOAT64', 'NUMERIC', 'BIGNUMERIC', 'BOOL', 'TIMESTAMP', 'DATETIME', or

'DATE'.

value:

The scalar parameter value.

Returns:

google.cloud.bigquery.query.ScalarQueryParameter: Instance without name

"""

return cls(None, type_, value)

@classmethod

def from_api_repr(cls, resource: dict) -> "ScalarQueryParameter":

"""Factory: construct parameter from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.ScalarQueryParameter: Instance

"""

# Import here to avoid circular imports.

from google.cloud.bigquery import schema

name = resource.get("name")

type_ = resource["parameterType"]["type"]

# parameterValue might not be present if JSON resource originates

# from the back-end - the latter omits it for None values.

value = resource.get("parameterValue", {}).get("value")

if value is not None:

converted = _helpers.SCALAR_QUERY_PARAM_PARSER.to_py(

value, schema.SchemaField(cast(str, name), type_)

)

else:

converted = None

return cls(name, type_, converted)

def to_api_repr(self) -> dict:

"""Construct JSON API representation for the parameter.

Returns:

Dict: JSON mapping

"""

value = self.value

converter = _SCALAR_VALUE_TO_JSON_PARAM.get(self.type_, lambda value: value)

value = converter(value) # type: ignore

resource: Dict[str, Any] = {

"parameterType": {"type": self.type_},

"parameterValue": {"value": value},

}

if self.name is not None:

resource["name"] = self.name

return resource

def _key(self):

"""A tuple key that uniquely describes this field.

Used to compute this instance's hashcode and evaluate equality.

Returns:

Tuple: The contents of this :class:`~google.cloud.bigquery.query.ScalarQueryParameter`.

"""

return (self.name, self.type_.upper(), self.value)

def __eq__(self, other):

if not isinstance(other, ScalarQueryParameter):

return NotImplemented

return self._key() == other._key()

def __ne__(self, other):

return not self == other

def __repr__(self):

return "ScalarQueryParameter{}".format(self._key())

class ArrayQueryParameter(_AbstractQueryParameter):

"""Named / positional query parameters for array values.

Args:

name (Optional[str]):

Parameter name, used via ``@foo`` syntax. If None, the

parameter can only be addressed via position (``?``).

array_type (Union[str, ScalarQueryParameterType, StructQueryParameterType]):

The type of array elements. If given as a string, it must be one of

`'STRING'`, `'INT64'`, `'FLOAT64'`, `'NUMERIC'`, `'BIGNUMERIC'`, `'BOOL'`,

`'TIMESTAMP'`, `'DATE'`, or `'STRUCT'`/`'RECORD'`.

If the type is ``'STRUCT'``/``'RECORD'`` and ``values`` is empty,

the exact item type cannot be deduced, thus a ``StructQueryParameterType``

instance needs to be passed in.

values (List[appropriate type]): The parameter array values.

"""

def __init__(self, name, array_type, values) -> None:

self.name = name

self.values = values

if isinstance(array_type, str):

if not values and array_type in {"RECORD", "STRUCT"}:

raise ValueError(

"Missing detailed struct item type info for an empty array, "

"please provide a StructQueryParameterType instance."

)

self.array_type = array_type

@classmethod

def positional(cls, array_type: str, values: list) -> "ArrayQueryParameter":

"""Factory for positional parameters.

Args:

array_type (Union[str, ScalarQueryParameterType, StructQueryParameterType]):

The type of array elements. If given as a string, it must be one of

`'STRING'`, `'INT64'`, `'FLOAT64'`, `'NUMERIC'`, `'BIGNUMERIC'`,

`'BOOL'`, `'TIMESTAMP'`, `'DATE'`, or `'STRUCT'`/`'RECORD'`.

If the type is ``'STRUCT'``/``'RECORD'`` and ``values`` is empty,

the exact item type cannot be deduced, thus a ``StructQueryParameterType``

instance needs to be passed in.

values (List[appropriate type]): The parameter array values.

Returns:

google.cloud.bigquery.query.ArrayQueryParameter: Instance without name

"""

return cls(None, array_type, values)

@classmethod

def _from_api_repr_struct(cls, resource):

name = resource.get("name")

converted = []

# We need to flatten the array to use the StructQueryParameter

# parse code.

resource_template = {

# The arrayType includes all the types of the fields of the STRUCT

"parameterType": resource["parameterType"]["arrayType"]

}

for array_value in resource["parameterValue"]["arrayValues"]:

struct_resource = copy.deepcopy(resource_template)

struct_resource["parameterValue"] = array_value

struct_value = StructQueryParameter.from_api_repr(struct_resource)

converted.append(struct_value)

return cls(name, "STRUCT", converted)

@classmethod

def _from_api_repr_scalar(cls, resource):

"""Converts REST resource into a list of scalar values."""

# Import here to avoid circular imports.

from google.cloud.bigquery import schema

name = resource.get("name")

array_type = resource["parameterType"]["arrayType"]["type"]

parameter_value = resource.get("parameterValue", {})

array_values = parameter_value.get("arrayValues", ())

values = [value["value"] for value in array_values]

converted = [

_helpers.SCALAR_QUERY_PARAM_PARSER.to_py(

value, schema.SchemaField(name, array_type)

)

for value in values

]

return cls(name, array_type, converted)

@classmethod

def from_api_repr(cls, resource: dict) -> "ArrayQueryParameter":

"""Factory: construct parameter from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.ArrayQueryParameter: Instance

"""

array_type = resource["parameterType"]["arrayType"]["type"]

if array_type == "STRUCT":

return cls._from_api_repr_struct(resource)

return cls._from_api_repr_scalar(resource)

def to_api_repr(self) -> dict:

"""Construct JSON API representation for the parameter.

Returns:

Dict: JSON mapping

"""

values = self.values

if self.array_type in {"RECORD", "STRUCT"} or isinstance(

self.array_type, StructQueryParameterType

):

reprs = [value.to_api_repr() for value in values]

a_values = [repr_["parameterValue"] for repr_ in reprs]

if reprs:

a_type = reprs[0]["parameterType"]

else:

# This assertion always evaluates to True because the

# constructor disallows STRUCT/RECORD type defined as a

# string with empty values.

assert isinstance(self.array_type, StructQueryParameterType)

a_type = self.array_type.to_api_repr()

else:

# Scalar array item type.

if isinstance(self.array_type, str):

a_type = {"type": self.array_type}

else:

a_type = self.array_type.to_api_repr()

converter = _SCALAR_VALUE_TO_JSON_PARAM.get(

a_type["type"], lambda value: value

)

values = [converter(value) for value in values] # type: ignore

a_values = [{"value": value} for value in values]

resource = {

"parameterType": {"type": "ARRAY", "arrayType": a_type},

"parameterValue": {"arrayValues": a_values},

}

if self.name is not None:

resource["name"] = self.name

return resource

def _key(self):

"""A tuple key that uniquely describes this field.

Used to compute this instance's hashcode and evaluate equality.

Returns:

Tuple: The contents of this :class:`~google.cloud.bigquery.query.ArrayQueryParameter`.

"""

if isinstance(self.array_type, str):

item_type = self.array_type

elif isinstance(self.array_type, ScalarQueryParameterType):

item_type = self.array_type._type

else:

item_type = "STRUCT"

return (self.name, item_type.upper(), self.values)

def __eq__(self, other):

if not isinstance(other, ArrayQueryParameter):

return NotImplemented

return self._key() == other._key()

def __ne__(self, other):

return not self == other

def __repr__(self):

return "ArrayQueryParameter{}".format(self._key())

class StructQueryParameter(_AbstractQueryParameter):

"""Name / positional query parameters for struct values.

Args:

name (Optional[str]):

Parameter name, used via ``@foo`` syntax. If None, the

parameter can only be addressed via position (``?``).

sub_params (Union[Tuple[

google.cloud.bigquery.query.ScalarQueryParameter,

google.cloud.bigquery.query.ArrayQueryParameter,

google.cloud.bigquery.query.StructQueryParameter

]]): The sub-parameters for the struct

"""

def __init__(self, name, *sub_params) -> None:

self.name = name

self.struct_types: Dict[str, Any] = OrderedDict()

self.struct_values: Dict[str, Any] = {}

types = self.struct_types

values = self.struct_values

for sub in sub_params:

if isinstance(sub, self.__class__):

types[sub.name] = "STRUCT"

values[sub.name] = sub

elif isinstance(sub, ArrayQueryParameter):

types[sub.name] = "ARRAY"

values[sub.name] = sub

else:

types[sub.name] = sub.type_

values[sub.name] = sub.value

@classmethod

def positional(cls, *sub_params):

"""Factory for positional parameters.

Args:

sub_params (Union[Tuple[

google.cloud.bigquery.query.ScalarQueryParameter,

google.cloud.bigquery.query.ArrayQueryParameter,

google.cloud.bigquery.query.StructQueryParameter

]]): The sub-parameters for the struct

Returns:

google.cloud.bigquery.query.StructQueryParameter: Instance without name

"""

return cls(None, *sub_params)

@classmethod

def from_api_repr(cls, resource: dict) -> "StructQueryParameter":

"""Factory: construct parameter from JSON resource.

Args:

resource (Dict): JSON mapping of parameter

Returns:

google.cloud.bigquery.query.StructQueryParameter: Instance

"""

# Import here to avoid circular imports.

from google.cloud.bigquery import schema

name = resource.get("name")

instance = cls(name)

type_resources = {}

types = instance.struct_types

for item in resource["parameterType"]["structTypes"]:

types[item["name"]] = item["type"]["type"]

type_resources[item["name"]] = item["type"]

struct_values = resource["parameterValue"]["structValues"]

for key, value in struct_values.items():

type_ = types[key]

converted: Optional[Union[ArrayQueryParameter, StructQueryParameter]] = None

if type_ == "STRUCT":

struct_resource = {

"name": key,

"parameterType": type_resources[key],

"parameterValue": value,

}

converted = StructQueryParameter.from_api_repr(struct_resource)

elif type_ == "ARRAY":

struct_resource = {

"name": key,

"parameterType": type_resources[key],

"parameterValue": value,

}

converted = ArrayQueryParameter.from_api_repr(struct_resource)

else:

value = value["value"]

converted = _helpers.SCALAR_QUERY_PARAM_PARSER.to_py(

value, schema.SchemaField(cast(str, name), type_)

)

instance.struct_values[key] = converted

return instance

def to_api_repr(self) -> dict:

"""Construct JSON API representation for the parameter.

Returns:

Dict: JSON mapping

"""

s_types = {}

values = {}

for name, value in self.struct_values.items():

type_ = self.struct_types[name]

if type_ in ("STRUCT", "ARRAY"):

repr_ = value.to_api_repr()

s_types[name] = {"name": name, "type": repr_["parameterType"]}

values[name] = repr_["parameterValue"]

else:

s_types[name] = {"name": name, "type": {"type": type_}}

converter = _SCALAR_VALUE_TO_JSON_PARAM.get(type_, lambda value: value)

values[name] = {"value": converter(value)}

resource = {

"parameterType": {

"type": "STRUCT",

"structTypes": [s_types[key] for key in self.struct_types],

},

"parameterValue": {"structValues": values},

}

if self.name is not None:

resource["name"] = self.name

return resource

def _key(self):

"""A tuple key that uniquely describes this field.

Used to compute this instance's hashcode and evaluate equality.

Returns:

Tuple: The contents of this :class:`~google.cloud.bigquery.ArrayQueryParameter`.

"""

return (self.name, self.struct_types, self.struct_values)

def __eq__(self, other):

if not isinstance(other, StructQueryParameter):

return NotImplemented

return self._key() == other._key()

def __ne__(self, other):

return not self == other

def __repr__(self):

return "StructQueryParameter{}".format(self._key())

class RangeQueryParameter(_AbstractQueryParameter):

"""Named / positional query parameters for range values.

Args:

range_element_type (Union[str, RangeQueryParameterType]):

The type of range elements. It must be one of 'TIMESTAMP',

'DATE', or 'DATETIME'.

start (Optional[Union[ScalarQueryParameter, str]]):

The start of the range value. Must be the same type as

range_element_type. If not provided, it's interpreted as UNBOUNDED.

end (Optional[Union[ScalarQueryParameter, str]]):

The end of the range value. Must be the same type as

range_element_type. If not provided, it's interpreted as UNBOUNDED.

name (Optional[str]):

Parameter name, used via ``@foo`` syntax. If None, the

parameter can only be addressed via position (``?``).

"""

@classmethod

def _parse_range_element_type(self, range_element_type):

if isinstance(range_element_type, str):

if range_element_type not in _SUPPORTED_RANGE_ELEMENTS:

raise ValueError(

"If given as a string, range_element_type must be one of "

f"'TIMESTAMP', 'DATE', or 'DATETIME'. Got {range_element_type}."

)

return RangeQueryParameterType(range_element_type)

elif isinstance(range_element_type, RangeQueryParameterType):

if range_element_type.type_._type not in _SUPPORTED_RANGE_ELEMENTS:

raise ValueError(

"If given as a RangeQueryParameterType object, "

"range_element_type must be one of 'TIMESTAMP', 'DATE', "

"or 'DATETIME' type."

)

return range_element_type

else:

raise ValueError(

"range_element_type must be a string or "

"RangeQueryParameterType object, of 'TIMESTAMP', 'DATE', "

"or 'DATETIME' type. Got "

f"{type(range_element_type)}:{range_element_type}"

)

@classmethod

def _serialize_range_element_value(self, value, type_):