google-cloud-bigtable 0.6.1 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. checksums.yaml +4 -4
  2. data/AUTHENTICATION.md +4 -26
  3. data/CHANGELOG.md +85 -0
  4. data/CONTRIBUTING.md +1 -1
  5. data/OVERVIEW.md +388 -19
  6. data/lib/google-cloud-bigtable.rb +19 -22
  7. data/lib/google/bigtable/admin/v2/bigtable_table_admin_services_pb.rb +1 -1
  8. data/lib/google/bigtable/v2/bigtable_pb.rb +3 -0
  9. data/lib/google/bigtable/v2/bigtable_services_pb.rb +1 -1
  10. data/lib/google/cloud/bigtable.rb +11 -17
  11. data/lib/google/cloud/bigtable/admin.rb +1 -1
  12. data/lib/google/cloud/bigtable/admin/v2.rb +1 -1
  13. data/lib/google/cloud/bigtable/admin/v2/bigtable_table_admin_client.rb +1 -1
  14. data/lib/google/cloud/bigtable/admin/v2/doc/google/iam/v1/policy.rb +42 -21
  15. data/lib/google/cloud/bigtable/app_profile.rb +162 -96
  16. data/lib/google/cloud/bigtable/app_profile/job.rb +5 -8
  17. data/lib/google/cloud/bigtable/app_profile/list.rb +18 -12
  18. data/lib/google/cloud/bigtable/chunk_processor.rb +24 -36
  19. data/lib/google/cloud/bigtable/cluster.rb +45 -18
  20. data/lib/google/cloud/bigtable/cluster/job.rb +3 -7
  21. data/lib/google/cloud/bigtable/cluster/list.rb +22 -20
  22. data/lib/google/cloud/bigtable/column_family.rb +18 -231
  23. data/lib/google/cloud/bigtable/column_family_map.rb +426 -0
  24. data/lib/google/cloud/bigtable/column_range.rb +15 -7
  25. data/lib/google/cloud/bigtable/convert.rb +12 -4
  26. data/lib/google/cloud/bigtable/errors.rb +4 -1
  27. data/lib/google/cloud/bigtable/gc_rule.rb +188 -69
  28. data/lib/google/cloud/bigtable/instance.rb +209 -189
  29. data/lib/google/cloud/bigtable/instance/cluster_map.rb +17 -13
  30. data/lib/google/cloud/bigtable/instance/job.rb +6 -5
  31. data/lib/google/cloud/bigtable/instance/list.rb +18 -13
  32. data/lib/google/cloud/bigtable/longrunning_job.rb +7 -1
  33. data/lib/google/cloud/bigtable/mutation_entry.rb +36 -39
  34. data/lib/google/cloud/bigtable/mutation_operations.rb +90 -73
  35. data/lib/google/cloud/bigtable/policy.rb +9 -5
  36. data/lib/google/cloud/bigtable/project.rb +87 -196
  37. data/lib/google/cloud/bigtable/read_modify_write_rule.rb +15 -10
  38. data/lib/google/cloud/bigtable/read_operations.rb +42 -59
  39. data/lib/google/cloud/bigtable/routing_policy.rb +172 -0
  40. data/lib/google/cloud/bigtable/row.rb +32 -21
  41. data/lib/google/cloud/bigtable/row_filter.rb +80 -35
  42. data/lib/google/cloud/bigtable/row_filter/chain_filter.rb +119 -68
  43. data/lib/google/cloud/bigtable/row_filter/condition_filter.rb +8 -2
  44. data/lib/google/cloud/bigtable/row_filter/interleave_filter.rb +117 -66
  45. data/lib/google/cloud/bigtable/row_filter/simple_filter.rb +24 -9
  46. data/lib/google/cloud/bigtable/row_range.rb +5 -0
  47. data/lib/google/cloud/bigtable/rows_mutator.rb +14 -21
  48. data/lib/google/cloud/bigtable/rows_reader.rb +23 -18
  49. data/lib/google/cloud/bigtable/sample_row_key.rb +6 -3
  50. data/lib/google/cloud/bigtable/service.rb +200 -253
  51. data/lib/google/cloud/bigtable/status.rb +76 -0
  52. data/lib/google/cloud/bigtable/table.rb +158 -262
  53. data/lib/google/cloud/bigtable/table/cluster_state.rb +17 -6
  54. data/lib/google/cloud/bigtable/table/list.rb +16 -9
  55. data/lib/google/cloud/bigtable/v2.rb +1 -1
  56. data/lib/google/cloud/bigtable/v2/bigtable_client.rb +12 -12
  57. data/lib/google/cloud/bigtable/v2/doc/google/bigtable/v2/bigtable.rb +16 -13
  58. data/lib/google/cloud/bigtable/value_range.rb +19 -13
  59. data/lib/google/cloud/bigtable/version.rb +1 -1
  60. metadata +67 -25
  61. data/lib/google/cloud/bigtable/table/column_family_map.rb +0 -70
@@ -19,10 +19,12 @@ require "google/cloud/bigtable/mutation_entry"
19
19
  require "google/cloud/bigtable/row"
20
20
  require "google/cloud/bigtable/rows_mutator"
21
21
  require "google/cloud/bigtable/read_modify_write_rule"
22
+ require "google/cloud/bigtable/status"
22
23
 
23
24
  module Google
24
25
  module Cloud
