google-cloud-bigquery 1.12.0 → 1.38.1

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

@@ -56,7 +56,8 @@ module Google
         # @private The Service object.
         attr_accessor :service
 
-        attr_reader :name, :numeric_id
+        attr_reader :name
+        attr_reader :numeric_id
 
         ##
         # Creates a new Service instance.
@@ -91,8 +92,7 @@ module Google
         # @return [String] The service account email address.
         #
         def service_account_email
-          @service_account_email ||= \
-            service.project_service_account.email
+          @service_account_email ||= service.project_service_account.email
         end
 
         ##
@@ -139,8 +139,8 @@ module Google
         #   * `empty` - An error will be returned if the destination table
         #     already contains data.
         # @param [String] job_id A user-defined ID for the copy 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
@@ -149,18 +149,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 [job] a job configuration object
         # @yieldparam [Google::Cloud::Bigquery::CopyJob::Updater] job a job
         #   configuration object for setting additional options.
@@ -182,11 +190,9 @@ module Google
         #
         # @!group Data
         #
-        def copy_job source_table, destination_table, create: nil, write: nil,
-                     job_id: nil, prefix: nil, labels: nil
+        def copy_job source_table, destination_table, create: nil, write: nil, job_id: nil, prefix: nil, labels: nil
           ensure_service!
