google-cloud-bigquery 1.12.0 → 1.38.1

data/lib/google/cloud/bigquery/dataset.rb

@@ -18,6 +18,7 @@ require "google/cloud/errors"
 require "google/cloud/bigquery/service"
 require "google/cloud/bigquery/table"
 require "google/cloud/bigquery/model"
+require "google/cloud/bigquery/routine"
 require "google/cloud/bigquery/external"
 require "google/cloud/bigquery/dataset/list"
 require "google/cloud/bigquery/dataset/access"
@@ -68,8 +69,8 @@ module Google
         ##
         # A unique ID for this dataset, without the project name.
         #
-        # @return [String] The ID must contain only letters (a-z, A-Z), numbers
-        #   (0-9), or underscores (_). The maximum length is 1,024 characters.
+        # @return [String] The ID must contain only letters (`[A-Za-z]`), numbers
+        #   (`[0-9]`), or underscores (`_`). The maximum length is 1,024 characters.
         #
         # @!group Attributes
         #
@@ -312,12 +313,19 @@ module Google
         # @param [Hash<String, String>] labels A hash containing key/value
         #   pairs.
         #
-        #   * Label keys and values can be no longer than 63 characters.
-        #   * Label keys and values can contain only lowercase letters, numbers,
-        #     underscores, hyphens, and international characters.
-        #   * Label keys and values cannot exceed 128 bytes in size.
-        #   * Label keys must begin with a letter.
-        #   * Label keys must be unique within a dataset.
+        #   The labels applied to a resource must meet the following requirements:
+        #
+        #   * Each resource can have multiple labels, up to a maximum of 64.
+        #   * Each label must be a key-value pair.
+        #   * Keys have a minimum length of 1 character and a maximum length of
+        #     63 characters, and cannot be empty. Values can be empty, and have
+        #     a maximum length of 63 characters.
+        #   * Keys and values can contain only lowercase letters, numeric characters,
+        #     underscores, and dashes. All characters must use UTF-8 encoding, and
+        #     international characters are allowed.
+        #   * The key portion of a label must be unique. However, you can use the
+        #     same key with multiple resources.
+        #   * Keys must start with a lowercase letter or international character.
         #
         # @example
         #   require "google/cloud/bigquery"
@@ -335,6 +343,75 @@ module Google
           patch_gapi! :labels
         end
 
+        ##
+        # The {EncryptionConfiguration} object that represents the default
+        # encryption method for all tables and models in the dataset. Once this
+        # property is set, all newly-created partitioned tables and models in
+        # the dataset will have their encryption set to this value, unless table
+        # creation request (or query) overrides it.
+        #
+        # Present only if this dataset is using custom default encryption.
+        #
+        # @see https://cloud.google.com/bigquery/docs/customer-managed-encryption
+        #   Protecting Data with Cloud KMS Keys
+        #
+        # @return [EncryptionConfiguration, nil] The default encryption
+        #   configuration.
+        #
+        #   @!group Attributes
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   encrypt_config = dataset.default_encryption
+        #
+        # @!group Attributes
+        #
+        def default_encryption
+          return nil if reference?
+          ensure_full_data!
+          return nil if @gapi.default_encryption_configuration.nil?
+          EncryptionConfiguration.from_gapi(@gapi.default_encryption_configuration).freeze
+        end
+
+        ##
+        # Set the {EncryptionConfiguration} object that represents the default
+        # encryption method for all tables and models in the dataset. Once this
+        # property is set, all newly-created partitioned tables and models in
+        # the dataset will have their encryption set to this value, unless table
+        # creation request (or query) overrides it.
+        #
+        # If the dataset is not a full resource representation (see
+        # {#resource_full?}), the full representation will be retrieved before
+        # the update to comply with ETag-based optimistic concurrency control.
+        #
+        # @see https://cloud.google.com/bigquery/docs/customer-managed-encryption
+        #   Protecting Data with Cloud KMS Keys
+        #
+        # @param [EncryptionConfiguration] value The new encryption config.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"
+        #   encrypt_config = bigquery.encryption kms_key: key_name
+        #
+        #   dataset.default_encryption = encrypt_config
+        #
+        # @!group Attributes
+        #
+        def default_encryption= value
+          ensure_full_data!
+          @gapi.default_encryption_configuration = value.to_gapi
+          patch_gapi! :default_encryption_configuration
+        end
+
         ##
         # Retrieves the access rules for a Dataset. The rules can be updated
         # when passing a block, see {Dataset::Access} for all the methods
@@ -424,7 +501,7 @@ module Google
         # you can pass the table's schema as a hash (see example.)
         #
         # @param [String] table_id The ID of the table. The ID must contain only
-        #   letters (a-z, A-Z), numbers (0-9), or underscores (_). The maximum
+        #   letters (`[A-Za-z]`), numbers (`[0-9]`), or underscores (`_`). The maximum
         #   length is 1,024 characters.
         # @param [String] name A descriptive name for the table.
         # @param [String] description A user-friendly description of the table.
@@ -485,6 +562,40 @@ module Google
         #     end
         #   end
         #
+        # @example With time partitioning and clustering.
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   table = dataset.create_table "my_table" do |t|
+        #     t.schema do |schema|
+        #       schema.timestamp "dob", mode: :required
+        #       schema.string "first_name", mode: :required
+        #       schema.string "last_name", mode: :required
+        #     end
+        #     t.time_partitioning_type  = "DAY"
+        #     t.time_partitioning_field = "dob"
+        #     t.clustering_fields = ["last_name", "first_name"]
+        #   end
+        #
+        # @example With range partitioning.
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   table = dataset.create_table "my_table" do |t|
+        #     t.schema do |schema|
+        #       schema.integer "my_table_id", mode: :required
+        #       schema.string "my_table_data", mode: :required
+        #     end
+        #     t.range_partitioning_field = "my_table_id"
+        #     t.range_partitioning_start = 0
+        #     t.range_partitioning_interval = 10
+        #     t.range_partitioning_end = 100
+        #   end
+        #
         # @!group Table
         #
         def create_table table_id, name: nil, description: nil
@@ -507,17 +618,19 @@ module Google
         end
 
         ##
-        # Creates a new [view](https://cloud.google.com/bigquery/docs/views)
-        # table, which is a virtual table defined by the given SQL query.
+        # Creates a new view, which is a virtual table defined by the given SQL query.
         #
-        # BigQuery's views are logical views, not materialized views, which
-        # means that the query that defines the view is re-executed every time
-        # the view is queried. Queries are billed according to the total amount
+        # With BigQuery's logical views, the query that defines the view is re-executed
+        # every time the view is queried. Queries are billed according to the total amount
         # of data in all table fields referenced directly or indirectly by the
         # top-level query. (See {Table#view?} and {Table#query}.)
         #
+        # For materialized views, see {#create_materialized_view}.
+        #
+        # @see https://cloud.google.com/bigquery/docs/views Creating views
+        #
         # @param [String] table_id The ID of the view table. The ID must contain
-        #   only letters (a-z, A-Z), numbers (0-9), or underscores (_). The
+        #   only letters (`[A-Za-z]`), numbers (`[0-9]`), or underscores (`_`). The
         #   maximum length is 1,024 characters.
         # @param [String] query The query that BigQuery executes when the view
         #   is referenced.
@@ -532,12 +645,20 @@ module Google
         #   SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)
         #   dialect. Optional. The default value is false.
         # @param [Array<String>, String] udfs User-defined function resources
-        #   used in the query. May be either a code resource to load from a
-        #   Google Cloud Storage URI (`gs://bucket/path`), or an inline resource
+        #   used in a legacy SQL query. May be either a code resource to load from
+        #   a Google Cloud Storage URI (`gs://bucket/path`), or an inline resource
         #   that contains code for a user-defined function (UDF). Providing an
         #   inline code resource is equivalent to providing a URI for a file
-        #   containing the same code. See [User-Defined
-        #   Functions](https://cloud.google.com/bigquery/docs/reference/standard-sql/user-defined-functions).
+        #   containing the same code.
+        #
+        #   This parameter is used for defining User Defined Function (UDF)
+        #   resources only when using legacy SQL. Users of standard SQL should
+        #   leverage either DDL (e.g. `CREATE [TEMPORARY] FUNCTION ...`) or the
+        #   Routines API to define UDF resources.
+        #
+        #   For additional information on migrating, see: [Migrating to
+        #   standard SQL - Differences in user-defined JavaScript
+        #   functions](https://cloud.google.com/bigquery/docs/reference/standard-sql/migrating-from-legacy-sql#differences_in_user-defined_javascript_functions)
         #
         # @return [Google::Cloud::Bigquery::Table] A new table object.
         #
