google-cloud-bigquery 1.27.0 → 1.32.0

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

@@ -483,7 +483,7 @@ module Google
             table_id:   m["tbl"]
           }.delete_if { |_, v| v.nil? }
           str_table_ref_hash = default_ref.to_h.merge str_table_ref_hash
-          ref = Google::Apis::BigqueryV2::TableReference.new str_table_ref_hash
+          ref = Google::Apis::BigqueryV2::TableReference.new(**str_table_ref_hash)
           validate_table_ref ref
           ref
         end
@@ -554,9 +554,9 @@ module Google
           nil
         end
 
-        def execute backoff: nil
+        def execute backoff: nil, &block
           if backoff
-            Backoff.new(retries: retries).execute { yield }
+            Backoff.new(retries: retries).execute(&block)
           else
             yield
           end
@@ -590,22 +590,20 @@ module Google
           def execute
             current_retries = 0
             loop do
-              begin
-                return yield
-              rescue Google::Apis::Error => e
-                raise e unless retry? e.body, current_retries
-
-                @backoff.call current_retries
-                current_retries += 1
-              end
+              return yield
+            rescue Google::Apis::Error => e
+              raise e unless retry? e.body, current_retries
+
+              @backoff.call current_retries
+              current_retries += 1
             end
           end
 
           protected
 
           def retry? result, current_retries #:nodoc:
-            if current_retries < @retries
-              return true if retry_error_reason? result
+            if current_retries < @retries && retry_error_reason?(result)
+              return true
             end
             false
           end

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

@@ -273,6 +273,17 @@ module Google
             type_kind == "NUMERIC".freeze
           end
 
+          ##
+          # Checks if the {#type_kind} of the field is `BIGNUMERIC`.
+          #
+          # @return [Boolean] `true` when `BIGNUMERIC`, `false` otherwise.
+          #
+          # @!group Helpers
+          #
+          def bignumeric?
+            type_kind == "BIGNUMERIC".freeze
+          end
+
           ##
           # Checks if the {#type_kind} of the field is `BOOL`.
           #
@@ -401,11 +412,12 @@ module Google
           # @private New Google::Apis::BigqueryV2::StandardSqlDataType from a String or StandardSql::DataType object.
           def self.gapi_from_string_or_data_type data_type
             return if data_type.nil?
-            if data_type.is_a? StandardSql::DataType
+            case data_type
+            when StandardSql::DataType
               data_type.to_gapi
-            elsif data_type.is_a? Hash
+            when Hash
               data_type
-            elsif data_type.is_a?(String) || data_type.is_a?(Symbol)
+            when String, Symbol
               Google::Apis::BigqueryV2::StandardSqlDataType.new type_kind: data_type.to_s.upcase
             else
               raise ArgumentError, "Unable to convert #{data_type} to Google::Apis::BigqueryV2::StandardSqlDataType"

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

@@ -37,16 +37,16 @@ module Google
       # repeated fields.
       #
       # The Table class can also represent a
-      # [view](https://cloud.google.com/bigquery/docs/views), which is a virtual
-      # table defined by a 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 of data in all table fields referenced directly or
-      # indirectly by the top-level query. (See {#view?}, {#query}, {#query=},
-      # and {Dataset#create_view}.)
+      # [logical view](https://cloud.google.com/bigquery/docs/views), which is a virtual
+      # table defined by a SQL query (see {#view?} and {Dataset#create_view}); or a
+      # [materialized view](https://cloud.google.com/bigquery/docs/materialized-views-intro),
+      # which is a precomputed view that periodically caches results of a query for increased
+      # performance and efficiency (see {#materialized_view?} and {Dataset#create_materialized_view}).
       #
       # @see https://cloud.google.com/bigquery/docs/loading-data#loading_denormalized_nested_and_repeated_data
       #   Loading denormalized, nested, and repeated data
+      # @see https://cloud.google.com/bigquery/docs/views Creating views
+      # @see https://cloud.google.com/bigquery/docs/materialized-views-intro Introduction to materialized views
       #
       # @example
       #   require "google/cloud/bigquery"
