google-cloud-bigtable 0.8.0 → 1.0.0

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 (47) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +12 -0
  3. data/OVERVIEW.md +388 -19
  4. data/lib/google-cloud-bigtable.rb +0 -1
  5. data/lib/google/bigtable/admin/v2/bigtable_table_admin_services_pb.rb +1 -1
  6. data/lib/google/bigtable/v2/bigtable_pb.rb +3 -0
  7. data/lib/google/bigtable/v2/bigtable_services_pb.rb +1 -1
  8. data/lib/google/cloud/bigtable/admin.rb +1 -1
  9. data/lib/google/cloud/bigtable/admin/v2.rb +1 -1
  10. data/lib/google/cloud/bigtable/admin/v2/bigtable_table_admin_client.rb +1 -1
  11. data/lib/google/cloud/bigtable/admin/v2/doc/google/iam/v1/policy.rb +6 -5
  12. data/lib/google/cloud/bigtable/app_profile.rb +13 -13
  13. data/lib/google/cloud/bigtable/app_profile/list.rb +7 -7
  14. data/lib/google/cloud/bigtable/cluster.rb +7 -7
  15. data/lib/google/cloud/bigtable/cluster/list.rb +2 -2
  16. data/lib/google/cloud/bigtable/column_family.rb +3 -1
  17. data/lib/google/cloud/bigtable/column_family_map.rb +8 -8
  18. data/lib/google/cloud/bigtable/column_range.rb +6 -6
  19. data/lib/google/cloud/bigtable/gc_rule.rb +8 -8
  20. data/lib/google/cloud/bigtable/instance.rb +74 -64
  21. data/lib/google/cloud/bigtable/instance/cluster_map.rb +8 -6
  22. data/lib/google/cloud/bigtable/instance/job.rb +2 -2
  23. data/lib/google/cloud/bigtable/instance/list.rb +4 -4
  24. data/lib/google/cloud/bigtable/longrunning_job.rb +1 -1
  25. data/lib/google/cloud/bigtable/mutation_entry.rb +17 -16
  26. data/lib/google/cloud/bigtable/mutation_operations.rb +10 -11
  27. data/lib/google/cloud/bigtable/project.rb +28 -59
  28. data/lib/google/cloud/bigtable/read_modify_write_rule.rb +6 -6
  29. data/lib/google/cloud/bigtable/read_operations.rb +14 -18
  30. data/lib/google/cloud/bigtable/routing_policy.rb +3 -2
  31. data/lib/google/cloud/bigtable/row.rb +14 -14
  32. data/lib/google/cloud/bigtable/row_filter.rb +31 -15
  33. data/lib/google/cloud/bigtable/row_filter/chain_filter.rb +49 -26
  34. data/lib/google/cloud/bigtable/row_filter/condition_filter.rb +4 -1
  35. data/lib/google/cloud/bigtable/row_filter/interleave_filter.rb +44 -24
  36. data/lib/google/cloud/bigtable/row_filter/simple_filter.rb +3 -3
  37. data/lib/google/cloud/bigtable/rows_reader.rb +2 -2
  38. data/lib/google/cloud/bigtable/sample_row_key.rb +1 -1
  39. data/lib/google/cloud/bigtable/table.rb +18 -18
  40. data/lib/google/cloud/bigtable/table/cluster_state.rb +10 -5
  41. data/lib/google/cloud/bigtable/table/list.rb +2 -2
  42. data/lib/google/cloud/bigtable/v2.rb +1 -1
  43. data/lib/google/cloud/bigtable/v2/bigtable_client.rb +21 -12
  44. data/lib/google/cloud/bigtable/v2/doc/google/bigtable/v2/bigtable.rb +34 -13
  45. data/lib/google/cloud/bigtable/value_range.rb +14 -13
  46. data/lib/google/cloud/bigtable/version.rb +1 -1
  47. metadata +2 -2
@@ -35,11 +35,11 @@ module Google
35
35
  attr_accessor :token
36
36
 
37
37
  ##
38
- # Locations from which Instance information could not be retrieved,
38
+ # Locations from which instance information could not be retrieved,
39
39
  # due to an outage or some other transient condition.
40
- # Instances whose Clusters are all in one of the failed locations
41
- # may be missing from `instances`, and Instances with at least one
42
- # Cluster in a failed location may only have partial information returned.
40
+ # Instances whose clusters are all in one of the failed locations
41
+ # may be missing from `instances`, and instances with at least one
42
+ # cluster in a failed location may only have partial information returned.
43
43
  attr_accessor :failed_locations
