google-cloud-bigquery 1.27.0 → 1.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 334d37be375f513da083f7338e1324413409a6c30554456c08290ed1337c2701
-  data.tar.gz: f21c7793b5a9f82d0c3840aa5915fd10ef43644ccc1d9ea996a63860fa8b16ed
+  metadata.gz: 44443c8c7fdf80fdfc611bba7ffcad2469ef60ff3aef8899f56a07fb4ced8555
+  data.tar.gz: 3b3f3020b6c4eebfa1a2a974f6d047068bd5d7f114b5d8c843c31401108b15b1
 SHA512:
-  metadata.gz: 187d0549552613c40f85001fdf82197db01af5b5e285dfd6f7615a64c62ed74807c0ea31ac560d2a1516dae0c91f14fcc08b143882fcf8437b8d7c964f256348
-  data.tar.gz: e6b80ed9ccff8ffb2f8537a009a6d41a7930ee080f50800001b0afa9f7706a85af58180d091051f34a2499d66ca15f5c084a74cbbff244d8c22d266fc62713db
+  metadata.gz: 5fb27c2d28ebb83a3f28a11241b7b260373dceade40159df44e31d6ab5de016079a00ddeba6943a09a6c7f8d303d08a24ca665160cd480b95f314382c2e45943
+  data.tar.gz: cf98a8d90c55cf065265c094a74ccf9f421a89e1c459b05189d4a7b33c8d97c9304c0e7256729de190a9bc7f74195fd6cff9170748cfb3bc4732a297f902b320

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Release History
 
+### 1.28.0 / 2021-03-09
+
+#### Features
+
+* Add Materialized View support
+  * Add Dataset#create_materialized_view
+  * Add Table#materialized_view?
+  * Add Table#enable_refresh?
+  * Add Table#enable_refresh=
+  * Add Table#last_refresh_time
+  * Add Table#refresh_interval_ms
+  * Add Table#refresh_interval_ms=
+
 ### 1.27.0 / 2021-02-10
 
 #### Features

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

@@ -618,15 +618,17 @@ module Google
         end
 
         ##
-        # Creates a new [view](https://cloud.google.com/bigquery/docs/views)
-        # table, which is a virtual table defined by the given SQL query.
+        # Creates a new view, which is a virtual table defined by the given SQL query.
         #
-        # BigQuery's views are logical views, not materialized views, which
-        # means that the query that defines the view is re-executed every time
-        # the view is queried. Queries are billed according to the total amount
+        # With BigQuery's logical views, the query that defines the view is re-executed
+        # every time the view is queried. Queries are billed according to the total amount
         # of data in all table fields referenced directly or indirectly by the
         # top-level query. (See {Table#view?} and {Table#query}.)
         #
+        # For materialized views, see {#create_materialized_view}.
+        #
+        # @see https://cloud.google.com/bigquery/docs/views Creating views
+        #
         # @param [String] table_id The ID of the view table. The ID must contain
         #   only letters (a-z, A-Z), numbers (0-9), or underscores (_). The
         #   maximum length is 1,024 characters.
@@ -667,7 +669,7 @@ module Google
         #   dataset = bigquery.dataset "my_dataset"
         #
         #   view = dataset.create_view "my_view",
-        #             "SELECT name, age FROM proj.dataset.users"
+        #                              "SELECT name, age FROM proj.dataset.users"
         #
         # @example A name and description can be provided:
         #   require "google/cloud/bigquery"
@@ -676,13 +678,18 @@ module Google
         #   dataset = bigquery.dataset "my_dataset"
         #
         #   view = dataset.create_view "my_view",
-        #             "SELECT name, age FROM proj.dataset.users",
-        #             name: "My View", description: "This is my view"
+        #                              "SELECT name, age FROM proj.dataset.users",
+        #                              name: "My View", description: "This is my view"
         #
         # @!group Table
         #