@@ -548,7 +669,7 @@ module Google
         #   dataset = bigquery.dataset "my_dataset"
         #
         #   view = dataset.create_view "my_view",
-        #             "SELECT name, age FROM proj.dataset.users"
+        #                              "SELECT name, age FROM proj.dataset.users"
         #
         # @example A name and description can be provided:
         #   require "google/cloud/bigquery"
@@ -557,13 +678,18 @@ module Google
         #   dataset = bigquery.dataset "my_dataset"
         #
         #   view = dataset.create_view "my_view",
-        #             "SELECT name, age FROM proj.dataset.users",
-        #             name: "My View", description: "This is my view"
+        #                              "SELECT name, age FROM proj.dataset.users",
+        #                              name: "My View", description: "This is my view"
         #
         # @!group Table
         #
-        def create_view table_id, query, name: nil, description: nil,
-                        standard_sql: nil, legacy_sql: nil, udfs: nil
+        def create_view table_id,
+                        query,
+                        name: nil,
+                        description: nil,
+                        standard_sql: nil,
+                        legacy_sql: nil,
+                        udfs: nil
           use_legacy_sql = Convert.resolve_legacy_sql standard_sql, legacy_sql
           new_view_opts = {
             table_reference: Google::Apis::BigqueryV2::TableReference.new(
@@ -579,7 +705,81 @@ module Google
               user_defined_function_resources: udfs_gapi(udfs)
             )
           }.delete_if { |_, v| v.nil? }
-          new_view = Google::Apis::BigqueryV2::Table.new new_view_opts
+          new_view = Google::Apis::BigqueryV2::Table.new(**new_view_opts)
+
+          gapi = service.insert_table dataset_id, new_view
+          Table.from_gapi gapi, service
+        end
+
+        ##
+        # Creates a new materialized view.
+        #
+        # Materialized views are precomputed views that periodically cache results of a query for increased performance
+        # and efficiency. BigQuery leverages precomputed results from materialized views and whenever possible reads
+        # only delta changes from the base table to compute up-to-date results.
+        #
+        # Queries that use materialized views are generally faster and consume less resources than queries that retrieve
+        # the same data only from the base table. Materialized views are helpful to significantly boost performance of
+        # workloads that have the characteristic of common and repeated queries.
+        #
+        # For logical views, see {#create_view}.
+        #
+        # @see https://cloud.google.com/bigquery/docs/materialized-views-intro Introduction to materialized views
+        #
+        # @param [String] table_id The ID of the materialized view table. The ID must contain only letters (`[A-Za-z]`),
+        #   numbers (`[0-9]`), or underscores (`_`). The maximum length is 1,024 characters.
+        # @param [String] query The query that BigQuery executes when the materialized view is referenced.
+        # @param [String] name A descriptive name for the table.
+        # @param [String] description A user-friendly description of the table.
+        # @param [Boolean] enable_refresh Enable automatic refresh of the materialized view when the base table is
+        #   updated. Optional. The default value is true.
+        # @param [Integer] refresh_interval_ms The maximum frequency in milliseconds at which this materialized view
+        #   will be refreshed. Optional. The default value is `1_800_000` (30 minutes).
+        #
+        # @return [Google::Cloud::Bigquery::Table] A new table object.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   materialized_view = dataset.create_materialized_view "my_materialized_view",
+        #                                                        "SELECT name, age FROM proj.dataset.users"
+        #
+        # @example Automatic refresh can be disabled:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   materialized_view = dataset.create_materialized_view "my_materialized_view",
+        #                                                        "SELECT name, age FROM proj.dataset.users",
+        #                                                        enable_refresh: false
+        #
+        # @!group Table
+        #
+        def create_materialized_view table_id,
+                                     query,
+                                     name: nil,
+                                     description: nil,
+                                     enable_refresh: nil,
+                                     refresh_interval_ms: nil
+          new_view_opts = {
+            table_reference:   Google::Apis::BigqueryV2::TableReference.new(
+              project_id: project_id,
+              dataset_id: dataset_id,
+              table_id:   table_id
+            ),
+            friendly_name:     name,
+            description:       description,
+            materialized_view: Google::Apis::BigqueryV2::MaterializedViewDefinition.new(
+              enable_refresh:      enable_refresh,
+              query:               query,
+              refresh_interval_ms: refresh_interval_ms
+            )
+          }.delete_if { |_, v| v.nil? }
+          new_view = Google::Apis::BigqueryV2::Table.new(**new_view_opts)
 
           gapi = service.insert_table dataset_id, new_view
           Table.from_gapi gapi, service
@@ -619,9 +819,7 @@ module Google
         #
         def table table_id, skip_lookup: nil
           ensure_service!
-          if skip_lookup
-            return Table.new_reference project_id, dataset_id, table_id, service
-          end
+          return Table.new_reference project_id, dataset_id, table_id, service if skip_lookup
           gapi = service.get_table dataset_id, table_id
           Table.from_gapi gapi, service
         rescue Google::Cloud::NotFoundError
@@ -664,8 +862,7 @@ module Google
         #
         def tables token: nil, max: nil
           ensure_service!
-          options = { token: token, max: max }
-          gapi = service.list_tables dataset_id, options
+          gapi = service.list_tables dataset_id, token: token, max: max
           Table::List.from_gapi gapi, service, dataset_id, max
         end
 
@@ -703,9 +900,7 @@ module Google
         #
         def model model_id, skip_lookup: nil
           ensure_service!
-          if skip_lookup
-            return Model.new_reference project_id, dataset_id, model_id, service
-          end
+          return Model.new_reference project_id, dataset_id, model_id, service if skip_lookup
           gapi = service.get_model dataset_id, model_id
           Model.from_gapi_json gapi, service
         rescue Google::Cloud::NotFoundError
@@ -752,6 +947,174 @@ module Google
           Model::List.from_gapi gapi, service, dataset_id, max
         end
 
+        ##
+        # Creates a new routine. The following attributes may be set in the yielded block:
+        # {Routine::Updater#routine_type=}, {Routine::Updater#language=}, {Routine::Updater#arguments=},
+        # {Routine::Updater#return_type=}, {Routine::Updater#imported_libraries=}, {Routine::Updater#body=}, and
+        # {Routine::Updater#description=}.
+        #
+        # @param [String] routine_id The ID of the routine. The ID must contain only
+        #   letters (`[A-Za-z]`), numbers (`[0-9]`), or underscores (`_`). The maximum length
+        #   is 256 characters.
+        # @yield [routine] A block for setting properties on the routine.
+        # @yieldparam [Google::Cloud::Bigquery::Routine::Updater] routine An updater to set additional properties on the
+        #   routine.
+        #
+        # @return [Google::Cloud::Bigquery::Routine] A new routine object.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   routine = dataset.create_routine "my_routine" do |r|
+        #     r.routine_type = "SCALAR_FUNCTION"
+        #     r.language = "SQL"
+        #     r.arguments = [
+        #       Google::Cloud::Bigquery::Argument.new(name: "x", data_type: "INT64")
+        #     ]
+        #     r.body = "x * 3"
+        #     r.description = "My routine description"
+        #   end
+        #
+        #   puts routine.routine_id
+        #
+        # @example Extended example:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   routine = dataset.create_routine "my_routine" do |r|
+        #     r.routine_type = "SCALAR_FUNCTION"
+        #     r.language = :SQL
+        #     r.body = "(SELECT SUM(IF(elem.name = \"foo\",elem.val,null)) FROM UNNEST(arr) AS elem)"
+        #     r.arguments = [
+        #       Google::Cloud::Bigquery::Argument.new(
+        #         name: "arr",
+        #         argument_kind: "FIXED_TYPE",
+        #         data_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #           type_kind: "ARRAY",
+        #           array_element_type: Google::Cloud::Bigquery::StandardSql::DataType.new(
+        #             type_kind: "STRUCT",
+        #             struct_type: Google::Cloud::Bigquery::StandardSql::StructType.new(
+        #               fields: [
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "name",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "STRING")
+        #                 ),
+        #                 Google::Cloud::Bigquery::StandardSql::Field.new(
+        #                   name: "val",
+        #                   type: Google::Cloud::Bigquery::StandardSql::DataType.new(type_kind: "INT64")
+        #                 )
+        #               ]
+        #             )
+        #           )
+        #         )
+        #       )
+        #     ]
+        #   end
+        #
+        # @!group Routine
+        #
+        def create_routine routine_id
+          ensure_service!
+          new_tb = Google::Apis::BigqueryV2::Routine.new(
+            routine_reference: Google::Apis::BigqueryV2::RoutineReference.new(
+              project_id: project_id, dataset_id: dataset_id, routine_id: routine_id
+            )
+          )
+          updater = Routine::Updater.new new_tb
+
+          yield updater if block_given?
+
+          gapi = service.insert_routine dataset_id, updater.to_gapi
+          Routine.from_gapi gapi, service
+        end
+
+        ##
+        # Retrieves an existing routine by ID.
+        #
+        # @param [String] routine_id The ID of a routine.
+        # @param [Boolean] skip_lookup Optionally create just a local reference
+        #   object without verifying that the resource exists on the BigQuery
+        #   service. Calls made on this object will raise errors if the resource
+        #   does not exist. Default is `false`. Optional.
+        #
+        # @return [Google::Cloud::Bigquery::Routine, nil] Returns `nil` if the
+        #   routine does not exist.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   routine = dataset.routine "my_routine"
+        #   puts routine.routine_id
+        #
+        # @example Avoid retrieving the routine resource with `skip_lookup`:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   routine = dataset.routine "my_routine", skip_lookup: true
+        #
+        # @!group Routine
+        #
+        def routine routine_id, skip_lookup: nil
+          ensure_service!
+          return Routine.new_reference project_id, dataset_id, routine_id, service if skip_lookup
+          gapi = service.get_routine dataset_id, routine_id
+          Routine.from_gapi gapi, service
+        rescue Google::Cloud::NotFoundError
+          nil
+        end
+
+        ##
+        # Retrieves the list of routines belonging to the dataset.
+        #
+        # @param [String] token A previously-returned page token representing
+        #   part of the larger set of results to view.
+        # @param [Integer] max Maximum number of routines to return.
+        # @param [String] filter If set, then only the routines matching this filter are returned. The current supported
+        #   form is `routineType:`, with a {Routine#routine_type} enum value. Example: `routineType:SCALAR_FUNCTION`.
+        #
+        # @return [Array<Google::Cloud::Bigquery::Routine>] An array of routines
+        #   (See {Google::Cloud::Bigquery::Routine::List})
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   routines = dataset.routines
+        #   routines.each do |routine|
+        #     puts routine.routine_id
+        #   end
+        #
+        # @example Retrieve all routines: (See {Routine::List#all})
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   routines = dataset.routines
+        #   routines.all do |routine|
+        #     puts routine.routine_id
+        #   end
+        #
+        # @!group Routine
+        #
+        def routines token: nil, max: nil, filter: nil
+          ensure_service!
+          gapi = service.list_routines dataset_id, token: token, max: max, filter: filter
+          Routine::List.from_gapi gapi, service, dataset_id, max, filter: filter
+        end
+
         ##
         # Queries data by creating a [query
         # job](https://cloud.google.com/bigquery/docs/query-overview#query_jobs).