44
44
 
45
45
  # @private
@@ -37,7 +37,7 @@ module Google
37
37
  attr_accessor :service
38
38
 
39
39
  ##
40
- # Get result object of the operation.
40
+ # Gets the result object of the operation.
41
41
  #
42
42
  # @return [Object, nil]
43
43
  # `nil` if the operation is not complete.
@@ -42,7 +42,7 @@ module Google
42
42
  # timestamp_to: timestamp_micros
43
43
  # ).delete_from_family("cf3").delete_from_row
44
44
  #
45
- # @example Using table
45
+ # @example Create using a table.
46
46
  # require "google/cloud/bigtable"
47
47
  #
48
48
  # bigtable = Google::Cloud::Bigtable.new
@@ -74,9 +74,9 @@ module Google
74
74
  end
75
75
 
76
76
  ##
77
- # Add SetCell mutation to list of mutations.
77
+ # Adds a SetCell to the list of mutations.
78
78
  #
79
- # A mutation that sets the value of the specified cell.
79
+ # A SetCell is a mutation that sets the value of the specified cell.
80
80
  #
81
81
  # @param family [String] Table column family name.
82
82
  # The name of the family into which new data should be written.
@@ -101,7 +101,7 @@ module Google
101
101
  # entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
102
102
  # entry.set_cell("cf1", "field01", "XYZ")
103
103
  #
104
- # @example With timestamp
104
+ # @example With timestamp.
105
105
  # entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
106
106
  # entry.set_cell(
107
107
  # "cf-1",
@@ -128,10 +128,11 @@ module Google
128
128
  end
129
129
 
130
130
  ##
131
- # Add DeleteFromColumn entry to list of mutations.
131
+ # Adds a DeleteFromColumn to the list of mutations.
132
132
  #
133
- # A mutation that deletes cells from the specified column, optionally
134
- # restricting the deletions to a given timestamp range.
133
+ # A DeleteFromColumn is a mutation that deletes cells from the
134
+ # specified column, optionally restricting the deletions to a given
135
+ # timestamp range.
135
136
  #
136
137
  # @param family [String] Table column family name.
137
138
  # The name of the column family from which cells should be deleted.
@@ -153,11 +154,11 @@ module Google
153
154
  # (millisecond granularity). For example: `1564257960168000`.
154
155
  # @return [MutationEntry] `self` object of entry for chaining.
155
156
  #
156
- # @example Without timestamp range
157
+ # @example Without timestamp range.
157
158
  # entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
158
159
  # entry.delete_cells("cf-1", "field-1")
159
160
  #
160
- # @example With timestamp range
161
+ # @example With timestamp range.
161
162
  # entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
162
163
  # timestamp_micros = (Time.now.to_f * 1000000).round(-3)
163
164
  # entry.delete_cells(
@@ -166,7 +167,7 @@ module Google
166
167
  # timestamp_from: timestamp_micros - 5000000,
167
168
  # timestamp_to: timestamp_micros
168
169
  # )
169
- # @example With timestamp range with lower boundary only
170
+ # @example With timestamp range with lower boundary only.
170
171
  # entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
171
172
  # timestamp_micros = (Time.now.to_f * 1000000).round(-3)
172
173
  # entry.delete_cells(
@@ -188,9 +189,9 @@ module Google
188
189
  end
189
190
 
190
191
  ##
191
- # Add DeleteFromFamily to list of mutations.
192
+ # Adds a DeleteFromFamily to the list of mutations.
192
193
  #
193
- # A mutation that deletes all cells from the specified column family.
194
+ # A DeleteFromFamily is a mutation that deletes all cells from the specified column family.
194
195
  #
195
196
  # @param family [String] Table column family name.
196
197
  # The name of the column family from which cells should be deleted.
@@ -207,9 +208,9 @@ module Google
207
208
  end
208
209
 
209
210
  ##
210
- # Add DeleteFromRow entry to list of mutations
211
+ # Adds a DeleteFromRow to the list of mutations.
211
212
  #
212
- # A Mutation which deletes all cells from the containing row.
213
+ # A DeleteFromRow is a mutation which deletes all cells from the containing row.
213
214
  #
214
215
  # @return [MutationEntry] `self` object of entry for chaining.
215
216
  #
@@ -223,7 +224,7 @@ module Google
223
224
  end
224
225
 
225
226
  ##
226
- # Mutation entry is retryable or not based on set_cell value.
227
+ # If the mutation entry is retryable or not based on set_cell value.
227
228
  #
228
229
  # @return [Boolean]