@@ -77,7 +77,7 @@ module Google
       #   }
       #   table.insert row
       #
-      # @example Creating a BigQuery view:
+      # @example Creating a logical view:
       #   require "google/cloud/bigquery"
       #
       #   bigquery = Google::Cloud::Bigquery.new
@@ -86,6 +86,15 @@ module Google
       #            "SELECT name, age FROM `my_project.my_dataset.my_table`"
       #   view.view? # true
       #
+      # @example Creating a materialized view:
+      #   require "google/cloud/bigquery"
+      #
+      #   bigquery = Google::Cloud::Bigquery.new
+      #   dataset = bigquery.dataset "my_dataset"
+      #   view = dataset.create_materialized_view "my_materialized_view",
+      #                                           "SELECT name, age FROM `my_project.my_dataset.my_table`"
+      #   view.materialized_view? # true
+      #
       class Table
         ##
         # @private The Service object.
@@ -386,8 +395,8 @@ module Google
         # {#resource_full?}), the full representation will be retrieved before
         # the update to comply with ETag-based optimistic concurrency control.
         #
-        # @param [Integer] expiration An expiration time, in seconds,
-        #   for data in time partitions.
+        # @param [Integer, nil] expiration An expiration time, in seconds,
+        #   for data in time partitions, , or `nil` to indicate no expiration time.
         #
         # @example
         #   require "google/cloud/bigquery"
@@ -407,8 +416,9 @@ module Google
         #
         def time_partitioning_expiration= expiration
           reload! unless resource_full?
+          expiration_ms = expiration * 1000 if expiration
           @gapi.time_partitioning ||= Google::Apis::BigqueryV2::TimePartitioning.new
-          @gapi.time_partitioning.expiration_ms = expiration * 1000
+          @gapi.time_partitioning.expiration_ms = expiration_ms
           patch_gapi! :time_partitioning
         end
 
@@ -461,8 +471,13 @@ module Google
         ###
         # Checks if the table is clustered.
         #
+        # See {Table::Updater#clustering_fields=}, {Table#clustering_fields} and
+        # {Table#clustering_fields=}.
+        #
         # @see https://cloud.google.com/bigquery/docs/clustered-tables
-        #   Introduction to Clustered Tables
+        #   Introduction to clustered tables
+        # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+        #   Creating and using clustered tables
         #
         # @return [Boolean, nil] `true` when the table is clustered, or
         #   `false` otherwise, if the object is a resource (see {#resource?});
@@ -481,14 +496,16 @@ module Google
         # first partitioned and subsequently clustered. The order of the
         # returned fields determines the sort order of the data.
         #
-        # See {Table::Updater#clustering_fields=}.
+        # BigQuery supports clustering for both partitioned and non-partitioned
+        # tables.
+        #
+        # See {Table::Updater#clustering_fields=}, {Table#clustering_fields=} and
+        # {Table#clustering?}.
         #
-        # @see https://cloud.google.com/bigquery/docs/partitioned-tables
-        #   Partitioned Tables
         # @see https://cloud.google.com/bigquery/docs/clustered-tables
-        #   Introduction to Clustered Tables
+        #   Introduction to clustered tables
         # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
-        #   Creating and Using Clustered Tables
+        #   Creating and using clustered tables
         #
         # @return [Array<String>, nil] The clustering fields, or `nil` if the
         #   table is not clustered or if the table is a reference (see
@@ -502,6 +519,53 @@ module Google
           @gapi.clustering.fields if clustering?
         end
 