@@ -759,27 +1122,6 @@ module Google
         # Sets the current dataset as the default dataset in the query. Useful
         # for using unqualified table names.
         #
-        # When using standard SQL and passing arguments using `params`, Ruby
-        # types are mapped to BigQuery types as follows:
-        #
-        # | BigQuery    | Ruby           | Notes  |
-        # |-------------|----------------|---|
-        # | `BOOL`      | `true`/`false` | |
-        # | `INT64`     | `Integer`      | |
-        # | `FLOAT64`   | `Float`        | |
-        # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
-        # | `STRING`    | `String`       | |
-        # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
-        # | `DATE`      | `Date`         | |
-        # | `TIMESTAMP` | `Time`         | |
-        # | `TIME`      | `Google::Cloud::BigQuery::Time` | |
-        # | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
-        # | `ARRAY` | `Array` | Nested arrays, `nil` values are not supported. |
-        # | `STRUCT`    | `Hash`        | Hash keys may be strings or symbols. |
-        #
-        # See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)
-        # for an overview of each BigQuery data type, including allowed values.
-        #
         # The geographic location for the job ("US", "EU", etc.) can be set via
         # {QueryJob::Updater#location=} in a block passed to this method. If the
         # dataset is a full resource representation (see {#resource_full?}), the
@@ -790,13 +1132,60 @@ module Google
         #   syntax](https://cloud.google.com/bigquery/query-reference), of the
         #   query to execute. Example: "SELECT count(f1) FROM
         #   [myProjectId:myDatasetId.myTableId]".
-        # @param [Array, Hash] params Standard SQL only. Used to pass query
-        #   arguments when the `query` string contains either positional (`?`)
-        #   or named (`@myparam`) query parameters. If value passed is an array
-        #   `["foo"]`, the query must use positional query parameters. If value
-        #   passed is a hash `{ myparam: "foo" }`, the query must use named
-        #   query parameters. When set, `legacy_sql` will automatically be set
-        #   to false and `standard_sql` to true.
+        # @param [Array, Hash] params Standard SQL only. Used to pass query arguments when the `query` string contains
+        #   either positional (`?`) or named (`@myparam`) query parameters. If value passed is an array `["foo"]`, the
+        #   query must use positional query parameters. If value passed is a hash `{ myparam: "foo" }`, the query must
+        #   use named query parameters. When set, `legacy_sql` will automatically be set to false and `standard_sql` to
+        #   true.
+        #
+        #   BigQuery types are converted from Ruby types as follows:
+        #
+        #   | BigQuery     | Ruby                                 | Notes                                              |
+        #   |--------------|--------------------------------------|----------------------------------------------------|
+        #   | `BOOL`       | `true`/`false`                       |                                                    |
+        #   | `INT64`      | `Integer`                            |                                                    |
+        #   | `FLOAT64`    | `Float`                              |                                                    |
+        #   | `NUMERIC`    | `BigDecimal`                         | `BigDecimal` values will be rounded to scale 9.    |
+        #   | `BIGNUMERIC` | `BigDecimal`                         | NOT AUTOMATIC: Must be mapped using `types`, below.|
+        #   | `STRING`     | `String`                             |                                                    |
+        #   | `DATETIME`   | `DateTime`                           | `DATETIME` does not support time zone.             |
+        #   | `DATE`       | `Date`                               |                                                    |
+        #   | `GEOGRAPHY`  | `String` (WKT or GeoJSON)            | NOT AUTOMATIC: Must be mapped using `types`, below.|
+        #   | `TIMESTAMP`  | `Time`                               |                                                    |
+        #   | `TIME`       | `Google::Cloud::BigQuery::Time`      |                                                    |
+        #   | `BYTES`      | `File`, `IO`, `StringIO`, or similar |                                                    |
+        #   | `ARRAY`      | `Array`                              | Nested arrays, `nil` values are not supported.     |
+        #   | `STRUCT`     | `Hash`                               | Hash keys may be strings or symbols.               |
+        #
+        #   See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types) for an overview
+        #   of each BigQuery data type, including allowed values. For the `GEOGRAPHY` type, see [Working with BigQuery
+        #   GIS data](https://cloud.google.com/bigquery/docs/gis-data).
+        # @param [Array, Hash] types Standard SQL only. Types of the SQL parameters in `params`. It is not always
+        #   possible to infer the right SQL type from a value in `params`. In these cases, `types` must be used to
+        #   specify the SQL type for these values.
+        #
+        #   Arguments must match the value type passed to `params`. This must be an `Array` when the query uses
+        #   positional query parameters. This must be an `Hash` when the query uses named query parameters. The values
+        #   should be BigQuery type codes from the following list:
+        #
+        #   * `:BOOL`
+        #   * `:INT64`
+        #   * `:FLOAT64`
+        #   * `:NUMERIC`
+        #   * `:BIGNUMERIC`
+        #   * `:STRING`
+        #   * `:DATETIME`
+        #   * `:DATE`
+        #   * `:GEOGRAPHY`
+        #   * `:TIMESTAMP`
+        #   * `:TIME`
+        #   * `:BYTES`
+        #   * `Array` - Lists are specified by providing the type code in an array. For example, an array of integers
+        #     are specified as `[:INT64]`.
+        #   * `Hash` - Types for STRUCT values (`Hash` objects) are specified using a `Hash` object, where the keys
+        #     match the `params` hash, and the values are the types value that matches the data.
+        #
+        #   Types are optional.
         # @param [Hash<String|Symbol, External::DataSource>] external A Hash
         #   that represents the mapping of the external tables to the table
         #   names used in the SQL query. The hash keys are the table names, and
@@ -855,13 +1244,19 @@ module Google
         #   Flattens all nested and repeated fields in the query results. The
         #   default value is `true`. `large_results` parameter must be `true` if
         #   this is set to `false`.
