google-cloud-bigtable 0.6.2 → 1.0.2

data/lib/google/cloud/bigtable/admin/v2/doc/google/type/expr.rb

@@ -1,4 +1,4 @@
-# Copyright 2019 Google LLC
+# Copyright 2020 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

data/lib/google/cloud/bigtable/app_profile.rb

@@ -17,10 +17,12 @@
 
 require "google/cloud/bigtable/app_profile/list"
 require "google/cloud/bigtable/app_profile/job"
+require "google/cloud/bigtable/routing_policy"
 
 module Google
   module Cloud
     module Bigtable
+      ##
       # # AppProfile
       #
       # A configuration object describing how Cloud Bigtable should treat traffic
@@ -33,7 +35,7 @@ module Google
       #
       #   instance = bigtable.instance("my-instance")
       #
-      #   app_profile = bigtable.app_profile("my-instance", "my-app-profile")
+      #   app_profile = instance.app_profile("my-app-profile")
       #
       #   # Update
       #   app_profile.description = "User data instance app profile"
@@ -58,88 +60,115 @@ module Google
           @changed_fields = {}
         end
 
-        # The unique identifier for the project.
+        ##
+        # The unique identifier for the project to which the app profile belongs.
         #
         # @return [String]
+        #
         def project_id
           @grpc.name.split("/")[1]
         end
 
-        # The unique identifier for the instance.
+        ##
+        # The unique identifier for the instance to which the app profile belongs.
         #
         # @return [String]
+        #
         def instance_id
           @grpc.name.split("/")[3]
         end
 
+        ##
         # The unique identifier for the app profile.
         #
         # @return [String]
+        #
         def name
           @grpc.name.split("/")[5]
         end
 
-        # The full path for the instance resource. Values are of the form
-        # `projects/<project_id>/instances/<instance_id>`.
+        ##
+        # The full path for the app profile resource. Values are of the form:
+        # `projects/<project_id>/instances/<instance_id>/appProfiles/<app_profile_name>`.
         #
         # @return [String]
+        #
         def path
           @grpc.name
         end
 
+        ##
         # Etag for optimistic concurrency control.
         #
         # @return [String]
+        #
         def etag
           @grpc.etag
         end
 
-        # Description of the AppProfile.
+        ##
+        # Description of the app profile.
         #
         # @return [String]
+        #
         def description
           @grpc.description
         end
 
-        # Set description of the AppProfile.
+        ##
+        # Sets the description of the app profile.
         #
         # @param text [String] Description text
+        #
         def description= text
           @grpc.description = text
           @changed_fields["description"] = "description"
         end
 
-        # Get value of multi-cluster routing policy.
+        ##
+        # Gets the multi-cluster routing policy, if present.
+        #
+        # @return [Google::Cloud::Bigtable::MultiClusterRoutingUseAny, nil]
         #
-        # @return [Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
         def multi_cluster_routing
-          @grpc.multi_cluster_routing_use_any
+          return nil unless @grpc.multi_cluster_routing_use_any
+
+          Google::Cloud::Bigtable::MultiClusterRoutingUseAny.new
         end
 
-        # Get value of single cluster routing policy.
+        ##
+        # Gets the single cluster routing policy, if present.
+        #
+        # @return [Google::Cloud::Bigtable::SingleClusterRouting, nil]
         #
-        # @return [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting]
         def single_cluster_routing
-          @grpc.single_cluster_routing
+          return nil unless @grpc.single_cluster_routing
+
+          Google::Cloud::Bigtable::SingleClusterRouting.new(
+            @grpc.single_cluster_routing.cluster_id,
+            @grpc.single_cluster_routing.allow_transactional_writes
+          )
         end
 
-        # Set routing policy.
+        ##
+        # Sets the routing policy for the app profile.
         #
-        # @param policy [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting | Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
-        #   The routing policy for all read/write requests that use this app profile.
-        #   A value must be explicitly set.
+        # @param policy [Google::Cloud::Bigtable::RoutingPolicy]
+        #   The routing policy for all read/write requests that use this app profile. A value must be explicitly set.
         #
         #   Routing Policies:
-        #   * `multi_cluster_routing` - Read/write requests may be routed to any
-        #     cluster in the instance and will fail over to another cluster in the event
-        #     of transient errors or delays. Choosing this option sacrifices
-        #     read-your-writes consistency to improve availability.
-        #   * `single_cluster_routing` - Unconditionally routes all read/write requests
-        #     to a specific cluster. This option preserves read-your-writes consistency
-        #     but does not improve availability.
-        #     The value contains `cluster_id` and optional field `allow_transactional_writes`.
-        #
-        # @example Set multi cluster routing policy
+        #   * {Google::Cloud::Bigtable::MultiClusterRoutingUseAny} - Read/write
+        #     requests may be routed to any cluster in the instance and will
+        #     fail over to another cluster in the event of transient errors or
+        #     delays. Choosing this option sacrifices read-your-writes
+        #     consistency to improve availability.
+        #   * {Google::Cloud::Bigtable::SingleClusterRouting} - Unconditionally
+        #     routes all read/write requests to a specific cluster. This option
+        #     preserves read-your-writes consistency but does not improve
+        #     availability. Value contains `cluster_id` and optional field
+        #     `allow_transactional_writes`.
+        #
+        # @example Set multi cluster routing policy.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -149,7 +178,7 @@ module Google
         #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
         #   app_profile.routing_policy = routing_policy
         #