229
230
  #
@@ -232,7 +233,7 @@ module Google
232
233
  end
233
234
 
234
235
  ##
235
- # Number of mutations
236
+ # The number of mutations.
236
237
  #
237
238
  # @return [Integer]
238
239
  #
@@ -36,13 +36,11 @@ module Google
36
36
  #
37
37
  module MutationOperations
38
38
  ##
39
- # Mutate row.
40
- #
41
39
  # Mutates a row atomically. Cells in the row are left
42
- # unchanged unless explicitly changed by +mutation+.
40
+ # unchanged unless explicitly changed by the mutations.
43
41
  # Changes to be atomically applied to the specified row. Entries are applied
44
42
  # in order, meaning that earlier mutations can be masked by later mutations.
45
- # Must contain at least one mutation entry and at most 100,000.
43
+ # Must contain at least one mutation and at most 100,000.
46
44
  #
47
45
  # @param entry [Google::Cloud::Bigtable::MutationEntry]
48
46
  # Mutation entry with row key and list of mutations.
@@ -82,7 +80,7 @@ module Google
82
80
 
83
81
  ##
84
82
  # Mutates multiple rows in a batch. Each individual row is mutated
85
- # atomically as in MutateRow, but the entire batch is not executed
83
+ # atomically as in #{mutate_row}, but the entire batch is not executed
86
84
  # atomically.
87
85
  #
88
86
  # @param entries [Array<Google::Cloud::Bigtable::MutationEntry>]
@@ -210,7 +208,8 @@ module Google
210
208
  # Must contain at least one entry if +true_mutations+ is empty and at most
211
209
  # 100,000 entries.
212
210
  # @return [Boolean]
213
- # Predicate match or not status
211
+ # Predicate match or not status.
212
+ #
214
213
  # @example
215
214
  # require "google/cloud/bigtable"
216
215
  #
@@ -255,9 +254,9 @@ module Google
255
254
  end
256
255
 
257
256
  ##
258
- # Create an instance of mutation_entry
257
+ # Creates a mutation entry instance.
259
258
  #
260
- # @param row_key [String] Row key. Optional
259
+ # @param row_key [String] Row key. Optional.
261
260
  # The row key of the row to which the mutation should be applied.
262
261
  # @return [Google::Cloud::Bigtable::MutationEntry]
263
262
  #
@@ -277,13 +276,13 @@ module Google
277
276
  end
278
277
 
279
278
  ##
280
- # Create an instance of ReadModifyWriteRule to append or increment the value
279
+ # Create a read/modify/write rule to append or increment the value
281
280
  # of the cell qualifier.
282
281
  #
283
282
  # @param family [String]
284
- # 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.
285
284
  # @param qualifier [String]
286
- # 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.
287
286
  # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]
288
287
  #
289
288
  # @example Create rule to append to qualifier value.
@@ -33,14 +33,13 @@ module Google
33
33
  # information about billing and authorized users, and they contain
34
34
  # Cloud Bigtable data. Each project has a friendly name and a unique ID.
35
35
  #
36
- # Google::Cloud::Bigtable::Project is the main object for interacting with
36
+ # `Google::Cloud::Bigtable::Project` is the main object for interacting with
37
37
  # Cloud Bigtable.
38
38
  #
39
39
  # {Google::Cloud::Bigtable::Cluster} and {Google::Cloud::Bigtable::Instance}
40
40
  # objects are created, accessed, and managed by Google::Cloud::Bigtable::Project.
41
41
  #
42
- # To create an instance, use {Google::Cloud::Bigtable.new} or
43
- # {Google::Cloud#bigtable}.
42
+ # To create a `Project` instance, use {Google::Cloud::Bigtable.new}.
44
43
  #
45
44
  # @example Obtaining an instance and the clusters from a project.
46
45
  # require "google/cloud/bigtable"
@@ -58,7 +57,6 @@ module Google
58
57
  # @private
59
58
  # Creates a new Bigtable Project instance.
60
59
  # @param service [Google::Cloud::Bigtable::Service]
61
-
62
60
  def initialize service
63
61
  @service = service
64
62
  end
@@ -109,9 +107,9 @@ module Google
109
107
  end
110
108
 
111
109
  ##
112
- # Get an existing Bigtable instance.
110
+ # Gets an existing Bigtable instance.
113
111
  #
114
- # @param instance_id [String] Existing instance id.
112
+ # @param instance_id [String] Existing instance ID.
115
113
  # @return [Google::Cloud::Bigtable::Instance, nil]
116
114
  #
117
115
  # @example