+        # @param [Integer] maximum_billing_tier Limits the billing tier for this
+        #   job. Queries that have resource usage beyond this tier will fail
+        #   (without incurring a charge). WARNING: The billed byte amount can be
+        #   multiplied by an amount up to this number! Most users should not need
+        #   to alter this setting, and we recommend that you avoid introducing new
+        #   uses of it. Deprecated.
         # @param [Integer] maximum_bytes_billed Limits the bytes billed for this
         #   job. Queries that will have bytes billed beyond this limit will fail
         #   (without incurring a charge). Optional. If unspecified, this will be
         #   set to your project default.
         # @param [String] job_id A user-defined ID for the query job. The ID
-        #   must contain only letters (a-z, A-Z), numbers (0-9), underscores
-        #   (_), or dashes (-). The maximum length is 1,024 characters. If
+        #   must contain only letters (`[A-Za-z]`), numbers (`[0-9]`), underscores
+        #   (`_`), or dashes (`-`). The maximum length is 1,024 characters. If
         #   `job_id` is provided, then `prefix` will not be used.
         #
         #   See [Generating a job
@@ -870,27 +1265,48 @@ module Google
         #   prepended to a generated value to produce a unique job ID. For
         #   example, the prefix `daily_import_job_` can be given to generate a
         #   job ID such as `daily_import_job_12vEDtMQ0mbp1Mo5Z7mzAFQJZazh`. The
-        #   prefix must contain only letters (a-z, A-Z), numbers (0-9),
-        #   underscores (_), or dashes (-). The maximum length of the entire ID
+        #   prefix must contain only letters (`[A-Za-z]`), numbers (`[0-9]`),
+        #   underscores (`_`), or dashes (`-`). The maximum length of the entire ID
         #   is 1,024 characters. If `job_id` is provided, then `prefix` will not
         #   be used.
         # @param [Hash] labels A hash of user-provided labels associated with
-        #   the job. You can use these to organize and group your jobs. Label
-        #   keys and values can be no longer than 63 characters, can only
-        #   contain lowercase letters, numeric characters, underscores and
-        #   dashes. International characters are allowed. Label values are
-        #   optional. Label keys must start with a letter and each label in the
-        #   list must have a different key. See [Requirements for
-        #   labels](https://cloud.google.com/bigquery/docs/creating-managing-labels#requirements).
+        #   the job. You can use these to organize and group your jobs.
+        #
+        #   The labels applied to a resource must meet the following requirements:
+        #
+        #   * Each resource can have multiple labels, up to a maximum of 64.
+        #   * Each label must be a key-value pair.
+        #   * Keys have a minimum length of 1 character and a maximum length of
+        #     63 characters, and cannot be empty. Values can be empty, and have
+        #     a maximum length of 63 characters.
+        #   * Keys and values can contain only lowercase letters, numeric characters,
+        #     underscores, and dashes. All characters must use UTF-8 encoding, and
+        #     international characters are allowed.
+        #   * The key portion of a label must be unique. However, you can use the
+        #     same key with multiple resources.
+        #   * Keys must start with a lowercase letter or international character.
         # @param [Array<String>, String] udfs User-defined function resources
-        #   used in the query. May be either a code resource to load from a
-        #   Google Cloud Storage URI (`gs://bucket/path`), or an inline resource
+        #   used in a legacy SQL query. May be either a code resource to load from
+        #   a Google Cloud Storage URI (`gs://bucket/path`), or an inline resource
         #   that contains code for a user-defined function (UDF). Providing an
         #   inline code resource is equivalent to providing a URI for a file
-        #   containing the same code. See [User-Defined
-        #   Functions](https://cloud.google.com/bigquery/docs/reference/standard-sql/user-defined-functions).
-        # @param [Integer] maximum_billing_tier Deprecated: Change the billing
-        #   tier to allow high-compute queries.
+        #   containing the same code.
+        #
+        #   This parameter is used for defining User Defined Function (UDF)
+        #   resources only when using legacy SQL. Users of standard SQL should
+        #   leverage either DDL (e.g. `CREATE [TEMPORARY] FUNCTION ...`) or the
+        #   Routines API to define UDF resources.
+        #
+        #   For additional information on migrating, see: [Migrating to
+        #   standard SQL - Differences in user-defined JavaScript
+        #   functions](https://cloud.google.com/bigquery/docs/reference/standard-sql/migrating-from-legacy-sql#differences_in_user-defined_javascript_functions)
+        # @param [Boolean] create_session If true, creates a new session, where the
+        #   session ID will be a server generated random id. If false, runs query
+        #   with an existing session ID when one is provided in the `session_id`
+        #   param, otherwise runs query in non-session mode. See {Job#session_id}.
+        #   The default value is false.
+        # @param [String] session_id The ID of an existing session. See also the
+        #   `create_session` param and {Job#session_id}.
         # @yield [job] a job configuration object
         # @yieldparam [Google::Cloud::Bigquery::QueryJob::Updater] job a job
         #   configuration object for setting additional options for the query.
@@ -960,32 +1376,62 @@ module Google
         #     end
         #   end
         #
+        # @example Query using named query parameters with types:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   job = dataset.query_job "SELECT name FROM my_table WHERE id IN UNNEST(@ids)",
+        #                           params: { ids: [] },
+        #                           types: { ids: [:INT64] }
+        #
+        #   job.wait_until_done!
+        #   if !job.failed?
+        #     job.data.each do |row|
+        #       puts row[:name]
+        #     end
+        #   end
+        #
         # @example Execute a DDL statement:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   job = bigquery.query_job "CREATE TABLE my_table (x INT64)"
+        #   job = dataset.query_job "CREATE TABLE my_table (x INT64)"
         #
         #   job.wait_until_done!
         #   if !job.failed?
-        #     table_ref = job.ddl_target_table
+        #     table_ref = job.ddl_target_table # Or ddl_target_routine for CREATE/DROP FUNCTION/PROCEDURE
         #   end
         #
         # @example Execute a DML statement:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   job = bigquery.query_job "UPDATE my_table " \
-        #                            "SET x = x + 1 " \
-        #                            "WHERE x IS NOT NULL"
+        #   job = dataset.query_job "UPDATE my_table SET x = x + 1 WHERE x IS NOT NULL"
         #
         #   job.wait_until_done!
         #   if !job.failed?
         #     puts job.num_dml_affected_rows
         #   end
         #
+        # @example Run query in a session:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   job = dataset.query_job "CREATE TEMPORARY TABLE temptable AS SELECT 17 as foo", create_session: true
+        #
+        #   job.wait_until_done!
+        #
+        #   session_id = job.session_id
+        #   data = dataset.query "SELECT * FROM temptable", session_id: session_id
+        #
         # @example Query using external data source, set destination:
         #   require "google/cloud/bigquery"
         #
@@ -1012,21 +1458,52 @@ module Google
         #
         # @!group Data
         #
-        def query_job query, params: nil, external: nil,
-                      priority: "INTERACTIVE", cache: true, table: nil,
-                      create: nil, write: nil, dryrun: nil, standard_sql: nil,
-                      legacy_sql: nil, large_results: nil, flatten: nil,
-                      maximum_billing_tier: nil, maximum_bytes_billed: nil,
-                      job_id: nil, prefix: nil, labels: nil, udfs: nil
+        def query_job query,
+                      params: nil,
+                      types: nil,
+                      external: nil,
+                      priority: "INTERACTIVE",
+                      cache: true,
+                      table: nil,
+                      create: nil,
+                      write: nil,
+                      dryrun: nil,
+                      standard_sql: nil,
+                      legacy_sql: nil,
+                      large_results: nil,
+                      flatten: nil,
+                      maximum_billing_tier: nil,
+                      maximum_bytes_billed: nil,
+                      job_id: nil,
+                      prefix: nil,
+                      labels: nil,
+                      udfs: nil,
+                      create_session: nil,
+                      session_id: nil
           ensure_service!
-          options = { priority: priority, cache: cache, table: table,
-                      create: create, write: write, dryrun: dryrun,
-                      large_results: large_results, flatten: flatten,
-                      legacy_sql: legacy_sql, standard_sql: standard_sql,
-                      maximum_billing_tier: maximum_billing_tier,
-                      maximum_bytes_billed: maximum_bytes_billed,
-                      job_id: job_id, prefix: prefix, params: params,
-                      external: external, labels: labels, udfs: udfs }
+          options = {
+            params: params,
+            types: types,
+            external: external,
+            priority: priority,
+            cache: cache,
+            table: table,
+            create: create,
+            write: write,
+            dryrun: dryrun,
+            standard_sql: standard_sql,
+            legacy_sql: legacy_sql,
+            large_results: large_results,
+            flatten: flatten,
+            maximum_billing_tier: maximum_billing_tier,
+            maximum_bytes_billed: maximum_bytes_billed,
+            job_id: job_id,
+            prefix: prefix,
+            labels: labels,
+            udfs: udfs,
+            create_session: create_session,
+            session_id: session_id
+          }
 
           updater = QueryJob::Updater.from_options service, query, options
           updater.dataset = self