+        ##
+        # Updates the list of fields on which data should be clustered.
+        #
+        # Only top-level, non-repeated, simple-type fields are supported. When
+        # you cluster a table using multiple columns, the order of columns you
+        # specify is important. The order of the specified columns determines
+        # the sort order of the data.
+        #
+        # BigQuery supports clustering for both partitioned and non-partitioned
+        # tables.
+        #
+        # See {Table::Updater#clustering_fields=}, {Table#clustering_fields} and
+        # {Table#clustering?}.
+        #
+        # @see https://cloud.google.com/bigquery/docs/clustered-tables
+        #   Introduction to clustered tables
+        # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
+        #   Creating and using clustered tables
+        # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables#modifying-cluster-spec
+        #   Modifying clustering specification
+        #
+        # @param [Array<String>, nil] fields The clustering fields, or `nil` to
+        #   remove the clustering configuration. Only top-level, non-repeated,
+        #   simple-type fields are supported.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #   table = dataset.table "my_table"
+        #
+        #   table.clustering_fields = ["last_name", "first_name"]
+        #
+        # @!group Attributes
+        #
+        def clustering_fields= fields
+          reload! unless resource_full?
+          if fields
+            @gapi.clustering ||= Google::Apis::BigqueryV2::Clustering.new
+            @gapi.clustering.fields = fields
+          else
+            @gapi.clustering = nil
+          end
+          patch_gapi! :clustering
+        end
+
         ##
         # The combined Project ID, Dataset ID, and Table ID for this table, in
         # the format specified by the [Legacy SQL Query
@@ -726,7 +790,7 @@ module Google
         end
 
         ##
-        # Checks if the table's type is "TABLE".
+        # Checks if the table's type is `TABLE`.
         #
         # @return [Boolean, nil] `true` when the type is `TABLE`, `false`
         #   otherwise, if the object is a resource (see {#resource?}); `nil` if
@@ -740,8 +804,10 @@ module Google
         end
 
         ##
-        # Checks if the table's type is "VIEW", indicating that the table
-        # represents a BigQuery view. See {Dataset#create_view}.
+        # Checks if the table's type is `VIEW`, indicating that the table
+        # represents a BigQuery logical view. See {Dataset#create_view}.
+        #
+        # @see https://cloud.google.com/bigquery/docs/views Creating views
         #
         # @return [Boolean, nil] `true` when the type is `VIEW`, `false`
         #   otherwise, if the object is a resource (see {#resource?}); `nil` if
@@ -755,7 +821,25 @@ module Google
         end
 
         ##
-        # Checks if the table's type is "EXTERNAL", indicating that the table
+        # Checks if the table's type is `MATERIALIZED_VIEW`, indicating that
+        # the table represents a BigQuery materialized view.
+        # See {Dataset#create_materialized_view}.
+        #
+        # @see https://cloud.google.com/bigquery/docs/materialized-views-intro Introduction to materialized views
+        #
+        # @return [Boolean, nil] `true` when the type is `MATERIALIZED_VIEW`,
+        #   `false` otherwise, if the object is a resource (see {#resource?});
+        #   `nil` if the object is a reference (see {#reference?}).
+        #
+        # @!group Attributes
+        #
+        def materialized_view?
+          return nil if reference?
+          @gapi.type == "MATERIALIZED_VIEW"
+        end
+
+        ##
+        # Checks if the table's type is `EXTERNAL`, indicating that the table
         # represents an External Data Source. See {#external?} and
         # {External::DataSource}.
         #
@@ -1138,21 +1222,24 @@ module Google
         end
 
         ##
-        # The query that executes each time the view is loaded.
+        # The query that defines the view or materialized view. See {#view?} and
+        # {#materialized_view?}.
         #
-        # @return [String] The query that defines the view.
+        # @return [String, nil] The query that defines the view or materialized_view;
+        #   or `nil` if not a view or materialized view.
         #
         # @!group Attributes
         #
         def query
-          @gapi.view&.query
+          view? ? @gapi.view&.query : @gapi.materialized_view&.query
         end
 
         ##
-        # Updates the query that executes each time the view is loaded.
+        # Updates the query that defines the view. (See {#view?}.) Not supported
+        # for materialized views.
         #
-        # This sets the query using standard SQL. To specify legacy SQL or to
-        # use user-defined function resources use (#set_query) instead.
+        # This method sets the query using standard SQL. To specify legacy SQL or
+        # to use user-defined function resources for a view, use (#set_query) instead.
         #
         # @see https://cloud.google.com/bigquery/query-reference BigQuery Query
         #   Reference