@@ -134,7 +132,7 @@ module Google
134
132
  end
135
133
 
136
134
  ##
137
- # Create a Bigtable instance.
135
+ # Creates a Bigtable instance.
138
136
  #
139
137
  # @see https://cloud.google.com/compute/docs/regions-zones Cluster zone locations
140
138
  #
@@ -145,9 +143,9 @@ module Google
145
143
  # @param display_name [String] The descriptive name for this instance as it
146
144
  # appears in UIs. Must be unique per project and between 4 and 30
147
145
  # characters.
148
- # @param type [Symbol] The type of the instance.
149
- # Valid values are `:DEVELOPMENT` or `:PRODUCTION`.
150
- # 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`.
151
149
  # @param labels [Hash{String=>String}] labels Cloud Labels are a flexible and lightweight
152
150
  # mechanism for organizing cloud resources into groups that reflect a
153
151
  # customer's organizational needs and deployment strategies. Cloud
@@ -174,7 +172,7 @@ module Google
174
172
  # The job representing the long-running, asynchronous processing of
175
173
  # an instance create operation.
176
174
  #
177
- # @example Create development instance.
175
+ # @example Create a development instance.
178
176
  # require "google/cloud/bigtable"
179
177
  #
180
178
  # bigtable = Google::Cloud::Bigtable.new
@@ -185,7 +183,7 @@ module Google
185
183
  # type: :DEVELOPMENT,
186
184
  # labels: { "env" => "dev"}
187
185
  # ) do |clusters|
188
- # clusters.add("test-cluster", "us-east1-b", nodes: 1)
186
+ # clusters.add("test-cluster", "us-east1-b") # nodes not allowed
189
187
  # end
190
188
  #
191
189
  # job.done? #=> false
@@ -200,7 +198,7 @@ module Google
200
198
  # instance = job.instance
201
199
  # end
202
200
  #
203
- # @example Create production instance.
201
+ # @example Create a production instance.
204
202
  # require "google/cloud/bigtable"
205
203
  #
206
204
  # bigtable = Google::Cloud::Bigtable.new
@@ -242,7 +240,7 @@ module Google
242
240
  end
243
241
 
244
242
  ##
245
- # List all clusters in project.
243
+ # Lists all clusters in the project.
246
244
  #
247
245
  # @param token [String] The `token` value returned by the last call to
248
246
  # `clusters` indicates that this is a continuation of a call
@@ -266,13 +264,13 @@ module Google
266
264
  end
267
265
 
268
266
  ##
269
- # List all tables for given instance.
267
+ # Lists all tables for the given instance.
270
268
  #
271
269
  # @param instance_id [String] Existing instance Id.
272
270
  # @return [Array<Google::Cloud::Bigtable::Table>]
273
271
  # (See {Google::Cloud::Bigtable::Table::List})
274
272
  #
275
- # @example Get tables
273
+ # @example
276
274
  # require "google/cloud/bigtable"
277
275
  #
278
276
  # bigtable = Google::Cloud::Bigtable.new
@@ -289,7 +287,8 @@ module Google
289
287
  end
290
288
 
291
289
  ##
292
- # Get table information.
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.
293
292
  #
294
293
  # @param instance_id [String] Existing instance Id.
295
294
  # @param table_id [String] Existing table Id.
@@ -310,61 +309,34 @@ module Google
310
309
  # "default" application profile will be used.
311
310
  # @return [Google::Cloud::Bigtable::Table, nil]
312
311
  #
313
- # @example Get table with schema only view
314
- # require "google/cloud/bigtable"
315
- #
316
- # bigtable = Google::Cloud::Bigtable.new
317
- #
318
- # table = bigtable.table("my-instance", "my-table", perform_lookup: true, view: :SCHEMA_VIEW)
319
- # if table
320
- # puts table.name
321
- # puts table.column_families
322
- # end
323
- #
324
- # @example Get table object without calling get table admin api.
312
+ # @example Get a sparse table representation without performing an RPC.
325
313
  # require "google/cloud/bigtable"
326
314
  #
327
315
  # bigtable = Google::Cloud::Bigtable.new
328
316
  #
329
317
  # table = bigtable.table("my-instance", "my-table")
330
318
  #
331
- # @example Get table with all fields, cluster states, and column families.
319
+ # @example Get a table with schema-only view.
332
320
  # require "google/cloud/bigtable"
333
321
  #
334
322
  # bigtable = Google::Cloud::Bigtable.new
335
323
  #
336
- # 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)
337
325
  # if table
338
326
  # puts table.name