@@ -1048,27 +1525,6 @@ module Google
         # Sets the current dataset as the default dataset in the query. Useful
         # for using unqualified table names.
         #
-        # When using standard SQL and passing arguments using `params`, Ruby
-        # types are mapped to BigQuery types as follows:
-        #
-        # | BigQuery    | Ruby           | Notes  |
-        # |-------------|----------------|---|
-        # | `BOOL`      | `true`/`false` | |
-        # | `INT64`     | `Integer`      | |
-        # | `FLOAT64`   | `Float`        | |
-        # | `NUMERIC`   | `BigDecimal`   | Will be rounded to 9 decimal places |
-        # | `STRING`    | `String`       | |
-        # | `DATETIME`  | `DateTime`  | `DATETIME` does not support time zone. |
-        # | `DATE`      | `Date`         | |
-        # | `TIMESTAMP` | `Time`         | |
-        # | `TIME`      | `Google::Cloud::BigQuery::Time` | |
-        # | `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
-        # | `ARRAY` | `Array` | Nested arrays, `nil` values are not supported. |
-        # | `STRUCT`    | `Hash`        | Hash keys may be strings or symbols. |
-        #
-        # See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types)
-        # for an overview of each BigQuery data type, including allowed values.
-        #
         # The geographic location for the job ("US", "EU", etc.) can be set via
         # {QueryJob::Updater#location=} in a block passed to this method. If the
         # dataset is a full resource representation (see {#resource_full?}), the
@@ -1081,13 +1537,60 @@ module Google
         #   syntax](https://cloud.google.com/bigquery/query-reference), of the
         #   query to execute. Example: "SELECT count(f1) FROM
         #   [myProjectId:myDatasetId.myTableId]".
-        # @param [Array, Hash] params Standard SQL only. Used to pass query
-        #   arguments when the `query` string contains either positional (`?`)
-        #   or named (`@myparam`) query parameters. If value passed is an array
-        #   `["foo"]`, the query must use positional query parameters. If value
-        #   passed is a hash `{ myparam: "foo" }`, the query must use named
-        #   query parameters. When set, `legacy_sql` will automatically be set
-        #   to false and `standard_sql` to true.
+        # @param [Array, Hash] params Standard SQL only. Used to pass query arguments when the `query` string contains
+        #   either positional (`?`) or named (`@myparam`) query parameters. If value passed is an array `["foo"]`, the
+        #   query must use positional query parameters. If value passed is a hash `{ myparam: "foo" }`, the query must
+        #   use named query parameters. When set, `legacy_sql` will automatically be set to false and `standard_sql` to
+        #   true.
+        #
+        #   BigQuery types are converted from Ruby types as follows:
+        #
+        #   | BigQuery     | Ruby                                 | Notes                                              |
+        #   |--------------|--------------------------------------|----------------------------------------------------|
+        #   | `BOOL`       | `true`/`false`                       |                                                    |
+        #   | `INT64`      | `Integer`                            |                                                    |
+        #   | `FLOAT64`    | `Float`                              |                                                    |
+        #   | `NUMERIC`    | `BigDecimal`                         | `BigDecimal` values will be rounded to scale 9.    |
+        #   | `BIGNUMERIC` | `BigDecimal`                         | NOT AUTOMATIC: Must be mapped using `types`, below.|
+        #   | `STRING`     | `String`                             |                                                    |
+        #   | `DATETIME`   | `DateTime`                           | `DATETIME` does not support time zone.             |
+        #   | `DATE`       | `Date`                               |                                                    |
+        #   | `GEOGRAPHY`  | `String` (WKT or GeoJSON)            | NOT AUTOMATIC: Must be mapped using `types`, below.|
+        #   | `TIMESTAMP`  | `Time`                               |                                                    |
+        #   | `TIME`       | `Google::Cloud::BigQuery::Time`      |                                                    |
+        #   | `BYTES`      | `File`, `IO`, `StringIO`, or similar |                                                    |
+        #   | `ARRAY`      | `Array`                              | Nested arrays, `nil` values are not supported.     |
+        #   | `STRUCT`     | `Hash`                               | Hash keys may be strings or symbols.               |
+        #
+        #   See [Data Types](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types) for an overview
+        #   of each BigQuery data type, including allowed values. For the `GEOGRAPHY` type, see [Working with BigQuery
+        #   GIS data](https://cloud.google.com/bigquery/docs/gis-data).
+        # @param [Array, Hash] types Standard SQL only. Types of the SQL parameters in `params`. It is not always
+        #   possible to infer the right SQL type from a value in `params`. In these cases, `types` must be used to
+        #   specify the SQL type for these values.
+        #
+        #   Arguments must match the value type passed to `params`. This must be an `Array` when the query uses
+        #   positional query parameters. This must be an `Hash` when the query uses named query parameters. The values
+        #   should be BigQuery type codes from the following list:
+        #
+        #   * `:BOOL`
+        #   * `:INT64`
+        #   * `:FLOAT64`
+        #   * `:NUMERIC`
+        #   * `:BIGNUMERIC`
+        #   * `:STRING`
+        #   * `:DATETIME`
+        #   * `:DATE`
+        #   * `:GEOGRAPHY`
+        #   * `:TIMESTAMP`
+        #   * `:TIME`
+        #   * `:BYTES`
+        #   * `Array` - Lists are specified by providing the type code in an array. For example, an array of integers
+        #     are specified as `[:INT64]`.
+        #   * `Hash` - Types for STRUCT values (`Hash` objects) are specified using a `Hash` object, where the keys
+        #     match the `params` hash, and the values are the types value that matches the data.
+        #
+        #   Types are optional.
         # @param [Hash<String|Symbol, External::DataSource>] external A Hash
         #   that represents the mapping of the external tables to the table
         #   names used in the SQL query. The hash keys are the table names, and
@@ -1122,6 +1625,8 @@ module Google
         #   When set to false, the values of `large_results` and `flatten` are
         #   ignored; the query will be run as if `large_results` is true and
         #   `flatten` is false. Optional. The default value is false.
+        # @param [String] session_id The ID of an existing session. See the
+        #   `create_session` param in {#query_job} and {Job#session_id}.
         # @yield [job] a job configuration object
         # @yieldparam [Google::Cloud::Bigquery::QueryJob::Updater] job a job
         #   configuration object for setting additional options for the query.
@@ -1136,9 +1641,12 @@ module Google
         #
         #   data = dataset.query "SELECT name FROM my_table"
         #
+        #   # Iterate over the first page of results
         #   data.each do |row|
         #     puts row[:name]
         #   end
+        #   # Retrieve the next page of results
+        #   data = data.next if data.next?
         #
         # @example Query using legacy SQL:
         #   require "google/cloud/bigquery"
@@ -1149,9 +1657,12 @@ module Google
         #   data = dataset.query "SELECT name FROM my_table",
         #                        legacy_sql: true
         #
+        #   # Iterate over the first page of results
         #   data.each do |row|
         #     puts row[:name]
         #   end
+        #   # Retrieve the next page of results
+        #   data = data.next if data.next?
         #
         # @example Query using positional query parameters:
         #   require "google/cloud/bigquery"
@@ -1162,9 +1673,12 @@ module Google
         #   data = dataset.query "SELECT name FROM my_table WHERE id = ?",
         #                        params: [1]
         #
+        #   # Iterate over the first page of results
         #   data.each do |row|
         #     puts row[:name]
         #   end
+        #   # Retrieve the next page of results
+        #   data = data.next if data.next?
         #
         # @example Query using named query parameters:
         #   require "google/cloud/bigquery"
@@ -1175,30 +1689,63 @@ module Google
         #   data = dataset.query "SELECT name FROM my_table WHERE id = @id",
         #                        params: { id: 1 }
         #
+        #   # Iterate over the first page of results
+        #   data.each do |row|
+        #     puts row[:name]
+        #   end
+        #   # Retrieve the next page of results
+        #   data = data.next if data.next?
+        #
+        # @example Query using named query parameters with types:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   data = dataset.query "SELECT name FROM my_table WHERE id IN UNNEST(@ids)",
+        #                        params: { ids: [] },
+        #                        types: { ids: [:INT64] }
+        #
+        #   # Iterate over the first page of results
         #   data.each do |row|
         #     puts row[:name]
         #   end
+        #   # Retrieve the next page of results
+        #   data = data.next if data.next?
         #
         # @example Execute a DDL statement:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   data = bigquery.query "CREATE TABLE my_table (x INT64)"
+        #   data = dataset.query "CREATE TABLE my_table (x INT64)"
         #
