google-cloud-bigtable 0.6.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3d888a5ae0e03db4d343f1f472df17e34e6749305a18907309afc1e9aba13451
-  data.tar.gz: 921696b2987c12c2480bf8407b9d19c500bdbfd0ff2ab2401a58a3880ca357d5
+  metadata.gz: a043924866764ff0a48e0787f4cf3cda747470cbd81977734aac3ed8ff080cd8
+  data.tar.gz: ec6fdc94f142babade487a79415fba618ebcd3ec83a0ea8d3a8820dc6b3f4eea
 SHA512:
-  metadata.gz: 5f898010312460f67d88380f2252a83b26acfd2e1220c31a09bacc1026c87066ffe184369807fc2fadcf17e49e98cee4ae255aaf771dd54617cdb706ba829f91
-  data.tar.gz: 17358abe5747ae235d77a62cbb4d3e0030939bb254111fbdd2d1dfea8e520681a1dbc4376b9c2a36d0880167864e109b89f4f42317bb1a59a43d748452dff7ec
+  metadata.gz: f67a6084d021869cbbf8065a2d5bec0452ba92d2754832e33f041e06e19d6988037c922118d4a443db7ba741034519c274fd201cc09871ca4da92bbfbcd076bd
+  data.tar.gz: 4b1f0e5b94d521830fd7626b37d1be278d1f34b9e4cb8b95a14a7c9a8ddf17aa5c1697c9ef42f4b2fa31d1c90f8aec7c0103eacd12591a553440144f1414324b

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,90 @@
 # Release History
 
+### 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
+
+* Update Table#column_families to yield ColumnFamilyMap for updates.
+  * ColumnFamilyMap now manages ColumnFamily lifecycle.
+* Add MutationOperations::Response.
+* Add Bigtable::Status.
+* Add Bigtable::RoutingPolicy.
+* Update Ruby dependency to minimum of 2.4.
+
+#### BREAKING CHANGES
+
+* Remove ColumnFamily lifecycle methods (create, save, delete, and related class methods).
+  * Replaced by Table#column_families yield block.
+* Move Google::Cloud::Bigtable::Table::ColumnFamilyMap to Google::Cloud::Bigtable::ColumnFamilyMap.
+  * This should only affect introspection, since the constructor was previously undocumented.
+* Remove Project#modify_column_families.
+  * Replaced by Table#column_families yield block.
+* Remove Table#column_family.
+  * Replaced by ColumnFamilyMap lifecycle methods.
+* Remove Table#modify_column_families.
+  * Replaced by Table#column_families yield block.
+* Update GcRule#union and #intersection to not return lower-level API types.
+* Update all return types and parameters associated with AppProfile routing policy to not use lower-level API types.
+  * The new types have exactly the same API as the old types, so this change should only affect type introspection.
+* Update return types of Chain and Interleave row filters to not use lower-level API types.
+* Change return type of MutationOperations#mutate_rows from lower-level API types to wrapper types.
+* Remove private MutationEntry#mutations from documentation.
+* Update GcRule#max_age to microsecond precision.
+
+#### Documentation
+
+* Update sample code.
+* Update documentation.
+
+### 0.6.2 / 2019-10-01
+
+#### Documentation
+
+* Fix role string in low-level IAM Policy JSON example
+* Update low-level IAM Policy class description and sample code
+
 ### 0.6.1 / 2019-09-05
 
 #### Features

data/CONTRIBUTING.md

@@ -24,7 +24,7 @@ be able to accept your pull requests.
 In order to use the google-cloud-bigtable console and run the project's tests,
 there is a small amount of setup:
 
-1. Install Ruby. google-cloud-bigtable requires Ruby 2.3+. You may choose to
+1. Install Ruby. google-cloud-bigtable requires Ruby 2.4+. You may choose to
    manage your Ruby and gem installations with [RVM](https://rvm.io/),
    [rbenv](https://github.com/rbenv/rbenv), or
    [chruby](https://github.com/postmodern/chruby).

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