google-cloud-bigtable 0.7.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 833d4009bf7801aeea418cc20c01957beb3aa7717eae7660aef91c4afc1b09c5
-  data.tar.gz: 95a806973acd438380803a215e1fdfb3d06846b66363ee541419ebe7f54cb507
+  metadata.gz: d5a23f16f0330f474a569b573e9651402b1494e0d6549a93bd09a92e74276866
+  data.tar.gz: 2f876607d84147ef39875f8fd476ee278fc0d31bad9e70db70d752eac33bc4fb
 SHA512:
-  metadata.gz: 7f8ba6fe01b55f0eae24961447f829ca02bb8f709ee11b75d8ec985314f673d714ebc4f71528a74da3c34911777da9cd95895c667cc74334b55fb8b786689db6
-  data.tar.gz: 131d9b4c4f58215ce1808eb721b4f8a01086df6a6b207503629d86a2200ceb8b871894b5d93d0246a69e72b87d9c2a665baf4ee02e5d278f263daef72a473c4d
+  metadata.gz: 8cceac32a50ad779a690fe989ba58c6723e876a0125045e9c380740e550781710a4b7c4c79b5954029d9b334dc43a87b29624cd09d1a769c0960fa0fc7e3027e
+  data.tar.gz: afdb9a5c2ef03fd8471cc6fa1746ba2aecd8e96618dd3049a035ee42f6c5fbbc9439367c299101c59edf20731847eb0444b5937c72711a18d1de8c534fdc2759

data/AUTHENTICATION.md

@@ -55,32 +55,10 @@ code.
 
 ### Google Cloud Platform environments
 