-        #   table_ref = data.ddl_target_table
+        #   table_ref = data.ddl_target_table # Or ddl_target_routine for CREATE/DROP FUNCTION/PROCEDURE
         #
         # @example Execute a DML statement:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
         #
-        #   data = bigquery.query "UPDATE my_table " \
-        #                         "SET x = x + 1 " \
-        #                         "WHERE x IS NOT NULL"
+        #   data = dataset.query "UPDATE my_table SET x = x + 1 WHERE x IS NOT NULL"
         #
         #   puts data.num_dml_affected_rows
         #
+        # @example Run query in a session:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   job = dataset.query_job "CREATE TEMPORARY TABLE temptable AS SELECT 17 as foo", create_session: true
+        #
+        #   job.wait_until_done!
+        #
+        #   session_id = job.session_id
+        #   data = dataset.query "SELECT * FROM temptable", session_id: session_id
+        #
         # @example Query using external data source, set destination:
         #   require "google/cloud/bigquery"
         #
@@ -1216,17 +1763,34 @@ module Google
         #     query.table = dataset.table "my_table", skip_lookup: true
         #   end
         #
+        #   # Iterate over the first page of results
         #   data.each do |row|
         #     puts row[:name]
         #   end
+        #   # Retrieve the next page of results
+        #   data = data.next if data.next?
         #
         # @!group Data
         #
-        def query query, params: nil, external: nil, max: nil, cache: true,
-                  standard_sql: nil, legacy_sql: nil, &block
-          job = query_job query, params: params, external: external,
-                                 cache: cache, standard_sql: standard_sql,
-                                 legacy_sql: legacy_sql, &block
+        def query query,
+                  params: nil,
+                  types: nil,
+                  external: nil,
+                  max: nil,
+                  cache: true,
+                  standard_sql: nil,
+                  legacy_sql: nil,
+                  session_id: nil,
+                  &block
+          job = query_job query,
+                          params: params,
+                          types: types,
+                          external: external,
+                          cache: cache,
+                          standard_sql: standard_sql,
+                          legacy_sql: legacy_sql,
+                          session_id: session_id,
+                          &block
           job.wait_until_done!
           ensure_job_succeeded! job
 
@@ -1407,8 +1971,8 @@ module Google
         #   this option. Also note that for most use cases, the block yielded by
         #   this method is a more convenient way to configure the schema.
         # @param [String] job_id A user-defined ID for the load job. The ID
-        #   must contain only letters (a-z, A-Z), numbers (0-9), underscores
-        #   (_), or dashes (-). The maximum length is 1,024 characters. If
+        #   must contain only letters (`[A-Za-z]`), numbers (`[0-9]`), underscores
+        #   (`_`), or dashes (`-`). The maximum length is 1,024 characters. If
         #   `job_id` is provided, then `prefix` will not be used.
         #
         #   See [Generating a job
@@ -1417,18 +1981,26 @@ module Google
         #   prepended to a generated value to produce a unique job ID. For
         #   example, the prefix `daily_import_job_` can be given to generate a
         #   job ID such as `daily_import_job_12vEDtMQ0mbp1Mo5Z7mzAFQJZazh`. The
-        #   prefix must contain only letters (a-z, A-Z), numbers (0-9),
-        #   underscores (_), or dashes (-). The maximum length of the entire ID
+        #   prefix must contain only letters (`[A-Za-z]`), numbers (`[0-9]`),
+        #   underscores (`_`), or dashes (`-`). The maximum length of the entire ID
         #   is 1,024 characters. If `job_id` is provided, then `prefix` will not
         #   be used.
         # @param [Hash] labels A hash of user-provided labels associated with
-        #   the job. You can use these to organize and group your jobs. Label
-        #   keys and values can be no longer than 63 characters, can only
-        #   contain lowercase letters, numeric characters, underscores and
-        #   dashes. International characters are allowed. Label values are
-        #   optional. Label keys must start with a letter and each label in the
-        #   list must have a different key. See [Requirements for
-        #   labels](https://cloud.google.com/bigquery/docs/creating-managing-labels#requirements).
+        #   the job. You can use these to organize and group your jobs.
+        #
+        #   The labels applied to a resource must meet the following requirements:
+        #
+        #   * Each resource can have multiple labels, up to a maximum of 64.
+        #   * Each label must be a key-value pair.
+        #   * Keys have a minimum length of 1 character and a maximum length of
+        #     63 characters, and cannot be empty. Values can be empty, and have
+        #     a maximum length of 63 characters.
+        #   * Keys and values can contain only lowercase letters, numeric characters,
+        #     underscores, and dashes. All characters must use UTF-8 encoding, and
+        #     international characters are allowed.
+        #   * The key portion of a label must be unique. However, you can use the
+        #     same key with multiple resources.
+        #   * Keys must start with a lowercase letter or international character.
         # @yield [updater] A block for setting the schema and other
         #   options for the destination table. The schema can be omitted if the
         #   destination table already exists, or if you're loading data from a
@@ -1522,29 +2094,19 @@ module Google
         #
         # @!group Data
         #
-        def load_job table_id, files, format: nil, create: nil, write: nil,
-                     projection_fields: nil, jagged_rows: nil,
-                     quoted_newlines: nil, encoding: nil, delimiter: nil,
-                     ignore_unknown: nil, max_bad_records: nil, quote: nil,
-                     skip_leading: nil, schema: nil, job_id: nil, prefix: nil,
-                     labels: nil, autodetect: nil, null_marker: nil, dryrun: nil
+        def load_job table_id, files, format: nil, create: nil, write: nil, projection_fields: nil, jagged_rows: nil,
+                     quoted_newlines: nil, encoding: nil, delimiter: nil, ignore_unknown: nil, max_bad_records: nil,
+                     quote: nil, skip_leading: nil, schema: nil, job_id: nil, prefix: nil, labels: nil, autodetect: nil,
+                     null_marker: nil, dryrun: nil
           ensure_service!
 
           updater = load_job_updater table_id,
-                                     format: format, create: create,
-                                     write: write,
-                                     projection_fields: projection_fields,
-                                     jagged_rows: jagged_rows,
-                                     quoted_newlines: quoted_newlines,
-                                     encoding: encoding,
-                                     delimiter: delimiter,
-                                     ignore_unknown: ignore_unknown,
-                                     max_bad_records: max_bad_records,
-                                     quote: quote, skip_leading: skip_leading,
-                                     dryrun: dryrun, schema: schema,
-                                     job_id: job_id, prefix: prefix,
-                                     labels: labels, autodetect: autodetect,
-                                     null_marker: null_marker
+                                     format: format, create: create, write: write, projection_fields: projection_fields,
+                                     jagged_rows: jagged_rows, quoted_newlines: quoted_newlines, encoding: encoding,
+                                     delimiter: delimiter, ignore_unknown: ignore_unknown,
+                                     max_bad_records: max_bad_records, quote: quote, skip_leading: skip_leading,
+                                     dryrun: dryrun, schema: schema, job_id: job_id, prefix: prefix, labels: labels,
+                                     autodetect: autodetect, null_marker: null_marker
 
           yield updater if block_given?
 
@@ -1760,21 +2322,14 @@ module Google
         #
         # @!group Data
         #
-        def load table_id, files, format: nil, create: nil, write: nil,
-                 projection_fields: nil, jagged_rows: nil, quoted_newlines: nil,
-                 encoding: nil, delimiter: nil, ignore_unknown: nil,
-                 max_bad_records: nil, quote: nil, skip_leading: nil,
-                 schema: nil, autodetect: nil, null_marker: nil, &block
+        def load table_id, files, format: nil, create: nil, write: nil, projection_fields: nil, jagged_rows: nil,
+                 quoted_newlines: nil, encoding: nil, delimiter: nil, ignore_unknown: nil, max_bad_records: nil,
+                 quote: nil, skip_leading: nil, schema: nil, autodetect: nil, null_marker: nil, &block
           job = load_job table_id, files,
-                         format: format, create: create, write: write,
-                         projection_fields: projection_fields,
-                         jagged_rows: jagged_rows,
-                         quoted_newlines: quoted_newlines,
-                         encoding: encoding, delimiter: delimiter,
-                         ignore_unknown: ignore_unknown,
-                         max_bad_records: max_bad_records,
-                         quote: quote, skip_leading: skip_leading,
-                         schema: schema, autodetect: autodetect,
+                         format: format, create: create, write: write, projection_fields: projection_fields,
+                         jagged_rows: jagged_rows, quoted_newlines: quoted_newlines, encoding: encoding,
+                         delimiter: delimiter, ignore_unknown: ignore_unknown, max_bad_records: max_bad_records,
+                         quote: quote, skip_leading: skip_leading, schema: schema, autodetect: autodetect,
                          null_marker: null_marker, &block
 
           job.wait_until_done!