25
26
  module Bigtable
27
+ ##
26
28
  # # MutationOperations
27
29
  #
28
30
  # Collection of mutations APIs.
@@ -33,30 +35,29 @@ module Google
33
35
  # * Check and mutate row
34
36
  #
35
37
  module MutationOperations
36
- # Mutate row.
37
- #
38
+ ##
38
39
  # Mutates a row atomically. Cells in the row are left
39
- # unchanged unless explicitly changed by +mutation+.
40
+ # unchanged unless explicitly changed by the mutations.
40
41
  # Changes to be atomically applied to the specified row. Entries are applied
41
42
  # in order, meaning that earlier mutations can be masked by later mutations.
42
- # Must contain at least one mutation entry and at most 100,000.
43
+ # Must contain at least one mutation and at most 100,000.
43
44
  #
44
45
  # @param entry [Google::Cloud::Bigtable::MutationEntry]
45
46
  # Mutation entry with row key and list of mutations.
46
47
  # @return [Boolean]
47
48
  # @example Single mutation on row.
48
- # require "google/cloud"
49
+ # require "google/cloud/bigtable"
49
50
  #
50
51
  # bigtable = Google::Cloud::Bigtable.new
51
52
  #
52
53
  # table = bigtable.table("my-instance", "my-table")
53
54
  #
54
- # entry = table.new_mutation_entry.new("user-1")
55
+ # entry = table.new_mutation_entry("user-1")
55
56
  # entry.set_cell("cf1", "field1", "XYZ")
56
57
  # table.mutate_row(entry)
57
58
  #
58
59
  # @example Multiple mutations on row.
59
- # require "google/cloud"
60
+ # require "google/cloud/bigtable"
60
61
  #
61
62
  # bigtable = Google::Cloud::Bigtable.new
62
63
  #
@@ -73,17 +74,13 @@ module Google
73
74
  # table.mutate_row(entry)
74
75
  #
75
76
  def mutate_row entry
76
- client.mutate_row(
77
- path,
78
- entry.row_key,
79
- entry.mutations,
80
- app_profile_id: @app_profile_id
81
- )
77
+ service.mutate_row path, entry.row_key, entry.mutations, app_profile_id: @app_profile_id
82
78
  true
83
79
  end
84
80
 
81
+ ##
85
82
  # Mutates multiple rows in a batch. Each individual row is mutated
86
- # atomically as in MutateRow, but the entire batch is not executed
83
+ # atomically as in #{mutate_row}, but the entire batch is not executed
87
84
  # atomically.
88
85
  #
89
86
  # @param entries [Array<Google::Cloud::Bigtable::MutationEntry>]
@@ -95,7 +92,7 @@ module Google
95
92
  # @return [Array<Google::Bigtable::V2::MutateRowsResponse::Entry>]
96
93
  #
97
94
  # @example
98
- # require "google/cloud"
95
+ # require "google/cloud/bigtable"
99
96
  #
100
97
  # bigtable = Google::Cloud::Bigtable.new
101
98
  #
@@ -104,12 +101,18 @@ module Google
104
101
  # entries = []
105
102
  # entries << table.new_mutation_entry("row-1").set_cell("cf1", "field1", "XYZ")
106
103
  # entries << table.new_mutation_entry("row-2").set_cell("cf1", "field1", "ABC")
107
- # table.mutate_row(entries)
104
+ # responses = table.mutate_rows(entries)
105
+ #
106
+ # responses.each do |response|
107
+ # puts response.status.description
108
+ # end
108
109
  #
109
110
  def mutate_rows entries
110
- RowsMutator.new(self, entries).apply_mutations
111
+ statuses = RowsMutator.new(self, entries).apply_mutations
112
+ statuses.map { |s| Response.from_grpc s }
111
113
  end
112
114
 
115
+ ##
113
116
  # Modifies a row atomically on the server. The method reads the latest
114
117
  # existing timestamp and value from the specified columns and writes a new
115
118
  # entry based on pre-defined read/modify/write rules. The new value for the
@@ -118,7 +121,8 @@ module Google
118
121
  #
119
122
  # @param key [String]
120
123
  # The row key of the row to which the read/modify/write rules should be applied.
121
- # @param rules [Google::Cloud::Bigtable::ReadModifyWriteRule, Array<Google::Cloud::Bigtable::ReadModifyWriteRule>]
124
+ # @param rules [Google::Cloud::Bigtable::ReadModifyWriteRule,
125
+ # Array<Google::Cloud::Bigtable::ReadModifyWriteRule>]
122
126
  # Rules specifying how the specified row's contents are to be transformed
123
127
  # into writes. Entries are applied in order, meaning that earlier rules will
124
128
  # affect the results of later ones.
@@ -152,13 +156,13 @@ module Google
152
156
  # puts row.cells
153
157
  #
154
158
  def read_modify_write_row key, rules