@@ -1167,7 +1254,7 @@ module Google
         #   view = dataset.table "my_view"
         #
         #   view.query = "SELECT first_name FROM " \
-        #                  "`my_project.my_dataset.my_table`"
+        #                "`my_project.my_dataset.my_table`"
         #
         # @!group Lifecycle
         #
@@ -1176,12 +1263,12 @@ module Google
         end
 
         ##
-        # Updates the query that executes each time the view is loaded. Allows
-        # setting of standard vs. legacy SQL and user-defined function
-        # resources.
+        # Updates the query that defines the view. (See {#view?}.) Not supported for
+        # materialized views.
         #
-        # @see https://cloud.google.com/bigquery/query-reference BigQuery Query
-        #   Reference
+        # Allows setting of standard vs. legacy SQL and user-defined function resources.
+        #
+        # @see https://cloud.google.com/bigquery/query-reference BigQuery Query Reference
         #
         # @param [String] query The query that defines the view.
         # @param [Boolean] standard_sql Specifies whether to use BigQuery's
@@ -1193,11 +1280,12 @@ 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 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.
+        #   used in a legacy SQL query. Optional.
+        #
+        #   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.
         #
         #   This parameter is used for defining User Defined Function (UDF)
         #   resources only when using legacy SQL. Users of standard SQL should
@@ -1208,7 +1296,7 @@ module Google
         #   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)
         #
-        # @example
+        # @example Update a view:
         #   require "google/cloud/bigquery"
         #
         #   bigquery = Google::Cloud::Bigquery.new
@@ -1216,12 +1304,13 @@ module Google
         #   view = dataset.table "my_view"
         #
         #   view.set_query "SELECT first_name FROM " \
-        #                    "`my_project.my_dataset.my_table`",
+        #                  "`my_project.my_dataset.my_table`",
         #                  standard_sql: true
         #
         # @!group Lifecycle
         #
         def set_query query, standard_sql: nil, legacy_sql: nil, udfs: nil