@@ -1825,7 +2380,7 @@ module Google
         #   dataset = bigquery.dataset "my_dataset", skip_lookup: true
         #   dataset.exists? # true
         #
-        def exists? force: nil
+        def exists? force: false
           return gapi_exists? if force
           # If we have a memoized value, return it
           return @exists unless @exists.nil?
@@ -1935,14 +2490,12 @@ module Google
         end
 
         ##
-        # @private New lazy Dataset object without making an HTTP request.
+        # @private New lazy Dataset object without making an HTTP request, for use with the skip_lookup option.
         def self.new_reference project_id, dataset_id, service
           raise ArgumentError, "dataset_id is required" unless dataset_id
           new.tap do |b|
-            reference_gapi = Google::Apis::BigqueryV2::DatasetReference.new(
-              project_id: project_id,
-              dataset_id: dataset_id
-            )
+            reference_gapi = Google::Apis::BigqueryV2::DatasetReference.new \
+              project_id: project_id, dataset_id: dataset_id
             b.service = service
             b.instance_variable_set :@reference, reference_gapi
           end
@@ -1953,18 +2506,47 @@ module Google
         # the need to complete a load operation before the data can appear in
         # query results.
         #
+        # Simple Ruby types are generally accepted per JSON rules, along with the following support for BigQuery's more
+        # complex types:
+        #
+        # | BigQuery     | Ruby                                 | Notes                                              |
+        # |--------------|--------------------------------------|----------------------------------------------------|
+        # | `NUMERIC`    | `BigDecimal`                         | `BigDecimal` values will be rounded to scale 9.    |
+        # | `BIGNUMERIC` | `String`                             | Pass as `String` to avoid rounding to scale 9.     |
+        # | `DATETIME`   | `DateTime`                           | `DATETIME` does not support time zone.             |
+        # | `DATE`       | `Date`                               |                                                    |
+        # | `GEOGRAPHY`  | `String`                             |                                                    |
+        # | `TIMESTAMP`  | `Time`                               |                                                    |
+        # | `TIME`       | `Google::Cloud::BigQuery::Time`      |                                                    |
+        # | `BYTES`      | `File`, `IO`, `StringIO`, or similar |                                                    |
+        # | `ARRAY`      | `Array`                              | Nested arrays, `nil` values are not supported.     |
+        # | `STRUCT`     | `Hash`                               | Hash keys may be strings or symbols.               |
+        #
+        # Because BigQuery's streaming API is designed for high insertion rates,
+        # modifications to the underlying table metadata are eventually
+        # consistent when interacting with the streaming system. In most cases
+        # metadata changes are propagated within minutes, but during this period
+        # API responses may reflect the inconsistent state of the table.
+        #
         # @see https://cloud.google.com/bigquery/streaming-data-into-bigquery
         #   Streaming Data Into BigQuery
         #
+        # @see https://cloud.google.com/bigquery/troubleshooting-errors#metadata-errors-for-streaming-inserts
+        #   BigQuery Troubleshooting: Metadata errors for streaming inserts
+        #
         # @param [String] table_id The ID of the destination table.
         # @param [Hash, Array<Hash>] rows A hash object or array of hash objects
-        #   containing the data. Required.
-        # @param [Array<String>] insert_ids A unique ID for each row. BigQuery
-        #   uses this property to detect duplicate insertion requests on a
-        #   best-effort basis. For more information, see [data
-        #   consistency](https://cloud.google.com/bigquery/streaming-data-into-bigquery#dataconsistency).
-        #   Optional. If not provided, the client library will assign a UUID to
-        #   each row before the request is sent.
+        #   containing the data. Required. `BigDecimal` values will be rounded to
+        #   scale 9 to conform with the BigQuery `NUMERIC` data type. To avoid
+        #   rounding `BIGNUMERIC` type values with scale greater than 9, use `String`
+        #   instead of `BigDecimal`.
+        # @param [Array<String|Symbol>, Symbol] insert_ids A unique ID for each row. BigQuery uses this property to
+        #   detect duplicate insertion requests on a best-effort basis. For more information, see [data
+        #   consistency](https://cloud.google.com/bigquery/streaming-data-into-bigquery#dataconsistency). Optional. If
+        #   not provided, the client library will assign a UUID to each row before the request is sent.
+        #
+        #  The value `:skip` can be provided to skip the generation of IDs for all rows, or to skip the generation of an
+        #  ID for a specific row in the array.
         # @param [Boolean] skip_invalid Insert all valid rows of a request, even
         #   if invalid rows exist. The default value is `false`, which causes
         #   the entire request to fail if any invalid rows exist.
@@ -1975,6 +2557,12 @@ module Google
         #   a new table with the given `table_id`, if no table is found for
         #   `table_id`. The default value is false.
         #
+        # @yield [table] a block for setting the table
+        # @yieldparam [Google::Cloud::Bigquery::Table::Updater] table An updater
+        #   to set additional properties on the table in the API request to
+        #   create it. Only used when `autocreate` is set and the table does not
+        #   already exist.
+        #
         # @return [Google::Cloud::Bigquery::InsertResponse] An insert response
         #   object.
         #
@@ -2018,42 +2606,36 @@ module Google
         #     t.schema.integer "age", mode: :required
         #   end
         #
+        # @example Pass `BIGNUMERIC` value as a string to avoid rounding to scale 9 in the conversion from `BigDecimal`:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   row = {
+        #     "my_numeric" => BigDecimal("123456798.987654321"),
+        #     "my_bignumeric" => "123456798.98765432100001" # BigDecimal would be rounded, use String instead!
+        #   }
+        #   dataset.insert "my_table", row
+        #
         # @!group Data
         #
-        def insert table_id, rows, insert_ids: nil, skip_invalid: nil,
-                   ignore_unknown: nil, autocreate: nil
+        def insert table_id, rows, insert_ids: nil, skip_invalid: nil, ignore_unknown: nil, autocreate: nil, &block
           rows = [rows] if rows.is_a? Hash
+          raise ArgumentError, "No rows provided" if rows.empty?
+
+          insert_ids = Array.new(rows.count) { :skip } if insert_ids == :skip
           insert_ids = Array insert_ids
-          if insert_ids.count > 0 && insert_ids.count != rows.count
+          if insert_ids.count.positive? && insert_ids.count != rows.count
             raise ArgumentError, "insert_ids must be the same size as rows"
           end
 
           if autocreate
-            begin
-              insert_data table_id, rows, skip_invalid:   skip_invalid,
-                                          ignore_unknown: ignore_unknown,
-                                          insert_ids:     insert_ids
-            rescue Google::Cloud::NotFoundError
-              sleep rand(1..60)
-              begin
-                create_table table_id do |tbl_updater|
-                  yield tbl_updater if block_given?
-                end
-              # rubocop:disable Lint/HandleExceptions
-              rescue Google::Cloud::AlreadyExistsError
-              end
-              # rubocop:enable Lint/HandleExceptions
-
-              sleep 60
-              insert table_id, rows, skip_invalid:   skip_invalid,
-                                     ignore_unknown: ignore_unknown,
-                                     autocreate:     true,
-                                     insert_ids:     insert_ids
-            end
+            insert_data_with_autocreate table_id, rows, skip_invalid: skip_invalid, ignore_unknown: ignore_unknown,
+                                                        insert_ids: insert_ids, &block
           else
-            insert_data table_id, rows, skip_invalid:   skip_invalid,
-                                        ignore_unknown: ignore_unknown,
-                                        insert_ids:     insert_ids
+            insert_data table_id, rows, skip_invalid: skip_invalid, ignore_unknown: ignore_unknown,
+                                        insert_ids: insert_ids
           end
         end
 
@@ -2104,9 +2686,8 @@ module Google
         #
         #   inserter.stop.wait!
         #
-        def insert_async table_id, skip_invalid: nil, ignore_unknown: nil,
-                         max_bytes: 10000000, max_rows: 500, interval: 10,
-                         threads: 4, &block
+        def insert_async table_id, skip_invalid: nil, ignore_unknown: nil, max_bytes: 10_000_000, max_rows: 500,
+                         interval: 10, threads: 4, &block
           ensure_service!
 
           # Get table, don't use Dataset#table which handles NotFoundError
@@ -2121,15 +2702,28 @@ module Google
 
         protected
 