339
327
  # puts table.column_families
340
- # puts table.cluster_states
341
328
  # end
342
329
  #
343
- # @example Mutate rows
330
+ # @example Get a table with all fields, cluster states, and column families.
344
331
  # require "google/cloud/bigtable"
345
332
  #
346
333
  # bigtable = Google::Cloud::Bigtable.new
347
334
  #
348
- # table = bigtable.table("my-instance", "my-table")
349
- #
350
- # entry = table.new_mutation_entry("user-1")
351
- # entry.set_cell(
352
- # "cf-1",
353
- # "field-1",
354
- # "XYZ",
355
- # timestamp: (Time.now.to_f * 1000000).round(-3) # microseconds
356
- # ).delete_cells("cf2", "field02")
357
- #
358
- # table.mutate_row(entry)
359
- # @example Read rows using app profile routing
360
- # require "google/cloud/bigtable"
361
- #
362
- # bigtable = Google::Cloud::Bigtable.new
363
- #
364
- # table = bigtable.table("my-instance", "my-table", app_profile_id: "my-app-profile")
365
- #
366
- # table.read_rows(limit: 5).each do |row|
367
- # 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
368
340
  # end
369
341
  #
370
342
  def table instance_id, table_id, view: nil, perform_lookup: nil, app_profile_id: nil
@@ -417,8 +389,6 @@ module Google
417
389
  # * Tablet 3 : `[customer_1, customer_2) => {"customer_1"}`
418
390
  # * Tablet 4 : `[customer_2, other) => {"customer_2"}`
419
391
  # * Tablet 5 : `[other, ) => {"other", "zz"}`
420
- # A hash in the form of `Google::Bigtable::Admin::V2::CreateTableRequest::Split`
421
- # can also be provided.
422
392
  # @yield [column_families] A block for adding column families.
423
393
  # @yieldparam [Google::Cloud::Bigtable::ColumnFamilyMap] column_families
424
394
  # A mutable object containing the column families for the table,
@@ -467,15 +437,14 @@ module Google
467
437
  end
468
438
 
469
439
  ##
470
- # Permanently deletes a specified table and all of its data.
440
+ # Permanently deletes the specified table and all of its data.
471
441
  #
472
442
  # @param instance_id [String]
473
443
  # The unique ID of the instance the table is in.
474
444
  # @param table_id [String]
475
- # The unique ID of the table to be deleted,
476
- # e.g., `foobar`
445
+ # The unique ID of the table to be deleted.
477
446
  #
478
- # @example Create table with column families and initial splits.
447
+ # @example
479
448
  # require "google/cloud/bigtable"
480
449
  #
481
450
  # bigtable = Google::Cloud::Bigtable.new
@@ -36,7 +36,7 @@ module Google
36
36
  #
37
37
  class ReadModifyWriteRule
38
38
  # @private
39
- # Create an instance of ReadModifyWriteRule
39
+ # Creates an instance of ReadModifyWriteRule
40
40
  #
41
41
  # @param family [String]
42
42
  # The name of the family to which the read/modify/write should be applied.
@@ -50,7 +50,7 @@ module Google
50
50
  end
51
51
 
52
52
  ##
53
- # Create an instance of an append-value rule.
53
+ # Creates an instance of an append-value rule.
54
54
  #
55
55
  # @param family [String]
56
56
  # The name of the family to which the read/modify/write should be applied.
@@ -73,7 +73,7 @@ module Google
73
73
  end
74
74
 
75
75
  ##
76
- # Create an instance of an increment-amount rule.
76
+ # Creates an instance of an increment-amount rule.
77
77
  #
78
78
  # @param family [String]
79
79
  # The name of the family to which the read/modify/write should be applied.
@@ -86,7 +86,7 @@ module Google
86
86
  # as a 64-bit big-endian signed integer), or the entire request will fail.
87
87
  # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]
88
88
  #
89
- # @example increment value rule
89
+ # @example
90
90
  # rule = Google::Cloud::Bigtable::ReadModifyWriteRule.increment(
91
91
  # "cf", "field01", 1
92
92
  # )
@@ -98,7 +98,7 @@ module Google
98
98
  end
99
99
 
100
100
  ##
101
- # Set append value.
101
+ # Sets the append value.
102
102
  #
103
103
  # @param value [String]
104
104
  # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]
@@ -109,7 +109,7 @@ module Google
109
109
  end
110
110
 
111
111
  ##
112
- # Set increment amount.
112
+ # Sets the increment amount.
113
113
  #
114
114
  # @param amount [Integer]
115
115
  # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]