+          raise "Updating the query is not supported for Table type: #{@gapi.type}" unless view?
           use_legacy_sql = Convert.resolve_legacy_sql standard_sql, legacy_sql
           @gapi.view = Google::Apis::BigqueryV2::ViewDefinition.new(
             query:                           query,
@@ -1232,26 +1321,28 @@ module Google
         end
 
         ##
-        # Checks if the view's query is using legacy sql.
+        # Checks if the view's query is using legacy sql. See {#view?}.
         #
-        # @return [Boolean] `true` when legacy sql is used, `false` otherwise.
+        # @return [Boolean] `true` when legacy sql is used, `false` otherwise; or `nil` if not a logical view.
         #
         # @!group Attributes
         #
         def query_legacy_sql?
+          return nil unless @gapi.view
           val = @gapi.view.use_legacy_sql
           return true if val.nil?
           val
         end
 
         ##
-        # Checks if the view's query is using standard sql.
+        # Checks if the view's query is using standard sql. See {#view?}.
         #
         # @return [Boolean] `true` when standard sql is used, `false` otherwise.
         #
         # @!group Attributes
         #
         def query_standard_sql?
+          return nil unless @gapi.view
           !query_legacy_sql?
         end
 
@@ -1263,18 +1354,92 @@ module Google
         # 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).
+        # See {#view?}.
         #
-        # @return [Array<String>] An array containing Google Cloud Storage URIs
-        #   and/or inline source code.
+        # @return [Array<String>, nil] An array containing Google Cloud Storage URIs
+        #   and/or inline source code, or `nil` if not a logical view.
         #
         # @!group Attributes
         #
         def query_udfs
+          return nil unless @gapi.view
           udfs_gapi = @gapi.view.user_defined_function_resources
           return [] if udfs_gapi.nil?
           Array(udfs_gapi).map { |udf| udf.inline_code || udf.resource_uri }
         end
 
+        ##
+        # Whether automatic refresh of the materialized view is enabled. When true,
+        # the materialized view is updated when the base table is updated. The default
+        # value is true. See {#materialized_view?}.
+        #
+        # @return [Boolean, nil] `true` when automatic refresh is enabled, `false` otherwise;
+        #   or `nil` if not a materialized view.
+        #
+        # @!group Attributes
+        #
+        def enable_refresh?
+          return nil unless @gapi.materialized_view
+          val = @gapi.materialized_view.enable_refresh
+          return true if val.nil?
+          val
+        end
+
+        ##
+        # Sets whether automatic refresh of the materialized view is enabled. When true,
+        # the materialized view is updated when the base table is updated. See {#materialized_view?}.
+        #
+        # @param [Boolean] new_enable_refresh `true` when automatic refresh is enabled, `false` otherwise.
+        #
+        # @!group Attributes
+        #
+        def enable_refresh= new_enable_refresh
+          @gapi.materialized_view = Google::Apis::BigqueryV2::MaterializedViewDefinition.new(
+            enable_refresh: new_enable_refresh
+          )
+          patch_gapi! :materialized_view
+        end
+
+        ##
+        # The time when the materialized view was last modified.
+        # See {#materialized_view?}.
+        #
+        # @return [Time, nil] The time, or `nil` if not present or not a materialized view.
+        #
+        # @!group Attributes
+        #
+        def last_refresh_time
+          Convert.millis_to_time @gapi.materialized_view&.last_refresh_time
+        end
+
+        ##
+        # The maximum frequency in milliseconds at which the materialized view will be refreshed.
+        # See {#materialized_view?}.
+        #
+        # @return [Integer, nil] The maximum frequency in milliseconds;
+        #   or `nil` if not a materialized view.
+        #
+        # @!group Attributes
+        #
+        def refresh_interval_ms
+          @gapi.materialized_view&.refresh_interval_ms
+        end
+
+        ##
+        # Sets the maximum frequency at which the materialized view will be refreshed.
+        # See {#materialized_view?}.
+        #
+        # @param [Integer] new_refresh_interval_ms The maximum frequency in milliseconds.
+        #
+        # @!group Attributes
+        #
+        def refresh_interval_ms= new_refresh_interval_ms
+          @gapi.materialized_view = Google::Apis::BigqueryV2::MaterializedViewDefinition.new(
+            refresh_interval_ms: new_refresh_interval_ms
+          )
+          patch_gapi! :materialized_view
+        end
+
         ##
         # Gets the Cloud IAM access control policy for the table. The latest policy will be read from the service. See
         # also {#update_policy}.
@@ -2195,6 +2360,21 @@ module Google
         # 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`                               |                                                    |
+        # | `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
@@ -2208,7 +2388,10 @@ module Google
         #   BigQuery Troubleshooting: Metadata errors for streaming inserts
         #
         # @param [Hash, Array<Hash>] rows A hash object or array of hash objects
-        #   containing the data. Required.
+        #   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
@@ -2251,6 +2434,19 @@ module Google
         #   ]
         #   table.insert rows
         #
+        # @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"
+        #   table = dataset.table "my_table"
+        #
+        #   row = {
+        #     "my_numeric" => BigDecimal("123456798.987654321"),
+        #     "my_bignumeric" => "123456798.98765432100001" # BigDecimal would be rounded, use String instead!
+        #   }
+        #   table.insert row
+        #
         # @!group Data
         #
         def insert rows, insert_ids: nil, skip_invalid: nil, ignore_unknown: nil
@@ -2264,8 +2460,12 @@ module Google
           end
 
           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
 
@@ -2564,7 +2764,7 @@ module Google
           return if attributes.empty?
           ensure_service!
           patch_args = Hash[attributes.map { |attr| [attr, @gapi.send(attr)] }]
-          patch_gapi = Google::Apis::BigqueryV2::Table.new patch_args
+          patch_gapi = Google::Apis::BigqueryV2::Table.new(**patch_args)
           patch_gapi.etag = etag if etag
           @gapi = service.patch_table dataset_id, table_id, patch_gapi
 
@@ -2690,12 +2890,11 @@ 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
@@ -2748,6 +2947,7 @@ module Google
           ##
           # @private Create an Updater object.
           def initialize gapi
+            super()
             @updates = []
             @gapi = gapi
             @schema = nil
@@ -2916,27 +3116,22 @@ module Google
           end
 
           ##
-          # Sets one or more fields on which data should be clustered. Must be
-          # specified with time-based partitioning, data in the table will be
-          # first partitioned and subsequently clustered.
+          # Sets the list of fields on which data should be clustered.
           #
           # Only top-level, non-repeated, simple-type fields are supported. When
           # you cluster a table using multiple columns, the order of columns you
           # specify is important. The order of the specified columns determines
           # the sort order of the data.
           #
-          # You can only set the clustering fields while creating a table as in
-          # the example below. BigQuery does not allow you to change clustering
-          # on an existing table.
+          # BigQuery supports clustering for both partitioned and non-partitioned
+          # tables.
           #
-          # See {Table#clustering_fields}.
+          # See {Table#clustering_fields} and {Table#clustering_fields=}.
           #
-          # @see https://cloud.google.com/bigquery/docs/partitioned-tables
-          #   Partitioned Tables
           # @see https://cloud.google.com/bigquery/docs/clustered-tables
-          #   Introduction to Clustered Tables
+          #   Introduction to clustered tables
           # @see https://cloud.google.com/bigquery/docs/creating-clustered-tables
-          #   Creating and Using Clustered Tables
+          #   Creating and using clustered tables
           #
           # @param [Array<String>] fields The clustering fields. Only top-level,
           #   non-repeated, simple-type fields are supported.
@@ -3115,9 +3310,18 @@ module Google
           end
 
           ##
-          # Adds a numeric number field to the schema. Numeric is a
-          # fixed-precision numeric type with 38 decimal digits, 9 that follow
-          # the decimal point.
+          # Adds a numeric number field to the schema. `NUMERIC` is a decimal
+          # type with fixed precision and scale. Precision is the number of
+          # digits that the number contains. Scale is how many of these
+          # digits appear after the decimal point. It supports:
+          #
+          # Precision: 38
+          # Scale: 9
+          # Min: -9.9999999999999999999999999999999999999E+28
+          # Max: 9.9999999999999999999999999999999999999E+28
+          #
+          # This type can represent decimal fractions exactly, and is suitable
+          # for financial calculations.
           #
           # See {Schema#numeric}
           #
@@ -3144,6 +3348,45 @@ module Google
             schema.numeric name, description: description, mode: mode
           end
 
+          ##
+          # Adds a bignumeric number field to the schema. `BIGNUMERIC` is a
+          # decimal type with fixed precision and scale. Precision is the
+          # number of digits that the number contains. Scale is how many of
+          # these digits appear after the decimal point. It supports:
+          #
+          # Precision: 76.76 (the 77th digit is partial)
+          # Scale: 38
+          # Min: -5.7896044618658097711785492504343953926634992332820282019728792003956564819968E+38
+          # Max: 5.7896044618658097711785492504343953926634992332820282019728792003956564819967E+38
+          #
+          # This type can represent decimal fractions exactly, and is suitable
+          # for financial calculations.
+          #
+          # See {Schema#bignumeric}
+          #
+          # @param [String] name The field name. The name must contain only
+          #   letters (a-z, A-Z), numbers (0-9), or underscores (_), and must
+          #   start with a letter or underscore. The maximum length is 128
+          #   characters.
+          # @param [String] description A description of the field.
+          # @param [Symbol] mode The field's mode. The possible values are
+          #   `:nullable`, `:required`, and `:repeated`. The default value is
+          #   `:nullable`.
+          #
+          # @example
+          #   require "google/cloud/bigquery"
+          #
+          #   bigquery = Google::Cloud::Bigquery.new
+          #   dataset = bigquery.dataset "my_dataset"
+          #   table = dataset.create_table "my_table" do |schema|
+          #     schema.bignumeric "total_cost", mode: :required
+          #   end
+          #
+          # @!group Schema
+          def bignumeric name, description: nil, mode: :nullable
+            schema.bignumeric name, description: description, mode: mode
+          end
+
           ##
           # Adds a boolean field to the schema.
           #