-        def insert_data table_id, rows, skip_invalid: nil, ignore_unknown: nil,
-                        insert_ids: nil
+        def insert_data_with_autocreate table_id, rows, skip_invalid: nil, ignore_unknown: nil, insert_ids: nil
+          insert_data table_id, rows, skip_invalid: skip_invalid, ignore_unknown: ignore_unknown, insert_ids: insert_ids
+        rescue Google::Cloud::NotFoundError
+          sleep rand(1..60)
+          begin
+            create_table table_id do |tbl_updater|
+              yield tbl_updater if block_given?
+            end
+          rescue Google::Cloud::AlreadyExistsError
+            # Do nothing if it already exists
+          end
+          sleep 60
+          retry
+        end
+
+        def insert_data table_id, rows, skip_invalid: nil, ignore_unknown: nil, insert_ids: nil
           rows = [rows] if rows.is_a? Hash
           raise ArgumentError, "No rows provided" if rows.empty?
           ensure_service!
-          options = { skip_invalid:   skip_invalid,
-                      ignore_unknown: ignore_unknown,
-                      insert_ids:     insert_ids }
-          gapi = service.insert_tabledata dataset_id, table_id, rows, options
+          gapi = service.insert_tabledata dataset_id, table_id, rows, skip_invalid:   skip_invalid,
+                                                                      ignore_unknown: ignore_unknown,
+                                                                      insert_ids:     insert_ids
           InsertResponse.from_gapi rows, gapi
         end
 
@@ -2160,10 +2754,8 @@ module Google
         def patch_gapi! *attributes
           return if attributes.empty?
           ensure_service!
-          patch_args = Hash[attributes.map do |attr|
-            [attr, @gapi.send(attr)]
-          end]
-          patch_gapi = Google::Apis::BigqueryV2::Dataset.new patch_args
+          patch_args = Hash[attributes.map { |attr| [attr, @gapi.send(attr)] }]
+          patch_gapi = Google::Apis::BigqueryV2::Dataset.new(**patch_args)
           patch_gapi.etag = etag if etag
           @gapi = service.patch_dataset dataset_id, patch_gapi
         end
@@ -2172,7 +2764,7 @@ module Google
         # Load the complete representation of the dataset if it has been
         # only partially loaded by a request to the API list method.
         def ensure_full_data!
-          reload! if resource_partial?
+          reload! unless resource_full?
         end
 
         def ensure_job_succeeded! job
@@ -2203,11 +2795,8 @@ module Google
           )
         end
 
-        def load_job_csv_options! job, jagged_rows: nil,
-                                  quoted_newlines: nil,
-                                  delimiter: nil,
-                                  quote: nil, skip_leading: nil,
-                                  null_marker: nil
+        def load_job_csv_options! job, jagged_rows: nil, quoted_newlines: nil, delimiter: nil, quote: nil,
+                                  skip_leading: nil, null_marker: nil
           job.jagged_rows = jagged_rows unless jagged_rows.nil?
           job.quoted_newlines = quoted_newlines unless quoted_newlines.nil?
           job.delimiter = delimiter unless delimiter.nil?
@@ -2216,17 +2805,11 @@ module Google
           job.skip_leading = skip_leading unless skip_leading.nil?
         end
 
-        def load_job_file_options! job, format: nil,
-                                   projection_fields: nil,
-                                   jagged_rows: nil, quoted_newlines: nil,
-                                   encoding: nil, delimiter: nil,
-                                   ignore_unknown: nil, max_bad_records: nil,
-                                   quote: nil, skip_leading: nil,
-                                   null_marker: nil
+        def load_job_file_options! job, format: nil, projection_fields: nil, jagged_rows: nil, quoted_newlines: nil,
+                                   encoding: nil, delimiter: nil, ignore_unknown: nil, max_bad_records: nil, quote: nil,
+                                   skip_leading: nil, null_marker: nil
           job.format = format unless format.nil?
-          unless projection_fields.nil?
-            job.projection_fields = projection_fields
-          end
+          job.projection_fields = projection_fields unless projection_fields.nil?
           job.encoding = encoding unless encoding.nil?
           job.ignore_unknown = ignore_unknown unless ignore_unknown.nil?
           job.max_bad_records = max_bad_records unless max_bad_records.nil?
@@ -2238,16 +2821,11 @@ module Google
                                      null_marker:     null_marker
         end
 
-        def load_job_updater table_id, format: nil, create: nil,
-                             write: nil, projection_fields: nil,
-                             jagged_rows: nil, quoted_newlines: nil,
-                             encoding: nil, delimiter: nil,
-                             ignore_unknown: nil, max_bad_records: nil,
-                             quote: nil, skip_leading: nil, dryrun: nil,
-                             schema: nil, job_id: nil, prefix: nil, labels: nil,
-                             autodetect: nil, null_marker: nil
-          new_job = load_job_gapi table_id, dryrun, job_id: job_id,
-                                                    prefix: prefix
+        def load_job_updater table_id, format: nil, create: nil, write: nil, projection_fields: nil, jagged_rows: nil,
+                             quoted_newlines: nil, encoding: nil, delimiter: nil, ignore_unknown: nil,
+                             max_bad_records: nil, quote: nil, skip_leading: nil, dryrun: nil, schema: nil, job_id: nil,
+                             prefix: nil, labels: nil, autodetect: nil, null_marker: nil
+          new_job = load_job_gapi table_id, dryrun, job_id: job_id, prefix: prefix
           LoadJob::Updater.new(new_job).tap do |job|
             job.location = location if location # may be dataset reference
             job.create = create unless create.nil?
@@ -2285,9 +2863,7 @@ module Google
             job_gapi.configuration.load.update! source_uris: urls
             if job_gapi.configuration.load.source_format.nil?
               source_format = Convert.derive_source_format_from_list urls
-              unless source_format.nil?
-                job_gapi.configuration.load.source_format = source_format
-              end
+              job_gapi.configuration.load.source_format = source_format unless source_format.nil?
             end
           end
 
@@ -2299,9 +2875,7 @@ module Google
           path = Pathname(file).to_path
           if job_gapi.configuration.load.source_format.nil?
             source_format = Convert.derive_source_format path
-            unless source_format.nil?
-              job_gapi.configuration.load.source_format = source_format
-            end
+            job_gapi.configuration.load.source_format = source_format unless source_format.nil?
           end
 
           gapi = service.load_table_file file, job_gapi
@@ -2310,21 +2884,18 @@ module Google
 
         def load_local_or_uri file, updater
           job_gapi = updater.to_gapi
-          job = if local_file? file
-                  load_local file, job_gapi
-                else
-                  load_storage file, job_gapi
-                end
-          job
+          if local_file? file
+            load_local file, job_gapi
+          else
+            load_storage file, job_gapi
+          end
         end
 
         def storage_url? files
           [files].flatten.all? do |file|
             file.respond_to?(:to_gs_url) ||
-              (file.respond_to?(:to_str) &&
-                  file.to_str.downcase.start_with?("gs://")) ||
-              (file.is_a?(URI) &&
-                  file.to_s.downcase.start_with?("gs://"))
+              (file.respond_to?(:to_str) && file.to_str.downcase.start_with?("gs://")) ||
+              (file.is_a?(URI) && file.to_s.downcase.start_with?("gs://"))
           end
         end
 
@@ -2348,15 +2919,16 @@ module Google
         end
 
         ##
-        # Yielded to a block to accumulate changes for a patch request.
+        # Yielded to a block to accumulate changes for a create request. See {Project#create_dataset}.
         class Updater < Dataset
           ##
-          # A list of attributes that were updated.
+          # @private A list of attributes that were updated.
           attr_reader :updates
 
           ##
-          # Create an Updater object.
+          # @private Create an Updater object.
           def initialize gapi
+            super()
             @updates = []
             @gapi = gapi
           end
@@ -2372,8 +2944,115 @@ module Google
             @access
           end
 
+          # rubocop:disable Style/MethodDefParentheses
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def delete(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def create_table(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def create_view(*)
+            raise "not implemented in #{self.class}"
+          end
+
           ##
-          # Make sure any access changes are saved
+          # @raise [RuntimeError] not implemented
+          def create_materialized_view(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def table(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def tables(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def model(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def models(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def create_routine(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def routine(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def routines(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def query_job(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def query(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def external(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def load_job(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def load(*)
+            raise "not implemented in #{self.class}"
+          end
+
+          ##
+          # @raise [RuntimeError] not implemented
+          def reload!
+            raise "not implemented in #{self.class}"
+          end
+          alias refresh! reload!
+
+          # rubocop:enable Style/MethodDefParentheses
+
+          ##
+          # @private Make sure any access changes are saved
           def check_for_mutated_access!
             return if @access.nil?
             return unless @access.changed?
@@ -2381,6 +3060,8 @@ module Google
             patch_gapi! :access
           end
 
+          ##
+          # @private
           def to_gapi
             check_for_mutated_access!
             @gapi