-        # @example Set single cluster routing policy
+        # @example Set single cluster routing policy.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -157,31 +186,62 @@ module Google
         #   app_profile = instance.app_profile("my-app-profile")
         #
         #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
-        #     "my-instance-cluster-1"
+        #     "my-instance-cluster-1",
         #     allow_transactional_writes: true
         #   )
         #   app_profile.routing_policy = routing_policy
         #
         def routing_policy= policy
-          if policy.is_a?(Google::Bigtable::Admin::V2::AppProfile:: \
-              SingleClusterRouting)
-            @grpc.single_cluster_routing = policy
+          routing_policy_grpc = policy.to_grpc
+          if routing_policy_grpc.is_a? Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting
+            @grpc.single_cluster_routing = routing_policy_grpc
             @changed_fields["routing_policy"] = "single_cluster_routing"
           else
-            @grpc.multi_cluster_routing_use_any = policy
+            @grpc.multi_cluster_routing_use_any = routing_policy_grpc
             @changed_fields["routing_policy"] = "multi_cluster_routing_use_any"
           end
         end
 
-        # Get routing policy.
+        ##
+        # Gets the routing policy for all read/write requests that use the app
+        # profile.
+        #
+        # Routing Policies:
+        # * {Google::Cloud::Bigtable::MultiClusterRoutingUseAny} - Read/write
+        #   requests may be routed to any cluster in the instance and will
+        #   fail over to another cluster in the event of transient errors or
+        #   delays. Choosing this option sacrifices read-your-writes
+        #   consistency to improve availability.
+        # * {Google::Cloud::Bigtable::SingleClusterRouting} - Unconditionally
+        #   routes all read/write requests to a specific cluster. This option
+        #   preserves read-your-writes consistency but does not improve
+        #   availability. Value contains `cluster_id` and optional field
+        #   `allow_transactional_writes`.
+        #
+        # @return [Google::Cloud::Bigtable::RoutingPolicy]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   instance = bigtable.instance("my-instance")
+        #
+        #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
         #
-        # @return [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting, Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
+        #   app_profile = instance.create_app_profile(
+        #     "my-app-profile",
+        #     routing_policy,
+        #     description: "App profile for user data instance"
+        #   )
+        #   puts app_profile.routing_policy
         #
         def routing_policy
-          @grpc.single_cluster_routing || @grpc.multi_cluster_routing_use_any
+          single_cluster_routing || multi_cluster_routing
         end
 
-        # Delete app profile.
+        ##
+        # Deletes the app profile.
         #
         # @param ignore_warnings [Boolean]
         #   Default value is false. If true, ignore safety checks when deleting
@@ -194,7 +254,8 @@ module Google
         #   bigtable = Google::Cloud::Bigtable.new
         #
         #   instance = bigtable.instance("my-instance")
-        #   app_profile = bigtable.instance("my-app-profile")
+        #
+        #   app_profile = instance.app_profile("my-app-profile")
         #
         #   app_profile.delete(ignore_warnings: true) # Ignore warnings.
         #
@@ -203,27 +264,26 @@ module Google
         #
         def delete ignore_warnings: false
           ensure_service!
-          service.delete_app_profile(
-            instance_id,
-            name,
-            ignore_warnings: ignore_warnings
-          )
+          service.delete_app_profile instance_id, name, ignore_warnings: ignore_warnings
           true
         end
 
-        # Update app profile.
+        ##
+        # Updates the app profile.
         #
         # @param ignore_warnings [Boolean]
         #   Default value is false. If true, ignore safety checks when updating
         #   the app profile.
         # @return [Google::Cloud::Bigtable::AppProfile::Job]
         #
-        # @example Update
+        # @example
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   app_profile = bigtable.app_profile("my-app-profile")
+        #   instance = bigtable.instance("my-instance")
+        #
+        #   app_profile = instance.app_profile("my-app-profile")
         #
         #   app_profile.description = "User data instance app profile"
         #   app_profile.routing_policy = \
@@ -238,17 +298,13 @@ module Google
         #     app_profile = job.app_profile
         #   end
         #
-        #   # OR - Update with ignoring warnings.
-        #   job = app_profile.save(ignore_warnings: true)
-        #   job.wait_until_done!
-        #
-        # @example Update with single cluster routing
+        # @example Update with single cluster routing.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
         #   instance = bigtable.instance("my-instance")