-          options = { create: create, write: write, labels: labels,
-                      job_id: job_id, prefix: prefix }
+          options = { create: create, write: write, labels: labels, job_id: job_id, prefix: prefix }
 
           updater = CopyJob::Updater.from_options(
             service,
@@ -261,13 +267,8 @@ module Google
         #
         # @!group Data
         #
-        def copy source_table, destination_table, create: nil, write: nil,
-                 &block
-          job = copy_job source_table,
-                         destination_table,
-                         create: create,
-                         write:  write,
-                         &block
+        def copy source_table, destination_table, create: nil, write: nil, &block
+          job = copy_job source_table, destination_table, create: create, write: write, &block
           job.wait_until_done!
           ensure_job_succeeded! job
           true
@@ -277,27 +278,6 @@ module Google
         # Queries data by creating a [query
         # job](https://cloud.google.com/bigquery/docs/query-overview#query_jobs).
         #
-        # 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.
         #
@@ -305,13 +285,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
@@ -375,13 +402,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
@@ -390,30 +423,51 @@ 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.
         #
         #   See [Generating a job
         #   ID](https://cloud.google.com/bigquery/docs/managing-jobs#generate-jobid).
         # @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 query options.
@@ -425,8 +479,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   job = bigquery.query_job "SELECT name FROM " \
-        #                            "`my_project.my_dataset.my_table`"
+        #   job = bigquery.query_job "SELECT name FROM `my_project.my_dataset.my_table`"
         #
         #   job.wait_until_done!
         #   if !job.failed?
@@ -440,8 +493,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   job = bigquery.query_job "SELECT name FROM " \
-        #                            " [my_project:my_dataset.my_table]",
+        #   job = bigquery.query_job "SELECT name FROM [my_project:my_dataset.my_table]",
         #                            legacy_sql: true
         #
         #   job.wait_until_done!
@@ -456,9 +508,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   job = bigquery.query_job "SELECT name FROM " \
-        #                            "`my_dataset.my_table`" \
-        #                            " WHERE id = ?",
+        #   job = bigquery.query_job "SELECT name FROM `my_dataset.my_table` WHERE id = ?",
         #                            params: [1]
         #
         #   job.wait_until_done!
@@ -473,9 +523,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   job = bigquery.query_job "SELECT name FROM " \
-        #                            "`my_dataset.my_table`" \
-        #                            " WHERE id = @id",
+        #   job = bigquery.query_job "SELECT name FROM `my_dataset.my_table` WHERE id = @id",
         #                            params: { id: 1 }
         #
         #   job.wait_until_done!
@@ -485,18 +533,32 @@ module Google
         #     end
         #   end
         #
+        # @example Query using named query parameters with types:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   job = bigquery.query_job "SELECT name FROM `my_dataset.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
         #
-        #   job = bigquery.query_job "CREATE TABLE " \
-        #                            "`my_dataset.my_table` " \
-        #                            "(x INT64)"
+        #   job = bigquery.query_job "CREATE TABLE`my_dataset.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:
@@ -504,10 +566,7 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   job = bigquery.query_job "UPDATE " \
-        #                            "`my_dataset.my_table` " \
-        #                            "SET x = x + 1 " \
-        #                            "WHERE x IS NOT NULL"
+        #   job = bigquery.query_job "UPDATE `my_dataset.my_table` SET x = x + 1 WHERE x IS NOT NULL"
         #
         #   job.wait_until_done!
         #   if !job.failed?
@@ -538,23 +597,56 @@ module Google
         #     end
         #   end
         #
-        def query_job query, params: nil, external: nil,
-                      priority: "INTERACTIVE", cache: true, table: nil,
-                      create: nil, write: nil, dryrun: nil, dataset: nil,
-                      project: 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,
+                      dataset: nil,
+                      project: 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,
-                      dataset: dataset, project: (project || self.project),
-                      legacy_sql: legacy_sql, standard_sql: standard_sql,
-                      maximum_billing_tier: maximum_billing_tier,
-                      maximum_bytes_billed: maximum_bytes_billed,
-                      external: external, job_id: job_id, prefix: prefix,
-                      labels: labels, udfs: udfs, params: params }
+          options = {
+            params: params,
+            types: types,
+            external: external,
+            priority: priority,
+            cache: cache,
+            table: table,
+            create: create,
+            write: write,
+            dryrun: dryrun,
+            dataset: dataset,
+            project: (project || self.project),
+            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
 
@@ -571,27 +663,6 @@ module Google
         # as needed to complete the query. When used for executing DDL/DML
         # statements, this method does not return row data.
         #
-        # 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.
         #
@@ -601,13 +672,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
@@ -649,6 +767,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.
@@ -663,9 +783,12 @@ module Google
         #   sql = "SELECT name FROM `my_project.my_dataset.my_table`"
         #   data = bigquery.query sql
         #
+        #   # 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"
@@ -675,9 +798,12 @@ module Google
         #   sql = "SELECT name FROM [my_project:my_dataset.my_table]"
         #   data = bigquery.query sql, 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 Retrieve all rows: (See {Data#all})
         #   require "google/cloud/bigquery"
@@ -695,28 +821,46 @@ module Google
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_dataset.my_table`" \
-        #                         "WHERE id = ?",
+        #   data = bigquery.query "SELECT name FROM `my_dataset.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"
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
-        #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_dataset.my_table`" \
-        #                         "WHERE id = @id",
+        #   data = bigquery.query "SELECT name FROM `my_dataset.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
+        #
+        #   data = bigquery.query "SELECT name FROM `my_dataset.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"
@@ -725,16 +869,14 @@ module Google
         #
         #   data = bigquery.query "CREATE TABLE `my_dataset.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
         #
-        #   data = bigquery.query "UPDATE `my_dataset.my_table` " \
-        #                         "SET x = x + 1 " \
-        #                         "WHERE x IS NOT NULL"
+        #   data = bigquery.query "UPDATE `my_dataset.my_table` SET x = x + 1 WHERE x IS NOT NULL"
         #
         #   puts data.num_dml_affected_rows
         #
@@ -755,17 +897,36 @@ 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
-        #
-        def query query, params: nil, external: nil, max: nil, cache: true,
-                  dataset: nil, project: nil, standard_sql: nil,
-                  legacy_sql: nil, &block
-          job = query_job query, params: params, external: external,
-                                 cache: cache, dataset: dataset,
-                                 project: project, standard_sql: standard_sql,
-                                 legacy_sql: legacy_sql, &block
+        #   # Retrieve the next page of results
+        #   data = data.next if data.next?
+        #
+        def query query,
+                  params: nil,
+                  types: nil,
+                  external: nil,
+                  max: nil,
+                  cache: true,
+                  dataset: nil,
+                  project: nil,
+                  standard_sql: nil,
+                  legacy_sql: nil,
+                  session_id: nil,
+                  &block
+          job = query_job query,
+                          params: params,
+                          types: types,
+                          external: external,
+                          cache: cache,
+                          dataset: dataset,
+                          project: project,
+                          standard_sql: standard_sql,
+                          legacy_sql: legacy_sql,
+                          session_id: session_id,
+                          &block
           job.wait_until_done!
 
           if job.failed?
@@ -822,9 +983,12 @@ module Google
         #   data = bigquery.query "SELECT * FROM my_ext_table",
         #                         external: { my_ext_table: csv_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?
         #
         def external url, format: nil
           ext = External.from_urls url, format
@@ -861,9 +1025,7 @@ module Google
         #
         def dataset dataset_id, skip_lookup: nil
           ensure_service!
-          if skip_lookup
-            return Dataset.new_reference project, dataset_id, service
-          end
+          return Dataset.new_reference project, dataset_id, service if skip_lookup
           gapi = service.get_dataset dataset_id
           Dataset.from_gapi gapi, service
         rescue Google::Cloud::NotFoundError
@@ -874,14 +1036,13 @@ module Google
         # Creates a new dataset.
         #
         # @param [String] dataset_id A unique ID for this dataset, without the
-        #   project name. The ID must contain only letters (a-z, A-Z), numbers
-        #   (0-9), or underscores (_). The maximum length is 1,024 characters.
+        #   project name. The ID must contain only letters (`[A-Za-z]`), numbers
+        #   (`[0-9]`), or underscores (`_`). The maximum length is 1,024 characters.
         # @param [String] name A descriptive name for the dataset.
         # @param [String] description A user-friendly description of the
         #   dataset.
         # @param [Integer] expiration The default lifetime of all tables in the
-        #   dataset, in milliseconds. The minimum value is 3600000 milliseconds
-        #   (one hour).
+        #   dataset, in milliseconds. The minimum value is `3_600_000` (one hour).
         # @param [String] location The geographic location where the dataset
         #   should reside. Possible values include `EU` and `US`. The default
         #   value is `US`.
@@ -990,8 +1151,7 @@ module Google
         #
         def datasets all: nil, filter: nil, token: nil, max: nil
           ensure_service!
-          options = { all: all, filter: filter, token: token, max: max }
-          gapi = service.list_datasets options
+          gapi = service.list_datasets all: all, filter: filter, token: token, max: max
           Dataset::List.from_gapi gapi, service, all, filter, max
         end
 
@@ -1024,17 +1184,27 @@ module Google
         # Retrieves the list of jobs belonging to the project.
         #
         # @param [Boolean] all Whether to display jobs owned by all users in the
-        #   project. The default is `false`.
+        #   project. The default is `false`. Optional.
         # @param [String] token A previously-returned page token representing
-        #   part of the larger set of results to view.
-        # @param [Integer] max Maximum number of jobs to return.
-        # @param [String] filter A filter for job state.
+        #   part of the larger set of results to view. Optional.
+        # @param [Integer] max Maximum number of jobs to return. Optional.
+        # @param [String] filter A filter for job state. Optional.
         #
         #   Acceptable values are:
         #
         #   * `done` - Finished jobs
         #   * `pending` - Pending jobs
         #   * `running` - Running jobs
+        # @param [Time] min_created_at Min value for {Job#created_at}. When
+        #   provided, only jobs created after or at this time are returned.
+        #   Optional.
+        # @param [Time] max_created_at Max value for {Job#created_at}. When
+        #   provided, only jobs created before or at this time are returned.
+        #   Optional.
+        # @param [Google::Cloud::Bigquery::Job, String] parent_job A job
+        #   object or a job ID. If set, retrieve only child jobs of the
+        #   specified parent. Optional. See {Job#job_id}, {Job#num_child_jobs},
+        #   and {Job#parent_job_id}.
         #
         # @return [Array<Google::Cloud::Bigquery::Job>] (See
         #   {Google::Cloud::Bigquery::Job::List})
@@ -1059,6 +1229,20 @@ module Google
         #     # process job
         #   end
         #
+        # @example Retrieve only jobs created within provided times:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   two_days_ago = Time.now - 60*60*24*2
+        #   three_days_ago = Time.now - 60*60*24*3
+        #
+        #   jobs = bigquery.jobs min_created_at: three_days_ago,
+        #                        max_created_at: two_days_ago
+        #   jobs.each do |job|
+        #     # process job
+        #   end
+        #
         # @example Retrieve all jobs: (See {Job::List#all})
         #   require "google/cloud/bigquery"
         #
@@ -1069,11 +1253,63 @@ module Google
         #     # process job
         #   end
         #
-        def jobs all: nil, token: nil, max: nil, filter: nil
+        # @example Retrieve child jobs by setting `parent_job`:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #
+        #   multi_statement_sql = <<~SQL
+        #     -- Declare a variable to hold names as an array.
+        #     DECLARE top_names ARRAY<STRING>;
+        #     -- Build an array of the top 100 names from the year 2017.
+        #     SET top_names = (
+        #     SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100)
+        #     FROM `bigquery-public-data.usa_names.usa_1910_current`
+        #     WHERE year = 2017
+        #     );
+        #     -- Which names appear as words in Shakespeare's plays?
+        #     SELECT
+        #     name AS shakespeare_name
+        #     FROM UNNEST(top_names) AS name
+        #     WHERE name IN (
+        #     SELECT word
+        #     FROM `bigquery-public-data.samples.shakespeare`
+        #     );
+        #   SQL
+        #
+        #   job = bigquery.query_job multi_statement_sql
+        #
+        #   job.wait_until_done!
+        #
+        #   child_jobs = bigquery.jobs parent_job: job
+        #
+        #   child_jobs.each do |child_job|
+        #     script_statistics = child_job.script_statistics
+        #     puts script_statistics.evaluation_kind
+        #     script_statistics.stack_frames.each do |stack_frame|
+        #       puts stack_frame.text
+        #     end
+        #   end
+        #
+        def jobs all: nil,
+                 token: nil,
+                 max: nil,
+                 filter: nil,
+                 min_created_at: nil,
+                 max_created_at: nil,
+                 parent_job: nil
           ensure_service!
-          options = { all: all, token: token, max: max, filter: filter }
-          gapi = service.list_jobs options
-          Job::List.from_gapi gapi, service, all, max, filter
+          parent_job = parent_job.job_id if parent_job.is_a? Job
+          options = {
+            parent_job_id: parent_job,
+            all: all,
+            token: token,
+            max: max, filter: filter,
+            min_created_at: min_created_at,
+            max_created_at: max_created_at
+          }
+          gapi = service.list_jobs(**options)
+          Job::List.from_gapi gapi, service, **options
         end
 
         ##
@@ -1119,8 +1355,7 @@ module Google
         #
         def projects token: nil, max: nil
           ensure_service!
-          options = { token: token, max: max }
-          gapi = service.list_projects options
+          gapi = service.list_projects token: token, max: max
           Project::List.from_gapi gapi, service, max
         end
 
@@ -1141,14 +1376,15 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   fourpm = bigquery.time 16, 0, 0
-        #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_dataset.my_table`" \
-        #                         "WHERE time_of_date = @time",
+        #   data = bigquery.query "SELECT name FROM `my_dataset.my_table` WHERE time_of_date = @time",
         #                         params: { time: fourpm }
         #
+        #   # 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 Create Time with fractional seconds:
         #   require "google/cloud/bigquery"
@@ -1156,14 +1392,15 @@ module Google
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   precise_time = bigquery.time 16, 35, 15.376541
-        #   data = bigquery.query "SELECT name " \
-        #                         "FROM `my_dataset.my_table`" \
-        #                         "WHERE time_of_date >= @time",
+        #   data = bigquery.query "SELECT name FROM `my_dataset.my_table` WHERE time_of_date >= @time",
         #                         params: { time: precise_time }
         #
+        #   # 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?
         #
         def time hour, minute, second
           Bigquery::Time.new "#{hour}:#{minute}:#{second}"
@@ -1280,49 +1517,61 @@ module Google
         end
 
         ##
-        # Extracts the data from the provided table to a Google Cloud Storage
-        # file using an asynchronous method. In this method, an {ExtractJob} is
-        # immediately returned. The caller may poll the service by repeatedly
-        # calling {Job#reload!} and {Job#done?} to detect when the job is done,
-        # or simply block until the job is done by calling
+        # Extracts the data from a table or exports a model to Google Cloud Storage
+        # asynchronously, immediately returning an {ExtractJob} that can be used to
+        # track the progress of the export job.  The caller may poll the service by
+        # repeatedly calling {Job#reload!} and {Job#done?} to detect when the job
+        # is done, or simply block until the job is done by calling
         # #{Job#wait_until_done!}. See {#extract} for the synchronous version.
-        # Use this method instead of {Table#extract_job} to extract data from
-        # source tables in other projects.
+        #
+        # Use this method instead of {Table#extract_job} or {Model#extract_job} to
+        # extract data from source tables or models in other projects.
         #
         # The geographic location for the job ("US", "EU", etc.) can be set via
         # {ExtractJob::Updater#location=} in a block passed to this method.
         #
-        # @see https://cloud.google.com/bigquery/exporting-data-from-bigquery
-        #   Exporting Data From BigQuery
+        # @see https://cloud.google.com/bigquery/docs/exporting-data
+        #   Exporting table data
+        # @see https://cloud.google.com/bigquery-ml/docs/exporting-models
+        #   Exporting models
         #
-        # @param [String, Table] table The source table from which to extract
-        #   data. This can be a table object; or a string ID as specified by the
-        #   [Standard SQL Query
+        # @param [Table, Model, String] source The source table or model for
+        #   the extract operation. This can be a table or model object; or a
+        #   table ID string as specified by the [Standard SQL Query
         #   Reference](https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#from-clause)
         #   (`project-name.dataset_id.table_id`) or the [Legacy SQL Query
         #   Reference](https://cloud.google.com/bigquery/query-reference#from)
         #   (`project-name:dataset_id.table_id`).
         # @param [Google::Cloud::Storage::File, String, Array<String>]
         #   extract_url The Google Storage file or file URI pattern(s) to which
-        #   BigQuery should extract the table data.
-        # @param [String] format The exported file format. The default value is
-        #   `csv`.
+        #   BigQuery should extract. For a model export this value should be a
+        #   string ending in an object name prefix, since multiple objects will
+        #   be exported.
+        # @param [String] format The exported file format. The default value for
+        #   tables is `csv`. Tables with nested or repeated fields cannot be
+        #   exported as CSV. The default value for models is `ml_tf_saved_model`.
         #
-        #   The following values are supported:
+        #   Supported values for tables:
         #
         #   * `csv` - CSV
         #   * `json` - [Newline-delimited JSON](http://jsonlines.org/)
         #   * `avro` - [Avro](http://avro.apache.org/)
+        #
+        #   Supported values for models:
+        #
+        #   * `ml_tf_saved_model` - TensorFlow SavedModel
+        #   * `ml_xgboost_booster` - XGBoost Booster
         # @param [String] compression The compression type to use for exported
         #   files. Possible values include `GZIP` and `NONE`. The default value
-        #   is `NONE`.
+        #   is `NONE`. Not applicable when extracting models.
         # @param [String] delimiter Delimiter to use between fields in the
-        #   exported data. Default is <code>,</code>.
-        # @param [Boolean] header Whether to print out a header row in the
-        #   results. Default is `true`.
+        #   exported table data. Default is `,`. Not applicable when extracting
+        #   models.
+        # @param [Boolean] header Whether to print out a header row in table
+        #   exports. Default is `true`. Not applicable when extracting models.
         # @param [String] job_id A user-defined ID for the extract 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
@@ -1331,48 +1580,65 @@ 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 [job] a job configuration object
         # @yieldparam [Google::Cloud::Bigquery::ExtractJob::Updater] job a job
         #   configuration object for setting additional options.
         #
         # @return [Google::Cloud::Bigquery::ExtractJob]
         #
-        # @example
+        # @example Export table data
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
         #
         #   table_id = "bigquery-public-data.samples.shakespeare"
-        #   extract_job = bigquery.extract_job table_id,
-        #                                      "gs://my-bucket/shakespeare.csv"
+        #   extract_job = bigquery.extract_job table_id, "gs://my-bucket/shakespeare.csv"
         #   extract_job.wait_until_done!
         #   extract_job.done? #=> true
         #
+        # @example Export a model
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model"
+        #
+        #   extract_job = bigquery.extract model, "gs://my-bucket/#{model.model_id}"
+        #
         # @!group Data
         #
-        def extract_job table, extract_url, format: nil, compression: nil,
-                        delimiter: nil, header: nil, job_id: nil, prefix: nil,
-                        labels: nil
+        def extract_job source, extract_url, format: nil, compression: nil, delimiter: nil, header: nil, job_id: nil,
+                        prefix: nil, labels: nil
           ensure_service!
-          options = { format: format, compression: compression,
-                      delimiter: delimiter, header: header, job_id: job_id,
+          options = { format: format, compression: compression, delimiter: delimiter, header: header, job_id: job_id,
                       prefix: prefix, labels: labels }
+          source_ref = if source.respond_to? :model_ref
+                         source.model_ref
+                       else
+                         Service.get_table_ref source, default_ref: project_ref
+                       end
 
-          table_ref = Service.get_table_ref table, default_ref: project_ref
-          updater = ExtractJob::Updater.from_options service, table_ref,
-                                                     extract_url, options
+          updater = ExtractJob::Updater.from_options service, source_ref, extract_url, options
 
           yield updater if block_given?
 
@@ -1382,51 +1648,63 @@ module Google
         end
 
         ##
-        # Extracts the data from the provided table to a Google Cloud Storage
-        # file using a synchronous method that blocks for a response. Timeouts
+        # Extracts the data from a table or exports a model to Google Cloud Storage
+        # using a synchronous method that blocks for a response. Timeouts
         # and transient errors are generally handled as needed to complete the
-        # job. See {#extract_job} for the asynchronous version. Use this method
-        # instead of {Table#extract} to extract data from source tables in other
-        # projects.
+        # job. See {#extract_job} for the asynchronous version.
+        #
+        # Use this method instead of {Table#extract} or {Model#extract} to
+        # extract data from source tables or models in other projects.
         #
         # The geographic location for the job ("US", "EU", etc.) can be set via
         # {ExtractJob::Updater#location=} in a block passed to this method.
         #
-        # @see https://cloud.google.com/bigquery/exporting-data-from-bigquery
-        #   Exporting Data From BigQuery
+        # @see https://cloud.google.com/bigquery/docs/exporting-data
+        #   Exporting table data
+        # @see https://cloud.google.com/bigquery-ml/docs/exporting-models
+        #   Exporting models
         #
-        # @param [String, Table] table The source table from which to extract
-        #   data. This can be a table object; or a string ID as specified by the
-        #   [Standard SQL Query
+        # @param [Table, Model, String] source The source table or model for
+        #   the extract operation. This can be a table or model object; or a
+        #   table ID string as specified by the [Standard SQL Query
         #   Reference](https://cloud.google.com/bigquery/docs/reference/standard-sql/query-syntax#from-clause)
         #   (`project-name.dataset_id.table_id`) or the [Legacy SQL Query
         #   Reference](https://cloud.google.com/bigquery/query-reference#from)
         #   (`project-name:dataset_id.table_id`).
         # @param [Google::Cloud::Storage::File, String, Array<String>]
         #   extract_url The Google Storage file or file URI pattern(s) to which
-        #   BigQuery should extract the table data.
-        # @param [String] format The exported file format. The default value is
-        #   `csv`.
+        #   BigQuery should extract. For a model export this value should be a
+        #   string ending in an object name prefix, since multiple objects will
+        #   be exported.
+        # @param [String] format The exported file format. The default value for
+        #   tables is `csv`. Tables with nested or repeated fields cannot be
+        #   exported as CSV. The default value for models is `ml_tf_saved_model`.
         #
-        #   The following values are supported:
+        #   Supported values for tables:
         #
         #   * `csv` - CSV
         #   * `json` - [Newline-delimited JSON](http://jsonlines.org/)
         #   * `avro` - [Avro](http://avro.apache.org/)
+        #
+        #   Supported values for models:
+        #
+        #   * `ml_tf_saved_model` - TensorFlow SavedModel
+        #   * `ml_xgboost_booster` - XGBoost Booster
         # @param [String] compression The compression type to use for exported
         #   files. Possible values include `GZIP` and `NONE`. The default value
-        #   is `NONE`.
+        #   is `NONE`. Not applicable when extracting models.
         # @param [String] delimiter Delimiter to use between fields in the
-        #   exported data. Default is <code>,</code>.
-        # @param [Boolean] header Whether to print out a header row in the
-        #   results. Default is `true`.
+        #   exported table data. Default is `,`. Not applicable when extracting
+        #   models.
+        # @param [Boolean] header Whether to print out a header row in table
+        #   exports. Default is `true`. Not applicable when extracting models.
         # @yield [job] a job configuration object
         # @yieldparam [Google::Cloud::Bigquery::ExtractJob::Updater] job a job
         #   configuration object for setting additional options.
         #
         # @return [Boolean] Returns `true` if the extract operation succeeded.
         #
-        # @example
+        # @example Export table data
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
@@ -1434,12 +1712,19 @@ module Google
         #   bigquery.extract "bigquery-public-data.samples.shakespeare",
         #                    "gs://my-bucket/shakespeare.csv"
         #
+        # @example Export a model
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   model = dataset.model "my_model"
+        #
+        #   bigquery.extract model, "gs://my-bucket/#{model.model_id}"
+        #
         # @!group Data
         #
-        def extract table, extract_url, format: nil, compression: nil,
-                    delimiter: nil, header: nil, &block
-          job = extract_job table,
-                            extract_url,
+        def extract source, extract_url, format: nil, compression: nil, delimiter: nil, header: nil, &block
+          job = extract_job source, extract_url,
                             format:      format,
                             compression: compression,
                             delimiter:   delimiter,
@@ -1463,9 +1748,7 @@ module Google
 
             # TODO: remove `Integer` and set normally after migrating to Gax or
             # to google-api-client 0.10 (See google/google-api-ruby-client#439)
-            if gapi.numeric_id
-              p.instance_variable_set :@numeric_id, Integer(gapi.numeric_id)
-            end
+            p.instance_variable_set :@numeric_id, Integer(gapi.numeric_id) if gapi.numeric_id
           end
         end