155
- res_row = client.read_modify_write_row(
159
+ res_row = service.read_modify_write_row(
156
160
  path,
157
161
  key,
158
162
  Array(rules).map(&:to_grpc),
159
163
  app_profile_id: @app_profile_id
160
164
  ).row
161
- row = Row.new(res_row.key)
165
+ row = Row.new res_row.key
162
166
 
163
167
  res_row.families.each do |family|
164
168
  family.columns.each do |column|
@@ -177,6 +181,7 @@ module Google
177
181
  row
178
182
  end
179
183
 
184
+ ##
180
185
  # Mutates a row atomically based on the output of a predicate reader filter.
181
186
  #
182
187
  # NOTE: Condition predicate filter is not supported.
@@ -203,7 +208,8 @@ module Google
203
208
  # Must contain at least one entry if +true_mutations+ is empty and at most
204
209
  # 100,000 entries.
205
210
  # @return [Boolean]
206
- # Predicate match or not status
211
+ # Predicate match or not status.
212
+ #
207
213
  # @example
208
214
  # require "google/cloud/bigtable"
209
215
  #
@@ -222,72 +228,35 @@ module Google
222
228
  # otherwise_mutations = Google::Cloud::Bigtable::MutationEntry.new
223
229
  # otherwise_mutations.delete_from_family("cf3")
224
230
  #
225
- # response = table.check_and_mutate_row(
231
+ # predicate_matched = table.check_and_mutate_row(
226
232
  # "user01",
227
233
  # predicate_filter,
228
234
  # on_match: on_match_mutations,
229
235
  # otherwise: otherwise_mutations
230
236
  # )
231
237
  #
232
- # if response
238
+ # if predicate_matched
233
239
  # puts "All predicates matched"
234
240
  # end
235
241
  #
236
- def check_and_mutate_row \
237
- key,
238
- predicate,
239
- on_match: nil,
240
- otherwise: nil
242
+ def check_and_mutate_row key, predicate, on_match: nil, otherwise: nil
241
243
  true_mutations = on_match.mutations if on_match
242
244
  false_mutations = otherwise.mutations if otherwise
243
- response = client.check_and_mutate_row(
245
+ response = service.check_and_mutate_row(
244
246
  path,
245
247
  key,
246
248
  predicate_filter: predicate.to_grpc,
247
- true_mutations: true_mutations,
248
- false_mutations: false_mutations,
249
- app_profile_id: @app_profile_id
249
+ true_mutations: true_mutations,
250
+ false_mutations: false_mutations,
251
+ app_profile_id: @app_profile_id
250
252
  )
251
253
  response.predicate_matched
252
254
  end
253
255
 
254
- # Read sample row keys.
255
- #
256
- # Returns a sample of row keys in the table. The returned row keys will
257
- # delimit contiguous sections of the table of approximately equal size. The
258
- # sections can be used to break up the data for distributed tasks like
259
- # MapReduces.
260
- #
261
- # @yieldreturn [Google::Cloud::Bigtable::SampleRowKey]
262
- # @return [:yields: sample_row_key]
263
- # Yield block for each processed SampleRowKey.
264
- #
265
- # @example
266
- # require "google/cloud"
267
- #
268
- # bigtable = Google::Cloud::Bigtable.new
269
- # table = bigtable.table("my-instance", "my-table")
270
- #
271
- # table.sample_row_keys.each do |sample_row_key|
272
- # p sample_row_key.key # user00116
273
- # p sample_row_key.offset # 805306368
274
- # end
275
- #
276
- def sample_row_keys
277
- return enum_for(:sample_row_keys) unless block_given?
278
-
279
- response = client.sample_row_keys(
280
- path,
281
- app_profile_id: @app_profile_id
282
- )
283
- response.each do |grpc|
284
- yield SampleRowKey.from_grpc(grpc)
285
- end
286
- end
287
-
288
- # Create an instance of mutation_entry
256
+ ##
257
+ # Creates a mutation entry instance.
289
258
  #
290
- # @param row_key [String] Row key. Optional
259
+ # @param row_key [String] Row key. Optional.
291
260
  # The row key of the row to which the mutation should be applied.
292
261
  # @return [Google::Cloud::Bigtable::MutationEntry]
293
262
  #
@@ -303,16 +272,17 @@ module Google
303
272
  # entry = table.new_mutation_entry
304
273
  #
305
274
  def new_mutation_entry row_key = nil
306
- Google::Cloud::Bigtable::MutationEntry.new(row_key)
275
+ Google::Cloud::Bigtable::MutationEntry.new row_key
307
276
  end
308
277
 
309
- # Create an instance of ReadModifyWriteRule to append or increment the value
278
+ ##
279
+ # Create a read/modify/write rule to append or increment the value
310
280
  # of the cell qualifier.
311
281
  #
312
282
  # @param family [String]
313
- # The name of the column family to which the read/modify/write should be applied.
283
+ # The name of the column family to which the read/modify/write rule should be applied.
314
284
  # @param qualifier [String]
315
- # The qualifier of the column to which the read/modify/write should be applied.
285
+ # The qualifier of the column to which the read/modify/write rule should be applied.
316
286
  # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]
317
287
  #
318
288
  # @example Create rule to append to qualifier value.
@@ -332,7 +302,54 @@ module Google
332
302
  # rule.increment(100)
333
303
  #
334
304
  def new_read_modify_write_rule family, qualifier
335
- Google::Cloud::Bigtable::ReadModifyWriteRule.new(family, qualifier)
305
+ Google::Cloud::Bigtable::ReadModifyWriteRule.new family, qualifier
306
+ end
307
+
308
+ ##
309
+ # # MutationEntry::Response
310
+ #
311
+ # Represents a response message from BigtableService.MutateRows.
312
+ #
313
+ # @attr [Integer] index The index into the original request's `entries`
314
+ # list of the Entry for which a result is being reported.
315
+ # @attr [Google::Cloud::Bigtable::Status] The result of the request
316
+ # Entry identified by `index`. Depending on how requests are batched
317
+ # during execution, it is possible for one Entry to fail due to an
318
+ # error with another Entry. In the event that this occurs, the same
319
+ # error will be reported for both entries.
320
+ #
321
+ # @example
322
+ # require "google/cloud/bigtable"
323
+ #
324
+ # bigtable = Google::Cloud::Bigtable.new
325
+ #
326
+ # table = bigtable.table("my-instance", "my-table")
327
+ #
328
+ # entries = []
329
+ # entries << table.new_mutation_entry("row-1").set_cell("cf1", "field1", "XYZ")
330
+ # entries << table.new_mutation_entry("row-2").set_cell("cf1", "field1", "ABC")
331
+ # responses = table.mutate_rows(entries)
332
+ #
333
+ # responses.each do |response|
334
+ # puts response.status.description
335
+ # end
336
+ #
337
+ class Response
338
+ attr_reader :index, :status
339
+
340
+ ##
341
+ # @private Creates a MutationEntry::Response object.
342
+ def initialize index, status
343
+ @index = index
344
+ @status = status
345
+ end
346
+
347
+ ##
348
+ # @private New MutationEntry::Response from a
349
+ # Google::Bigtable::V2::MutateRowsResponse::Entry object.
350
+ def self.from_grpc grpc
351
+ new grpc.index, Status.from_grpc(grpc.status)
352
+ end
336
353
  end
337
354
  end
338
355
  end
@@ -16,6 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module Bigtable
19
+ ##
19
20
  # # Policy
20
21
  #
21
22
  # Represents a Cloud IAM Policy for Bigtable instance resources.
@@ -63,6 +64,7 @@ module Google
63
64
  @roles = roles
64
65
  end
65
66
 
67
+ ##
66
68
  # Convenience method for adding a member to a binding on this policy.
67
69
  # See [Understanding
68
70
  # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
@@ -88,6 +90,7 @@ module Google
88
90
  role(role_name) << member
89
91
  end
90
92
 
93
+ ##
91
94
  # Convenience method for removing a member from a binding on this
92
95
  # policy. See [Understanding
93
96
  # Roles](https://cloud.google.com/iam/docs/understanding-roles) for a
@@ -101,7 +104,7 @@ module Google
101
104
  # `"user:owner@example.com"`.
102
105
  #
103
106
  # @example
104
- # require "google/cloud/Bigtable"
107
+ # require "google/cloud/bigtable"
105
108
  #
106
109
  # bigtable = Google::Cloud::Bigtable.new
107
110
  # instance = bigtable.instance "my-instance"
@@ -113,6 +116,7 @@ module Google
113
116
  role(role_name).delete member
114
117
  end
115
118
 
119
+ ##
116
120
  # Convenience method returning the array of members bound to a role in
117
121
  # this policy. Returns an empty array if no value is present for the role in
118
122
  # {#roles}. See [Understanding
@@ -124,7 +128,7 @@ module Google
124
128
  # @return [Array<String>] The members strings, or an empty array.
125
129
  #
126
130
  # @example
127
- # require "google/cloud/Bigtable"
131
+ # require "google/cloud/bigtable"
128
132
  #
129
133
  # bigtable = Google::Cloud::Bigtable.new
130
134
  # instance = bigtable.instance "my-instance"
@@ -142,11 +146,11 @@ module Google
142
146
  bindings = roles.keys.map do |role_name|
143
147
  next if roles[role_name].empty?
144
148
  Google::Iam::V1::Binding.new(
145
- role: role_name,
149
+ role: role_name,
146
150
  members: roles[role_name]
147
151
  )
148
152
  end
149
- Google::Iam::V1::Policy.new(etag: etag, bindings: bindings)
153
+ Google::Iam::V1::Policy.new etag: etag, bindings: bindings
150
154
  end
151
155
 
152
156
  # @private
@@ -155,7 +159,7 @@ module Google
155
159
  roles = grpc.bindings.each_with_object({}) do |binding, memo|
156
160
  memo[binding.role] = binding.members.to_a
157
161
  end
158
- new(grpc.etag, roles)
162
+ new grpc.etag, roles
159
163
  end
160
164
  end
161
165
  end
@@ -26,23 +26,23 @@ require "google/cloud/bigtable/table"
26
26
  module Google
27
27
  module Cloud
28
28
  module Bigtable
29
+ ##
29
30
  # # Project
30
31
  #
31
32
  # Projects are top-level containers in Google Cloud Platform. They store
32
33
  # information about billing and authorized users, and they contain
33
34
  # Cloud Bigtable data. Each project has a friendly name and a unique ID.
34
35
  #
35
- # Google::Cloud::Bigtable::Project is the main object for interacting with
36
+ # `Google::Cloud::Bigtable::Project` is the main object for interacting with
36
37
  # Cloud Bigtable.
37
38
  #
38
39
  # {Google::Cloud::Bigtable::Cluster} and {Google::Cloud::Bigtable::Instance}
39
40
  # objects are created, accessed, and managed by Google::Cloud::Bigtable::Project.
40
41
  #
41
- # To create an instance, use {Google::Cloud::Bigtable.new} or
42
- # {Google::Cloud#bigtable}.
42
+ # To create a `Project` instance, use {Google::Cloud::Bigtable.new}.
43
43
  #
44
44
  # @example Obtaining an instance and the clusters from a project.
45
- # require "google/cloud"
45
+ # require "google/cloud/bigtable"
46
46
  #
47
47
  # bigtable = Google::Cloud::Bigtable.new
48
48
  #
@@ -57,17 +57,17 @@ module Google
57
57
  # @private
58
58
  # Creates a new Bigtable Project instance.
59
59
  # @param service [Google::Cloud::Bigtable::Service]
60
-
61
60
  def initialize service
62
61
  @service = service
63
62
  end
64
63
 
64
+ ##
65
65
  # The identifier for the Cloud Bigtable project.
66
66
  #
67
67
  # @return [String] Project ID.
68
68
  #
69
69
  # @example
70
- # require "google/cloud"
70
+ # require "google/cloud/bigtable"
71
71
  #
72
72
  # bigtable = Google::Cloud::Bigtable.new(
73
73
  # project_id: "my-project",
@@ -75,12 +75,13 @@ module Google
75
75
  # )
76
76
  #
77
77
  # bigtable.project_id #=> "my-project"
78
-
78
+ #
79
79
  def project_id
80
80
  ensure_service!
81
81
  service.project_id
82
82
  end
83
83
 
84
+ ##
84
85
  # Retrieves the list of Bigtable instances for the project.
85
86
  #
86
87
  # @param token [String] The `token` value returned by the last call to
@@ -98,16 +99,17 @@ module Google
98
99
  # instances.all do |instance|
99
100
  # puts instance.instance_id
100
101
  # end
101
-
102
+ #
102
103
  def instances token: nil
103
104
  ensure_service!
104
- grpc = service.list_instances(token: token)
105
- Instance::List.from_grpc(grpc, service)
105
+ grpc = service.list_instances token: token
106
+ Instance::List.from_grpc grpc, service
106
107
  end
107
108
 
108
- # Get an existing Bigtable instance.
109
+ ##
110
+ # Gets an existing Bigtable instance.
109
111
  #
110
- # @param instance_id [String] Existing instance id.
112
+ # @param instance_id [String] Existing instance ID.
111
113
  # @return [Google::Cloud::Bigtable::Instance, nil]
112
114
  #
113
115
  # @example
@@ -120,16 +122,17 @@ module Google
120
122
  # if instance
121
123
  # puts instance.instance_id
122
124
  # end
123
-
125
+ #
124
126
  def instance instance_id
125
127
  ensure_service!
126
- grpc = service.get_instance(instance_id)
127
- Instance.from_grpc(grpc, service)
128
+ grpc = service.get_instance instance_id
129
+ Instance.from_grpc grpc, service
128
130
  rescue Google::Cloud::NotFoundError
129
131
  nil
130
132
  end
131
133
 
132
- # Create a Bigtable instance.
134
+ ##
135
+ # Creates a Bigtable instance.
133
136
  #
134
137
  # @see https://cloud.google.com/compute/docs/regions-zones Cluster zone locations
135
138
  #
@@ -140,9 +143,9 @@ module Google
140
143
  # @param display_name [String] The descriptive name for this instance as it
141
144
  # appears in UIs. Must be unique per project and between 4 and 30
142
145
  # characters.
143
- # @param type [Symbol] The type of the instance.
144
- # Valid values are `:DEVELOPMENT` or `:PRODUCTION`.
145
- # Default `:PRODUCTION` instance will created if left blank.
146
+ # @param type [Symbol] The type of the instance. When creating a development instance,
147
+ # `nodes` on the cluster must not be set.
148
+ # Valid values are `:DEVELOPMENT` or `:PRODUCTION`. Default is `:PRODUCTION`.
146
149
  # @param labels [Hash{String=>String}] labels Cloud Labels are a flexible and lightweight
147
150
  # mechanism for organizing cloud resources into groups that reflect a
148
151
  # customer's organizational needs and deployment strategies. Cloud
@@ -169,7 +172,7 @@ module Google
169
172
  # The job representing the long-running, asynchronous processing of
170
173
  # an instance create operation.
171
174
  #
172
- # @example Create development instance.
175
+ # @example Create a development instance.
173
176
  # require "google/cloud/bigtable"
174
177
  #
175
178
  # bigtable = Google::Cloud::Bigtable.new
@@ -180,13 +183,13 @@ module Google
180
183
  # type: :DEVELOPMENT,
181
184
  # labels: { "env" => "dev"}
182
185
  # ) do |clusters|
183
- # clusters.add("test-cluster", "us-east1-b", nodes: 1)
186
+ # clusters.add("test-cluster", "us-east1-b") # nodes not allowed
184
187
  # end
185
188
  #
186
189
  # job.done? #=> false
187
190
  #
188
191
  # # Reload job until completion.
189
- # job.wait_until_done
192
+ # job.wait_until_done!
190
193
  # job.done? #=> true
191
194
  #
192
195
  # if job.error?
@@ -195,7 +198,7 @@ module Google
195
198
  # instance = job.instance
196
199
  # end
197
200
  #
198
- # @example Create production instance.
201
+ # @example Create a production instance.
199
202
  # require "google/cloud/bigtable"
200
203
  #
201
204
  # bigtable = Google::Cloud::Bigtable.new
@@ -211,7 +214,7 @@ module Google
211
214
  # job.done? #=> false
212
215
  #
213
216
  # # To block until the operation completes.
214
- # job.wait_until_done
217
+ # job.wait_until_done!
215
218
  # job.done? #=> true
216
219
  #
217
220
  # if job.error?
@@ -219,39 +222,25 @@ module Google
219
222
  # else
220
223
  # instance = job.instance
221
224
  # end
222
-
223
- def create_instance \
224
- instance_id,
225
- display_name: nil,
226
- type: nil,
227
- labels: nil,
228
- clusters: nil
225
+ #
226
+ def create_instance instance_id, display_name: nil, type: nil, labels: nil, clusters: nil
229
227
  labels = Hash[labels.map { |k, v| [String(k), String(v)] }] if labels
230
228
 
231
- instance_attrs = {
232
- display_name: display_name,
233
- type: type,
234
- labels: labels
235
- }.delete_if { |_, v| v.nil? }
236
- instance = Google::Bigtable::Admin::V2::Instance.new(instance_attrs)
229
+ instance_attrs = { display_name: display_name, type: type, labels: labels }.delete_if { |_, v| v.nil? }
230
+ instance = Google::Bigtable::Admin::V2::Instance.new instance_attrs
237
231
  clusters ||= Instance::ClusterMap.new
238
232
  yield clusters if block_given?
239
233
 
240
234
  clusters.each_value do |cluster|
241
- unless cluster.location == "".freeze
242
- cluster.location = service.location_path(cluster.location)
243
- end
235
+ cluster.location = service.location_path cluster.location unless cluster.location == ""
244
236
  end
245
237
 
246
- grpc = service.create_instance(
247
- instance_id,
248
- instance,
249
- clusters.to_h
250
- )
251
- Instance::Job.from_grpc(grpc, service)
238
+ grpc = service.create_instance instance_id, instance, clusters.to_h
239
+ Instance::Job.from_grpc grpc, service
252
240
  end
253
241
 
254
- # List all clusters in project.
242
+ ##
243
+ # Lists all clusters in the project.
255
244
  #
256
245
  # @param token [String] The `token` value returned by the last call to
257
246
  # `clusters` indicates that this is a continuation of a call
@@ -267,20 +256,21 @@ module Google
267
256
  # puts cluster.cluster_id
268
257
  # puts cluster.ready?
269
258
  # end
270
-
259
+ #
271
260
  def clusters token: nil
272
261
  ensure_service!
273
- grpc = service.list_clusters("-", token: token)
274
- Cluster::List.from_grpc(grpc, service, instance_id: "-")
262
+ grpc = service.list_clusters "-", token: token
263
+ Cluster::List.from_grpc grpc, service, instance_id: "-"
275
264
  end
276
265
 
277
- # List all tables for given instance.
266
+ ##
267
+ # Lists all tables for the given instance.
278
268
  #
279
269
  # @param instance_id [String] Existing instance Id.
280
270
  # @return [Array<Google::Cloud::Bigtable::Table>]
281
271
  # (See {Google::Cloud::Bigtable::Table::List})
282
272
  #
283
- # @example Get tables
273
+ # @example
284
274
  # require "google/cloud/bigtable"
285
275
  #
286
276
  # bigtable = Google::Cloud::Bigtable.new
@@ -289,15 +279,16 @@ module Google
289
279
  # puts table.name
290
280
  # puts table.column_families
291
281
  # end
292
-
282
+ #
293
283
  def tables instance_id
294
284
  ensure_service!
295
- grpc = service.list_tables(instance_id)
296
- Table::List.from_grpc(grpc, service)
285
+ grpc = service.list_tables instance_id
286
+ Table::List.from_grpc grpc, service
297
287
  end
298
288
 
299
- # Get table information.
300
- #
289
+ ##
290
+ # Returns a table representation. If `perform_lookup` is `false` (the default), a sparse representation will be
291
+ # returned without performing an RPC and without verifying that the table resource exists.
301
292
  #
302
293
  # @param instance_id [String] Existing instance Id.
303
294
  # @param table_id [String] Existing table Id.
@@ -318,79 +309,44 @@ module Google
318
309
  # "default" application profile will be used.
319
310
  # @return [Google::Cloud::Bigtable::Table, nil]
320
311
  #
321
- # @example Get table with schema only view
322
- # require "google/cloud/bigtable"
323
- #
324
- # bigtable = Google::Cloud::Bigtable.new
325
- #
326
- # table = bigtable.table("my-instance", "my-table", perform_lookup: true, view: :SCHEMA_VIEW)
327
- # if table
328
- # p table.name
329
- # p table.column_families
330
- # end
331
- #
332
- # @example Get table object without calling get table admin api.
312
+ # @example Get a sparse table representation without performing an RPC.
333
313
  # require "google/cloud/bigtable"
334
314
  #
335
315
  # bigtable = Google::Cloud::Bigtable.new
336
316
  #
337
317
  # table = bigtable.table("my-instance", "my-table")
338
318
  #
339
- # @example Get table with all fields, cluster states, and column families.
319
+ # @example Get a table with schema-only view.
340
320
  # require "google/cloud/bigtable"
341
321
  #
342
322
  # bigtable = Google::Cloud::Bigtable.new
343
323
  #
344
- # table = bigtable.table("my-instance", "my-table", view: :FULL, perform_lookup: true)
324
+ # table = bigtable.table("my-instance", "my-table", perform_lookup: true, view: :SCHEMA_VIEW)
345
325
  # if table
346
326
  # puts table.name
347
- # p table.column_families
348
- # p table.cluster_states
327
+ # puts table.column_families
349
328
  # end
350
329
  #
351
- # @example Mutate rows
330
+ # @example Get a table with all fields, cluster states, and column families.
352
331
  # require "google/cloud/bigtable"
353
332
  #
354
333
  # bigtable = Google::Cloud::Bigtable.new
355
334
  #
356
- # table = bigtable.table("my-instance", "my-table")
357
- #
358
- # entry = table.new_mutation_entry("user-1")
359
- # entry.set_cell(
360
- # "cf-1",
361
- # "field-1",
362
- # "XYZ",
363
- # timestamp: (Time.now.to_f * 1000000).round(-3) # microseconds
364
- # ).delete_cells("cf2", "field02")
365
- #
366
- # table.mutate_row(entry)
367
- # @example Read rows using app profile routing
368
- # require "google/cloud/bigtable"
369
- #
370
- # bigtable = Google::Cloud::Bigtable.new
371
- #
372
- # table = bigtable.table("my-instance", "my-table", app_profile_id: "my-app-profile")
373
- #
374
- # table.read_rows(limit: 5).each do |row|
375
- # p row
335
+ # table = bigtable.table("my-instance", "my-table", view: :FULL, perform_lookup: true)
336
+ # if table
337
+ # puts table.name
338
+ # puts table.column_families
339
+ # puts table.cluster_states
376
340
  # end
377
-
378
- def table \
379
- instance_id,
380
- table_id,
381
- view: nil,
382
- perform_lookup: nil,
383
- app_profile_id: nil
341
+ #
342
+ def table instance_id, table_id, view: nil, perform_lookup: nil, app_profile_id: nil
384
343
  ensure_service!
385
344
 
386
345
  table = if perform_lookup
387
- grpc = service.get_table(instance_id, table_id, view: view)
388
- Table.from_grpc(grpc, service, view: view)
346
+ grpc = service.get_table instance_id, table_id, view: view
347
+ Table.from_grpc grpc, service, view: view
389
348
  else
390
- Table.from_path(
391
- service.table_path(instance_id, table_id),
392
- service
393
- )
349
+ Table.from_path service.table_path(instance_id, table_id), service
394
350
  end
395
351
 
396
352
  table.app_profile_id = app_profile_id
@@ -399,6 +355,7 @@ module Google
399
355
  nil
400
356
  end
401
357
 
358
+ ##
402
359
  # Creates a new table in the specified instance.
403
360
  # The table can be created with a full set of initial column families,
404
361
  # specified in the request.
@@ -408,9 +365,9 @@ module Google
408
365
  # @param table_id [String]
409
366
  # The ID by which the new table should be referred to within the
410
367
  # instance, e.g., `foobar`.
411
- # @param column_families [Hash{String => Google::Cloud::Bigtable::ColumnFamily}]
412
- # (See {Google::Cloud::Bigtable::Table::ColumnFamilyMap})
413
- # If unspecified, you may use a code block to add column families.
368
+ # @param column_families [Google::Cloud::Bigtable::ColumnFamilyMap]
369
+ # An object containing the column families for the table, mapped by
370
+ # column family name.
414
371
  # @param granularity [Symbol]
415
372
  # The granularity at which timestamps are stored in this table.
416
373
  # Timestamps not matching the granularity will be rejected.
@@ -432,17 +389,14 @@ module Google
432
389
  # * Tablet 3 : `[customer_1, customer_2) => {"customer_1"}`
433
390
  # * Tablet 4 : `[customer_2, other) => {"customer_2"}`
434
391
  # * Tablet 5 : `[other, ) => {"other", "zz"}`
435
- # A hash in the form of `Google::Bigtable::Admin::V2::CreateTableRequest::Split`
436
- # can also be provided.
437
- # @yield [column_families] A block for adding column_families.
438
- # @yieldparam [Hash{String => Google::Cloud::Bigtable::ColumnFamily}]
439
- # Map of family name and column family object.
440
- # (See {Google::Cloud::Bigtable::Instance::ColumnFamilyMap})
441
- # (Read the GC Rules for column families at {Google::Cloud::Bigtable::GcRule})
392
+ # @yield [column_families] A block for adding column families.
393
+ # @yieldparam [Google::Cloud::Bigtable::ColumnFamilyMap] column_families
394
+ # A mutable object containing the column families for the table,
395
+ # mapped by column family name.
442
396
  #
443
397
  # @return [Google::Cloud::Bigtable::Table]
444
398
  #
445
- # @example Create a table without a column family
399
+ # @example Create a table without column families.
446
400
  # require "google/cloud/bigtable"
447
401
  #
448
402
  # bigtable = Google::Cloud::Bigtable.new
@@ -450,53 +404,47 @@ module Google
450
404
  # table = bigtable.create_table("my-instance", "my-table")
451
405
  # puts table.name
452
406
  #
453
- # @example Create table with column families and initial splits.
407
+ # @example Create a table with initial splits and column families.
454
408
  # require "google/cloud/bigtable"
455
409
  #
456
410
  # bigtable = Google::Cloud::Bigtable.new
457
411
  #
458
412
  # initial_splits = ["user-00001", "user-100000", "others"]
459
- # table = bigtable.create_table("my-instance", "my-table", initial_splits: initial_splits) do |column_families|
460
- # column_families.add('cf1', Google::Cloud::Bigtable::GcRule.max_versions(5))
461
- # column_families.add('cf2', Google::Cloud::Bigtable::GcRule.max_age(600))
413
+ # table = bigtable.create_table("my-instance", "my-table", initial_splits: initial_splits) do |cfm|
414
+ # cfm.add('cf1', gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
415
+ # cfm.add('cf2', gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
462
416
  #
463
417
  # gc_rule = Google::Cloud::Bigtable::GcRule.union(
464
418
  # Google::Cloud::Bigtable::GcRule.max_age(1800),
465
419
  # Google::Cloud::Bigtable::GcRule.max_versions(3)
466
420
  # )
467
- # column_families.add('cf3', gc_rule)
421
+ # cfm.add('cf3', gc_rule: gc_rule)
468
422
  # end
469
423
  #
470
- # p table
471
-
472
- def create_table \
473
- instance_id,
474
- table_id,
475
- column_families: nil,
476
- granularity: nil,
477
- initial_splits: nil,
478
- &block
424
+ # puts table
425
+ #
426
+ def create_table instance_id, table_id, column_families: nil, granularity: nil, initial_splits: nil, &block
479
427
  ensure_service!
480
428
  Table.create(
481
429
  service,
482
430
  instance_id,
483
431
  table_id,
484
432
  column_families: column_families,
485
- granularity: granularity,
486
- initial_splits: initial_splits,
433
+ granularity: granularity,
434
+ initial_splits: initial_splits,
487
435
  &block
488
436
  )
489
437
  end
490
438
 
491
- # Permanently deletes a specified table and all of its data.
439
+ ##
440
+ # Permanently deletes the specified table and all of its data.
492
441
  #
493
442
  # @param instance_id [String]
494
443
  # The unique ID of the instance the table is in.
495
444
  # @param table_id [String]
496
- # The unique ID of the table to be deleted,
497
- # e.g., `foobar`
445
+ # The unique ID of the table to be deleted.
498
446
  #
499
- # @example Create table with column families and initial splits.
447
+ # @example
500
448
  # require "google/cloud/bigtable"
501
449
  #
502
450
  # bigtable = Google::Cloud::Bigtable.new
@@ -504,67 +452,10 @@ module Google
504
452
  # bigtable.delete_table("my-instance", "my-table")
505
453
  #
506
454
  def delete_table instance_id, table_id
507
- service.delete_table(instance_id, table_id)
455
+ service.delete_table instance_id, table_id
508
456
  true
509
457
  end
510
458
 
511
- # Performs a series of column family modifications on the specified table.
512
- # Either all or none of the modifications will occur before this method
513
- # returns, but data requests received prior to that point may see a table
514
- # where only some modifications have taken effect.
515
- #
516
- # @param instance_id [String]
517
- # The unique ID of the instance the table is in.
518
- # @param table_id [String]
519
- # The unique Id of the table whose families should be modified.
520
- # @param modifications [Array<Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification> | Google::Bigtable::Admin::V2::ModifyColumnFamiliesRequest::Modification]
521
- # Modifications to be atomically applied to the specified table's families.
522
- # Entries are applied in order, meaning that earlier modifications can be
523
- # masked by later ones (in the case of repeated updates to the same family,
524
- # for example).
525
- # @return [Google::Cloud::Bigtable::Table] Table with updated column families.
526
- #
527
- # @example
528
- # require "google/cloud/bigtable"
529
- #
530
- # bigtable = Google::Cloud::Bigtable.new
531
- #
532
- # modifications = []
533
- # modifications << Google::Cloud::Bigtable::ColumnFamily.create_modification(
534
- # "cf1", Google::Cloud::Bigtable::GcRule.max_age(600))
535
- # )
536
- #
537
- # modifications << Google::Cloud::Bigtable::ColumnFamily.update_modification(
538
- # "cf2", Google::Cloud::Bigtable::GcRule.max_versions(5)
539
- # )
540
- #
541
- # gc_rule_1 = Google::Cloud::Bigtable::GcRule.max_versions(3)
542
- # gc_rule_2 = Google::Cloud::Bigtable::GcRule.max_age(600)
543
- # modifications << Google::Cloud::Bigtable::ColumnFamily.update_modification(
544
- # "cf3", Google::Cloud::Bigtable::GcRule.union(gc_rule_1, gc_rule_2)
545
- # )
546
- #
547
- # max_age_gc_rule = Google::Cloud::Bigtable::GcRule.max_age(300)
548
- # modifications << Google::Cloud::Bigtable::ColumnFamily.update_modification(
549
- # "cf4", Google::Cloud::Bigtable::GcRule.union(max_version_gc_rule)
550
- # )
551
- #
552
- # modifications << Google::Cloud::Bigtable::ColumnFamily.drop_modification("cf5")
553
- #
554
- # table = bigtable.modify_column_families("my-instance", "my-table", modifications)
555
- #
556
- # p table.column_families
557
-
558
- def modify_column_families instance_id, table_id, modifications
559
- ensure_service!
560
- Table.modify_column_families(
561
- service,
562
- instance_id,
563
- table_id,
564
- modifications
565
- )
566
- end
567
-
568
459
  protected
569
460
 
570
461
  # @private