-        #   app_profile = bigtable.instance("my-app-profile")
+        #   app_profile = instance.app_profile("my-app-profile")
         #
         #   app_profile.description = "User data instance app profile"
         #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
@@ -261,10 +317,6 @@ module Google
         #
         #   job.done? #=> false
         #   job.reload!
-        #   job.done? #=> false
-        #
-        #   # Reload job until completion.
-        #   job.wait_until_done!
         #   job.done? #=> true
         #
         #   if job.error?
@@ -273,52 +325,62 @@ module Google
         #     app_profile = job.app_profile
         #     puts app_profile.name
         #   end
-
+        #
         def save ignore_warnings: false
           ensure_service!
-          update_mask = Google::Protobuf::FieldMask.new(
-            paths: @changed_fields.values
-          )
-          grpc = service.update_app_profile(
-            @grpc,
-            update_mask,
-            ignore_warnings: ignore_warnings
-          )
+          update_mask = Google::Protobuf::FieldMask.new paths: @changed_fields.values
+          grpc = service.update_app_profile @grpc, update_mask, ignore_warnings: ignore_warnings
           @changed_fields.clear
-          AppProfile::Job.from_grpc(grpc, service)
+          AppProfile::Job.from_grpc grpc, service
         end
         alias update save
 
-        # Reload app profile information.
+        ##
+        # Reloads the app profile data.
         #
         # @return [Google::Cloud::Bigtable::AppProfile]
-
+        #
         def reload!
-          @grpc = service.get_app_profile(instance_id, name)
+          @grpc = service.get_app_profile instance_id, name
           self
         end
 
-        # Create instance of multi cluster routing policy.
+        ##
+        # Creates an instance of the multi cluster routing policy.
+        #
+        # Read/write requests may be routed to any cluster in the instance and
+        # will fail over to another cluster in the event of transient errors or
+        # delays. Choosing this option sacrifices read-your-writes consistency
+        # to improve availability.
         #
-        # Read/write requests may be routed to any cluster in the instance and will
-        # fail over to another cluster in the event of transient errors or delays.
-        # Choosing this option sacrifices read-your-writes consistency to improve
-        # availability.
-        # @return [Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny]
+        # @return [Google::Cloud::Bigtable::MultiClusterRoutingUseAny]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
         #
-        # @example Create instance of multi cluster routing
+        #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+        #   instance = bigtable.instance("my-instance")
+        #
+        #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+        #
+        #   app_profile = instance.create_app_profile(
+        #     "my-app-profile",
+        #     routing_policy,
+        #     description: "App profile for user data instance"
+        #   )
+        #   puts app_profile.routing_policy
         #
         def self.multi_cluster_routing
-          Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny.new
+          Google::Cloud::Bigtable::MultiClusterRoutingUseAny.new
         end
 
-        # Create instance of single cluster routing.
+        ##
+        # Creates an instance of the single cluster routing policy.
         #
         # Unconditionally routes all read/write requests to a specific cluster.
-        # This option preserves read-your-writes consistency but does not improve
-        # availability.
+        # This option preserves read-your-writes consistency but does not
+        # improve availability.
         #
         # @param cluster_id [String]
         #   The cluster to which read/write requests should be routed.
@@ -327,25 +389,29 @@ module Google
         #   allowed by this app profile. It is unsafe to send these requests to
         #   the same table/row/column in multiple clusters.
         #   Default value is false.
-        # @return [Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting]
+        # @return [Google::Cloud::Bigtable::SingleClusterRouting]
         #
-        # @example Create instance of single cluster routing
+        # @example
+        #   require "google/cloud/bigtable"
         #
-        #   Google::Cloud::Bigtable::AppProfile.single_cluster_routing("my-cluster")
+        #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   # With allowed transactional writes
-        #   Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
-        #     "my-cluster",
+        #   instance = bigtable.instance("my-instance")
+        #
+        #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
+        #     "my-instance-cluster-1",
         #     allow_transactional_writes: true
         #   )
-
-        def self.single_cluster_routing \
-            cluster_id,
-            allow_transactional_writes: false
-          Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting.new(
-            cluster_id: cluster_id,
-            allow_transactional_writes: allow_transactional_writes
-          )
+        #
+        #   app_profile = instance.create_app_profile(
+        #     "my-app-profile",
+        #     routing_policy,
+        #     description: "App profile for user data instance"
+        #   )
+        #   puts app_profile.routing_policy
+        #
+        def self.single_cluster_routing cluster_id, allow_transactional_writes: false
+          Google::Cloud::Bigtable::SingleClusterRouting.new cluster_id, allow_transactional_writes
         end
 
         # @private
@@ -356,7 +422,7 @@ module Google
         # @param service [Google::Cloud::Bigtable::Service]
         # @return [Google::Cloud::Bigtable::Table]
         def self.from_grpc grpc, service
-          new(grpc, service)
+          new grpc, service
         end
 
         protected