-While running on Google Cloud Platform environments such as Google Compute
-Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
-The **Project ID** and **Credentials** and are discovered automatically. Code
-should be written as if already authenticated. Just be sure when you [set up the
-GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
-access. For example:
-
-  * **All APIs**
-    * `https://www.googleapis.com/auth/cloud-platform`
-    * `https://www.googleapis.com/auth/cloud-platform.read-only`
-  * **BigQuery**
-    * `https://www.googleapis.com/auth/bigquery`
-    * `https://www.googleapis.com/auth/bigquery.insertdata`
-  * **Compute Engine**
-    * `https://www.googleapis.com/auth/compute`
-  * **Datastore**
-    * `https://www.googleapis.com/auth/datastore`
-    * `https://www.googleapis.com/auth/userinfo.email`
-  * **DNS**
-    * `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
-  * **Pub/Sub**
-    * `https://www.googleapis.com/auth/pubsub`
-  * **Storage**
-    * `https://www.googleapis.com/auth/devstorage.full_control`
-    * `https://www.googleapis.com/auth/devstorage.read_only`
-    * `https://www.googleapis.com/auth/devstorage.read_write`
+When running on Google Cloud Platform (GCP), including Google Compute Engine (GCE),
+Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud Functions
+(GCF) and Cloud Run, the **Project ID** and **Credentials** and are discovered
+automatically. Code should be written as if already authenticated.
 
 ### Environment Variables
 

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Release History
 
+### 1.1.0 / 2020-02-10
+
+#### Features
+
+* Add Table-level IAM Policy support
+
+### 1.0.2 / 2020-01-23
+
+#### Documentation
+
+* Update copyright year
+* Update Status documentation
+
+### 1.0.1 / 2020-01-15
+
+#### Documentation
+
+* Update lower-level API documentation
+
+### 1.0.0 / 2019-12-03
+
+#### Documentation
+
+* Update release level to GA
+* Add OVERVIEW.md guide with samples
+* Add sample to README.md
+* Fix samples and copy edit all in-line documentation
+* Correct error in lower-level API Table IAM documentation
+* Update lower-level API documentation to indicate attributes as required
+* Update low-level IAM Policy documentation
+
+### 0.8.0 / 2019-11-01
+
+#### ⚠ BREAKING CHANGES
+
+* The following methods now raise Google::Cloud::Error instead of
+  Google::Gax::GaxError and/or GRPC::BadStatus:
+  * Table#mutate_row
+  * Table#read_modify_write_row
+  * Table#check_and_mutate_row
+  * Table#sample_row_keys
+
+#### Features
+
+* Raise Google::Cloud::Error from Table#mutate_row, Table#read_modify_write_row,
+  Table#check_and_mutate_row, and Table#sample_row_keys.
+
+#### Bug Fixes
+
+* Update minimum runtime dependencies
+
+#### Documentation
+
+* Update the list of GCP environments for automatic authentication
+
 ### 0.7.0 / 2019-10-22
 
 #### Features

data/OVERVIEW.md

@@ -1,31 +1,400 @@
 # Cloud Bigtable
 
-Ruby Client for Cloud Bigtable API ([Beta](https://github.com/googleapis/google-cloud-ruby#versioning))
+Cloud Bigtable is a petabyte-scale, fully managed NoSQL database service for
+large analytical and operational workloads. Ideal for ad tech, fintech, and IoT,
+Cloud Bigtable offers consistent sub-10ms latency. Replication provides higher
+availability, higher durability, and resilience in the face of zonal failures.
+Cloud Bigtable is designed with a storage engine for machine learning
+applications and provides easy integration with open source big data tools.
 
-[Cloud Bigtable API][Product Documentation]:
-API for reading and writing the contents of Bigtables associated with a
-cloud project.
-- [Product Documentation][]
+For more information about Cloud Bigtable, read the [Cloud Bigtable
+Documentation](https://cloud.google.com/bigtable/docs/).
 
-## Quick Start
-In order to use this library, you first need to go through the following
-steps:
+The goal of google-cloud is to provide an API that is comfortable to Rubyists.
+Your authentication credentials are detected automatically in Google Cloud
+Platform (GCP), including Google Compute Engine (GCE), Google Kubernetes Engine
+(GKE), Google App Engine (GAE), Google Cloud Functions (GCF) and Cloud Run. In
+other environments you can configure authentication easily, either directly in
+your code or via environment variables. Read more about the options for
+connecting in the {file:AUTHENTICATION.md Authentication Guide}.
 
-1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
-2. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
-3. [Enable the Cloud Bigtable API.](https://console.cloud.google.com/apis/library/bigtable.googleapis.com)
-4. [Setup Authentication.](https://googleapis.dev/ruby/google-cloud-bigtable/latest/file.AUTHENTICATION.html)
+## Creating instances and clusters
 
-### Next Steps
-- Read the [Cloud Bigtable API Product documentation][Product Documentation]
-  to learn more about the product and see How-to Guides.
-- View this [repository's main README](https://github.com/googleapis/google-cloud-ruby/blob/master/README.md)
-  to see the full list of Cloud APIs that we cover.
+When you first use Cloud Bigtable, you must create an instance, which is an
+allocation of resources that are used by Cloud Bigtable. When you create an
+instance, you must specify at least one cluster. Clusters describe where your
+data is stored and how many nodes are used for your data.
+
+Use {Google::Cloud::Bigtable::Project#create_instance Project#create_instance}
+to create an instance. The following example creates a production instance with
+one cluster and three nodes:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+job = bigtable.create_instance(
+  "my-instance",
+  display_name: "Instance for user data",
+  labels: { "env" => "dev"}
+) do |clusters|
+  clusters.add("test-cluster", "us-east1-b", nodes: 3, storage_type: :SSD)
+end
+
+job.done? #=> false
+
+# To block until the operation completes.
+job.wait_until_done!
+job.done? #=> true
+
+if job.error?
+  status = job.error
+else
+  instance = job.instance
+end
+```
+
+You can also create a low-cost development instance for development and testing,
+with performance limited to the equivalent of a one-node cluster. There are no
+monitoring or throughput guarantees; replication is not available; and the SLA
+does not apply. When creating a development instance, you do not specify `nodes`
+for your clusters:
+
+ ```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+job = bigtable.create_instance(
+  "my-instance",
+  display_name: "Instance for user data",
+  type: :DEVELOPMENT,
+  labels: { "env" => "dev"}
+) do |clusters|
+  clusters.add("test-cluster", "us-east1-b") # nodes not allowed
+end
+
+job.done? #=> false
+
+# Reload job until completion.
+job.wait_until_done!
+job.done? #=> true
+
+if job.error?
+  status = job.error
+else
+  instance = job.instance
+end
+ ```
+
+You can upgrade a development instance to a production instance at any time.
+
+## Creating tables
+
+Cloud Bigtable stores data in massively scalable tables, each of which is a
+sorted key/value map. The table is composed of rows, each of which typically
+describes a single entity, and columns, which contain individual values for each
+row. Each row is indexed by a single row key, and columns that are related to
+one another are typically grouped together into a column family. Each column is
+identified by a combination of the column family and a column qualifier, which
+is a unique name within the column family.
+
+Each row/column intersection can contain multiple cells, or versions, at
+different timestamps, providing a record of how the stored data has been altered
+over time. Cloud Bigtable tables are sparse; if a cell does not contain any
+data, it does not take up any space.
+
+Use {Google::Cloud::Bigtable::Project#create_table Project#create_table} or
+{Google::Cloud::Bigtable::Instance#create_table Instance#create_table} to
+create a table:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+table = bigtable.create_table("my-instance", "my-table")
+puts table.name
+```
+
+When you create a table, you may specify the column families to use in the
+table, as well as a list of row keys that will be used to initially split the
+table into several tablets (tablets are similar to HBase regions):
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+initial_splits = ["user-00001", "user-100000", "others"]
+table = bigtable.create_table("my-instance", "my-table", initial_splits: initial_splits) do |cfm|
+  cfm.add('cf1', gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+  cfm.add('cf2', gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+
+  gc_rule = Google::Cloud::Bigtable::GcRule.union(
+    Google::Cloud::Bigtable::GcRule.max_age(1800),
+    Google::Cloud::Bigtable::GcRule.max_versions(3)
+  )
+  cfm.add('cf3', gc_rule: gc_rule)
+end
+
+puts table
+```
+
+You may also add, update, and delete column families later by passing a block to
+{Google::Cloud::Bigtable::Table#column_families Table#column_families}:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+
+table.column_families do |cfm|
+  cfm.add "cf4", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
+  cfm.add "cf5", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)
+
+  rule_1 = Google::Cloud::Bigtable::GcRule.max_versions(3)
+  rule_2 = Google::Cloud::Bigtable::GcRule.max_age(600)
+  rule_union = Google::Cloud::Bigtable::GcRule.union(rule_1, rule_2)
+  cfm.update "cf2", gc_rule: rule_union
+
+  cfm.delete "cf3"
+end
+
+puts table.column_families["cf3"] #=> nil
+```
+
+## Writing data
+
+The {Google::Cloud::Bigtable::Table Table} class allows you to perform the
+following types of writes:
+
+* Simple writes
+* Increments and appends
+* Conditional writes
+* Batch writes
+
+See [Cloud Bigtable writes](https://cloud.google.com/bigtable/docs/writes) for
+detailed information about writing data.
+
+### Simple writes
+
+Use {Google::Cloud::Bigtable::Table#mutate_row Table#mutate_row} to make
+one or more mutations to a single row:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+table = bigtable.table("my-instance", "my-table")
+
+entry = table.new_mutation_entry("user-1")
+entry.set_cell(
+  "cf-1",
+  "field-1",
+  "XYZ",
+  timestamp: (Time.now.to_f * 1000000).round(-3) # microseconds
+).delete_cells("cf2", "field02")
+
+table.mutate_row(entry)
+```
+
+### Increments and appends
+
+If you want to append data to an existing value or increment an existing numeric
+value, use
+{Google::Cloud::Bigtable::Table#read_modify_write_row Table#read_modify_write_row}:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+table = bigtable.table("my-instance", "my-table")
+
+rule_1 = table.new_read_modify_write_rule("cf", "field01")
+rule_1.append("append-xyz")
+
+rule_2 = table.new_read_modify_write_rule("cf", "field01")
+rule_2.increment(1)
+
+row = table.read_modify_write_row("user01", [rule_1, rule_2])
+
+puts row.cells
+```
+
+Do not use `read_modify_write_row` if you are using an app profile that has
+multi-cluster routing. (See
+{Google::Cloud::Bigtable::AppProfile#routing_policy AppProfile#routing_policy}.)
+
+### Conditional writes
+
+To check a row for a condition and then, depending on the result, write data to
+that row, use
+{Google::Cloud::Bigtable::Table#check_and_mutate_row Table#check_and_mutate_row}:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+table = bigtable.table("my-instance", "my-table")
+
+predicate_filter = Google::Cloud::Bigtable::RowFilter.key("user-10")
+on_match_mutations = Google::Cloud::Bigtable::MutationEntry.new
+on_match_mutations.set_cell(
+  "cf-1",
+  "field-1",
+  "XYZ",
+  timestamp: (Time.now.to_f * 1000000).round(-3) # microseconds
+).delete_cells("cf2", "field02")
+
+otherwise_mutations = Google::Cloud::Bigtable::MutationEntry.new
+otherwise_mutations.delete_from_family("cf3")
+
+predicate_matched = table.check_and_mutate_row(
+  "user01",
+  predicate_filter,
+  on_match: on_match_mutations,
+  otherwise: otherwise_mutations
+)
+
+if predicate_matched
+  puts "All predicates matched"
+end
+```
+
+Do not use `check_and_mutate_row` if you are using an app profile that has
+multi-cluster routing. (See
+{Google::Cloud::Bigtable::AppProfile#routing_policy AppProfile#routing_policy}.)
+
+### Batch writes
+
+You can write more than one row in a single RPC using
+{Google::Cloud::Bigtable::Table#mutate_rows Table#mutate_rows}:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+table = bigtable.table("my-instance", "my-table")
+
+entries = []
+entries << table.new_mutation_entry("row-1").set_cell("cf1", "field1", "XYZ")
+entries << table.new_mutation_entry("row-2").set_cell("cf1", "field1", "ABC")
+responses = table.mutate_rows(entries)
+
+responses.each do |response|
+  puts response.status.description
+end
+```
+
+Each entry in the request is atomic, but the request as a whole is not. As shown
+above, Cloud Bigtable returns a list of responses corresponding to the entries.
+
+## Reading data
+
+The {Google::Cloud::Bigtable::Table Table} class also enables you to read data.
+
+Use {Google::Cloud::Bigtable::Table#read_row Table#read_row} to read a single
+row by key:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+table = bigtable.table("my-instance", "my-table")
+
+row = table.read_row("user-1")
+```
+
+If desired, you can apply a filter:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+table = bigtable.table("my-instance", "my-table")
+
+filter = Google::Cloud::Bigtable::RowFilter.cells_per_row(3)
+
+row = table.read_row("user-1", filter: filter)
+```
+
+For multiple rows, the
+{Google::Cloud::Bigtable::Table#read_rows Table#read_rows} method streams back
+the contents of all requested rows in key order:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+table = bigtable.table("my-instance", "my-table")
+
+table.read_rows(keys: ["user-1", "user-2"]).each do |row|
+  puts row
+end
+```
+
+Instead of specifying individual keys (or a range), you can often just use a
+filter:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+table = bigtable.table("my-instance", "my-table")
+
+filter = table.filter.key("user-*")
+# OR
+# filter = Google::Cloud::Bigtable::RowFilter.key("user-*")
+
+table.read_rows(filter: filter).each do |row|
+  puts row
+end
+```
+
+## Deleting rows, tables, and instances
+
+Use {Google::Cloud::Bigtable::Table#drop_row_range Table#drop_row_range} to
+delete some or all of the rows in a table:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+table = bigtable.table("my-instance", "my-table")
+
+# Delete rows using row key prefix.
+table.drop_row_range(row_key_prefix: "user-100")
+
+# Delete all data With timeout
+table.drop_row_range(delete_all_data: true, timeout: 120) # 120 seconds.
+```
+
+Delete tables and instances using
+{Google::Cloud::Bigtable::Table#delete Table#delete} and
+{Google::Cloud::Bigtable::Instance#delete Instance#delete}, respectively:
+
+```ruby
+require "google/cloud/bigtable"
+
+bigtable = Google::Cloud::Bigtable.new
+
+instance = bigtable.instance("my-instance")
+table = instance.table("my-table")
+
+table.delete
+
+instance.delete
+```
 
 ## Additional information
 
 Google Bigtable can be configured to use an emulator or to enable gRPC's
 logging. To learn more, see the {file:EMULATOR.md Emulator guide} and
 {file:LOGGING.md Logging guide}.
-
-[Product Documentation]: https://cloud.google.com/bigtable