-        def create_view table_id, query, name: nil, description: nil,
-                        standard_sql: nil, legacy_sql: nil, udfs: nil
+        def create_view table_id,
+                        query,
+                        name: nil,
+                        description: nil,
+                        standard_sql: nil,
+                        legacy_sql: nil,
+                        udfs: nil
           use_legacy_sql = Convert.resolve_legacy_sql standard_sql, legacy_sql
           new_view_opts = {
             table_reference: Google::Apis::BigqueryV2::TableReference.new(
@@ -704,6 +711,80 @@ module Google
           Table.from_gapi gapi, service
         end
 
+        ##
+        # Creates a new materialized view.
+        #
+        # Materialized views are precomputed views that periodically cache results of a query for increased performance
+        # and efficiency. BigQuery leverages precomputed results from materialized views and whenever possible reads
+        # only delta changes from the base table to compute up-to-date results.
+        #
+        # Queries that use materialized views are generally faster and consume less resources than queries that retrieve
+        # the same data only from the base table. Materialized views are helpful to significantly boost performance of
+        # workloads that have the characteristic of common and repeated queries.
+        #
+        # For logical views, see {#create_view}.
+        #
+        # @see https://cloud.google.com/bigquery/docs/materialized-views-intro Introduction to materialized views
+        #
+        # @param [String] table_id The ID of the materialized view table. The ID must contain only letters (a-z, A-Z),
+        #   numbers (0-9), or underscores (_). The maximum length is 1,024 characters.
+        # @param [String] query The query that BigQuery executes when the materialized view is referenced.
+        # @param [String] name A descriptive name for the table.
+        # @param [String] description A user-friendly description of the table.
+        # @param [Boolean] enable_refresh Enable automatic refresh of the materialized view when the base table is
+        #   updated. Optional. The default value is true.
+        # @param [Integer] refresh_interval_ms The maximum frequency in milliseconds at which this materialized view
+        #   will be refreshed. Optional. The default value is `1_800_000` (30 minutes).
+        #
+        # @return [Google::Cloud::Bigquery::Table] A new table object.
+        #
+        # @example
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   materialized_view = dataset.create_materialized_view "my_materialized_view",
+        #                                                        "SELECT name, age FROM proj.dataset.users"
+        #
+        # @example Automatic refresh can be disabled:
+        #   require "google/cloud/bigquery"
+        #
+        #   bigquery = Google::Cloud::Bigquery.new
+        #   dataset = bigquery.dataset "my_dataset"
+        #
+        #   materialized_view = dataset.create_materialized_view "my_materialized_view",
+        #                                                        "SELECT name, age FROM proj.dataset.users",
+        #                                                        enable_refresh: false
+        #
+        # @!group Table
+        #
+        def create_materialized_view table_id,
+                                     query,
+                                     name: nil,
+                                     description: nil,
+                                     enable_refresh: nil,
+                                     refresh_interval_ms: nil
+          new_view_opts = {
+            table_reference:   Google::Apis::BigqueryV2::TableReference.new(
+              project_id: project_id,
+              dataset_id: dataset_id,
+              table_id:   table_id
+            ),
+            friendly_name:     name,
+            description:       description,
+            materialized_view: Google::Apis::BigqueryV2::MaterializedViewDefinition.new(
+              enable_refresh:      enable_refresh,
+              query:               query,
+              refresh_interval_ms: refresh_interval_ms
+            )
+          }.delete_if { |_, v| v.nil? }
+          new_view = Google::Apis::BigqueryV2::Table.new new_view_opts
+
+          gapi = service.insert_table dataset_id, new_view
+          Table.from_gapi gapi, service
+        end
+
         ##
         # Retrieves an existing table by ID.
         #
@@ -2756,6 +2837,12 @@ module Google
             raise "not implemented in #{self.class}"
           end
 
+          ##
+          # @raise [RuntimeError] not implemented
+          def create_materialized_view(*)
+            raise "not implemented in #{self.class}"
+          end
+
           ##
           # @raise [RuntimeError] not implemented
           def table(*)

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

@@ -981,8 +981,7 @@ module Google
         # @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`.

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.
@@ -726,7 +735,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 +749,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 +766,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 +1167,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 +1199,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 +1208,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 +1225,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 +1241,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 +1249,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 +1266,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 +1299,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}.

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Bigquery
-      VERSION = "1.27.0".freeze
+      VERSION = "1.28.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-bigquery
 version: !ruby/object:Gem::Version
-  version: 1.27.0
+  version: 1.28.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-10 00:00:00.000000000 Z
+date: 2021-03-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -291,7 +291,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.6
+rubygems_version: 3.2.13
 signing_key: 
 specification_version: 4
 summary: API Client library for Google BigQuery