google-cloud-datastore 0.20.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 38ee5cd7d5c58d59744397ca7dfd52f2dcad5505
+  data.tar.gz: 5bc9a57ae0e231478b3b4c41e54c8b798b9930cc
+SHA512:
+  metadata.gz: bc065e2f16a173c663a780900c732b007659ef26528d16ad938f816fddc580076f12255f8680ef1e5dadbc8adf445c6ffccde044264a9ff768254ac6a60ee909
+  data.tar.gz: 48530d73bb1727e971972f12713a0180318ec57f9ad63d30ae56be7a06bcc570ba7310311f8c7bf47df02b3117770e60705879c55cff56b1cd2716eb2d4a231c

data/lib/google-cloud-datastore.rb

@@ -0,0 +1,141 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+##
+# This file is here to be autorequired by bundler, so that the .bigquery and
+# #bigquery methods can be available, but the library and all dependencies won't
+# be loaded until required and used.
+
+
+gem "google-cloud-core"
+require "google/cloud"
+
+module Google
+  module Cloud
+    ##
+    # Creates a new object for connecting to the Datastore service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/datastore`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Datastore::Dataset]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   datastore = gcloud.datastore
+    #
+    #   task = datastore.entity "Task" do |t|
+    #     t["type"] = "Personal"
+    #     t["done"] = false
+    #     t["priority"] = 4
+    #     t["description"] = "Learn Cloud Datastore"
+    #   end
+    #
+    #   datastore.save task
+    #
+    # @example You shouldn't need to override the default scope, but you can:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
+    #   datastore = gcloud.datastore scope: platform_scope
+    #
+    def datastore scope: nil, retries: nil, timeout: nil
+      Google::Cloud.datastore @project, @keyfile,
+                              scope: scope, retries: (retries || @retries),
+                              timeout: (timeout || @timeout)
+    end
+
+    ##
+    # Creates a new object for connecting to the Datastore service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # @param [String] project Dataset identifier for the Datastore you are
+    #   connecting to.
+    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
+    #   file path the file must be readable.
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/datastore`
+    # @param [Integer] retries Number of times to retry requests on server
+    #   error. The default value is `3`. Optional.
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Datastore::Dataset]
+    #
+    # @example
+    #   require "google/cloud/datastore"
+    #
+    #   datastore = Google::Cloud.datastore "my-todo-project",
+    #                              "/path/to/keyfile.json"
+    #
+    #   task = datastore.entity "Task", "sampleTask" do |t|
+    #     t["type"] = "Personal"
+    #     t["done"] = false
+    #     t["priority"] = 4
+    #     t["description"] = "Learn Cloud Datastore"
+    #   end
+    #
+    #   datastore.save task
+    #
+    def self.datastore project = nil, keyfile = nil, scope: nil, retries: nil,
+                       timeout: nil
+      require "google/cloud/datastore"
+      project ||= Google::Cloud::Datastore::Dataset.default_project
+      project = project.to_s # Always cast to a string
+      fail ArgumentError, "project is missing" if project.empty?
+
+      if ENV["DATASTORE_EMULATOR_HOST"]
+        return Google::Cloud::Datastore::Dataset.new(
+          Google::Cloud::Datastore::Service.new(
+            project, :this_channel_is_insecure,
+            host: ENV["DATASTORE_EMULATOR_HOST"], retries: retries))
+      end
+
+      if keyfile.nil?
+        credentials = Google::Cloud::Datastore::Credentials.default scope: scope
+      else
+        credentials = Google::Cloud::Datastore::Credentials.new(
+          keyfile, scope: scope)
+      end
+
+      Google::Cloud::Datastore::Dataset.new(
+        Google::Cloud::Datastore::Service.new(
+          project, credentials, retries: retries, timeout: timeout))
+    end
+  end
+end

data/lib/google/cloud/datastore.rb

@@ -0,0 +1,532 @@
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google-cloud-datastore"
+require "google/cloud/datastore/errors"
+require "google/cloud/datastore/dataset"
+require "google/cloud/datastore/transaction"
+require "google/cloud/datastore/credentials"
+
+module Google
+  module Cloud
+    ##
+    # # Google Cloud Datastore
+    #
+    # Google Cloud Datastore is a fully managed, schemaless database for storing
+    # non-relational data. You should feel at home if you are familiar with
+    # relational databases, but there are some key differences to be aware of to
+    # make the most of using Datastore.
+    #
+    # The goal of google-cloud is to provide a API that is comfortable to
+    # Rubyists. Authentication is handled by {Google::Cloud#datastore}. You can
+    # provide the project and credential information to connect to the Datastore
+    # service, or if you are running on Google Compute Engine this configuration
+    # is taken care of for you.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new "my-todo-project",
+    #                     "/path/to/keyfile.json"
+    # datastore = gcloud.datastore
+    #
+    # task = datastore.find "Task", "sampleTask"
+    # task["priority"] = 5
+    # datastore.save task
+    # ```
+    #
+    # You can learn more about various options for connection on the
+    # [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # To learn more about Datastore, read the
+    # [Google Cloud Datastore Concepts Overview
+    # ](https://cloud.google.com/datastore/docs/concepts/overview).
+    #
+    # ## Retrieving records
+    #
+    # Records, called "entities" in Datastore, are retrieved by using a key.
+    # The key is more than a numeric identifier, it is a complex data structure
+    # that can be used to model relationships. The simplest key has a string
+    # <tt>kind</tt> value, and either a numeric <tt>id</tt> value, or a string
+    # <tt>name</tt> value. A single record can be retrieved by calling
+    # {Google::Cloud::Datastore::Dataset#find} and passing the parts of the key:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task = datastore.find "Task", "sampleTask"
+    # ```
+    #
+    # Optionally, {Google::Cloud::Datastore::Dataset#find} can be given a key
+    # object:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task_key = datastore.key "Task", 123456
+    # task = datastore.find task_key
+    # ```
+    #
+    # See {Google::Cloud::Datastore::Dataset#find}
+    #
+    # ## Querying records
+    #
+    # Multiple records can be found that match criteria.
+    # (See {Google::Cloud::Datastore::Query#where})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # query = datastore.query("Task").
+    #   where("done", "=", false)
+    #
+    # tasks = datastore.run query
+    # ```
+    #
+    # Records can also be ordered. (See {Google::Cloud::Datastore::Query#order})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # query = datastore.query("Task").
+    #   order("created")
+    #
+    # tasks = datastore.run query
+    # ```
+    #
+    # The number of records returned can be specified.
+    # (See {Google::Cloud::Datastore::Query#limit})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # query = datastore.query("Task").
+    #   limit(5)
+    #
+    # tasks = datastore.run query
+    # ```
+    #
+    # Records' key structures can also be queried.
+    # (See {Google::Cloud::Datastore::Query#ancestor})
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task_list_key = datastore.key "TaskList", "default"
+    #
+    # query = datastore.query("Task").
+    #   ancestor(task_list_key)
+    #
+    # tasks = datastore.run query
+    # ```
+    #
+    # See {Google::Cloud::Datastore::Query} and
+    # {Google::Cloud::Datastore::Dataset#run}
+    #
+    # ### Paginating records
+    #
+    # All records may not return at once, but multiple calls can be made to
+    # Datastore to return them all.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # query = datastore.query("Task")
+    # tasks = datastore.run query
+    # tasks.all do |task|
+    #   puts t["description"]
+    # end
+    # ```
+    #
+    # See {Google::Cloud::Datastore::Dataset::LookupResults} and
+    # {Google::Cloud::Datastore::Dataset::QueryResults}
+    #
+    # ## Creating records
+    #
+    # New entities can be created and persisted buy calling
+    # {Google::Cloud::Datastore::Dataset#save}. The entity must have a key to be
+    # saved. If the key is incomplete then it will be completed when saved.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task = datastore.entity "Task" do |t|
+    #   t["type"] = "Personal"
+    #   t["done"] = false
+    #   t["priority"] = 4
+    #   t["description"] = "Learn Cloud Datastore"
+    # end
+    # task.key.id #=> nil
+    # datastore.save task
+    # task.key.id #=> 123456
+    # ```
+    #
+    # Multiple new entities may be created in a batch.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task1 = datastore.entity "Task" do |t|
+    #   t["type"] = "Personal"
+    #   t["done"] = false
+    #   t["priority"] = 4
+    #   t["description"] = "Learn Cloud Datastore"
+    # end
+    #
+    # task2 = datastore.entity "Task" do |t|
+    #   t["type"] = "Personal"
+    #   t["done"] = false
+    #   t["priority"] = 5
+    #   t["description"] = "Integrate Cloud Datastore"
+    # end
+    #
+    # tasks = datastore.save(task1, task2)
+    # task_key1 = tasks[0].key
+    # task_key2 = tasks[1].key
+    # ```
+    #
+    # Entities in Datastore form a hierarchically structured space similar to
+    # the directory structure of a file system. When you create an entity, you
+    # can optionally designate another entity as its parent; the new entity is a
+    # child of the parent entity.
+    #
+    # ```ruby
+    # task_key = datastore.key "Task", "sampleTask"
+    # task_key.parent = datastore.key "TaskList", "default"
+    #
+    # task = datastore.entity task_key do |t|
+    #   t["type"] = "Personal"
+    #   t["done"] = false
+    #   t["priority"] = 5
+    #   t["description"] = "Integrate Cloud Datastore"
+    # end
+    # ```
+    #
+    # ## Setting properties
+    #
+    # Entities hold properties. A property has a name that is a string or
+    # symbol, and a value that is an object. Most value objects are supported,
+    # including String, Integer, Date, Time, and even other entity or key
+    # objects. Changes to the entity's properties are persisted by calling
+    # {Google::Cloud::Datastore::Dataset#save}.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task = datastore.find "Task", "sampleTask"
+    # # Read the priority property
+    # task["priority"] #=> 4
+    # # Write the priority property
+    # task["priority"] = 5
+    # # Persist the changes
+    # datastore.save task
+    # ```
+    #
+    # Array properties can be used to store more than one value.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task = datastore.entity "Task", "sampleTask" do |t|
+    #   t["tags"] = ["fun", "programming"]
+    #   t["collaborators"] = ["alice", "bob"]
+    # end
+    # ```
+    #
+    # ## Deleting records
+    #
+    # Entities can be removed from Datastore by calling
+    # {Google::Cloud::Datastore::Dataset#delete} and passing the entity object
+    # or the entity's key object.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task = datastore.find "Task", "sampleTask"
+    # datastore.delete task
+    # ```
+    #
+    # Multiple entities may be deleted in a batch.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task_key1 = datastore.key "Task", "sampleTask1"
+    # task_key2 = datastore.key "Task", "sampleTask2"
+    # datastore.delete task_key1, task_key2
+    # ```
+    #
+    # ## Transactions
+    #
+    # Complex logic can be wrapped in a Transaction. All queries and updates
+    # within the {Google::Cloud::Datastore::Dataset#transaction} block are run
+    # within the transaction scope, and will be automatically committed when the
+    # block completes.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task_key = datastore.key "Task", "sampleTask"
+    #
+    # datastore.transaction do |tx|
+    #   if tx.find(task_key).nil?
+    #     task = datastore.entity task_key do |t|
+    #       t["type"] = "Personal"
+    #       t["done"] = false
+    #       t["priority"] = 4
+    #       t["description"] = "Learn Cloud Datastore"
+    #     end
+    #     tx.save task
+    #   end
+    # end
+    # ```
+    #
+    # Alternatively, if no block is given the transaction object is returned
+    # allowing you to commit or rollback manually.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore
+    #
+    # task_key = datastore.key "Task", "sampleTask"
+    #
+    # tx = datastore.transaction
+    # begin
+    #   if tx.find(task_key).nil?
+    #     task = datastore.entity task_key do |t|
+    #       t["type"] = "Personal"
+    #       t["done"] = false
+    #       t["priority"] = 4
+    #       t["description"] = "Learn Cloud Datastore"
+    #     end
+    #     tx.save task
+    #   end
+    #   tx.commit
+    # rescue
+    #   tx.rollback
+    # end
+    # ```
+    #
+    # See {Google::Cloud::Datastore::Transaction} and
+    # {Google::Cloud::Datastore::Dataset#transaction}
+    #
+    # ## Querying metadata
+    #
+    # Datastore provides programmatic access to some of its metadata to support
+    # meta-programming, implementing backend administrative functions, simplify
+    # consistent caching, and similar purposes. The metadata available includes
+    # information about the entity groups, namespaces, entity kinds, and
+    # properties your application uses, as well as the property representations
+    # for each property.
+    #
+    # The special entity kind `__namespace__` can be used to find all the
+    # namespaces used in your application entities.
+    #
+    # ```ruby
+    # query = datastore.query("__namespace__").
+    #   select("__key__").
+    #   where("__key__", ">=", datastore.key("__namespace__", "g")).
+    #   where("__key__", "<", datastore.key("__namespace__", "h"))
+    #
+    # namespaces = datastore.run(query).map do |entity|
+    #   entity.key.name
+    # end
+    # ```
+    #
+    # The special entity kind `__kind__` can be used to return all the
+    # kinds used in your application.
+    #
+    # ```ruby
+    # query = datastore.query("__kind__").
+    #   select("__key__")
+    #
+    # kinds = datastore.run(query).map do |entity|
+    #   entity.key.name
+    # end
+    # ```
+    #
+    # Property queries return entities of kind `__property__` denoting the
+    # indexed properties associated with an entity kind. (Unindexed properties
+    # are not included.)
+    #
+    # ```ruby
+    # query = datastore.query("__property__").
+    #   select("__key__")
+    #
+    # entities = datastore.run(query)
+    # properties_by_kind = entities.each_with_object({}) do |entity, memo|
+    #   kind = entity.key.parent.name
+    #   prop = entity.key.name
+    #   memo[kind] ||= []
+    #   memo[kind] << prop
+    # end
+    # ```
+    #
+    # Property queries support ancestor filtering on a `__kind__` or
+    # `__property__` key, to limit the query results to a single kind or
+    # property. The `property_representation` property in the entity
+    # representing property `p` of kind `k` is an array containing all
+    # representations of `p`'s value in any entity of kind `k`.
+    #
+    # ```ruby
+    # ancestor_key = datastore.key "__kind__", "Task"
+    # query = datastore.query("__property__").
+    #   ancestor(ancestor_key)
+    #
+    # entities = datastore.run(query)
+    # representations = entities.each_with_object({}) do |entity, memo|
+    #   property_name = entity.key.name
+    #   property_types = entity["property_representation"]
+    #   memo[property_name] = property_types
+    # end
+    # ```
+    #
+    # Property queries can also be filtered with a range over the
+    # pseudo-property `__key__`, where the keys denote either `__kind__` or
+    # `__property__` entities.
+    #
+    # ```ruby
+    # start_key = datastore.key "__property__", "priority"
+    # start_key.parent = datastore.key "__kind__", "Task"
+    # query = datastore.query("__property__").
+    #   select("__key__").
+    #   where("__key__", ">=", start_key)
+    #
+    # entities = datastore.run(query)
+    # properties_by_kind = entities.each_with_object({}) do |entity, memo|
+    #   kind = entity.key.parent.name
+    #   prop = entity.key.name
+    #   memo[kind] ||= []
+    #   memo[kind] << prop
+    # end
+    # ```
+    #
+    # ## Configuring retries and timeout
+    #
+    # You can configure how many times API requests may be automatically
+    # retried. When an API request fails, the response will be inspected to see
+    # if the request meets criteria indicating that it may succeed on retry,
+    # such as `500` and `503` status codes or a specific internal error code
+    # such as `rateLimitExceeded`. If it meets the criteria, the request will be
+    # retried after a delay. If another error occurs, the delay will be
+    # increased before a subsequent attempt, until the `retries` limit is
+    # reached.
+    #
+    # You can also set the request `timeout` value in seconds.
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # gcloud = Google::Cloud.new
+    # datastore = gcloud.datastore retries: 10, timeout: 120
+    # ```
+    #
+    # See the [Datastore error
+    # codes](https://cloud.google.com/datastore/docs/concepts/errors#error_codes)
+    # for a list of error conditions.
+    #
+    # ## The Cloud Datastore Emulator
+    #
+    # As of this release, the Cloud Datastore emulator that is part of the
+    # gcloud SDK is no longer compatible with google-cloud. This is because the
+    # gcloud SDK's Cloud Datastore emulator does not yet support gRPC as a
+    # transport layer.
+    #
+    # A gRPC-compatible emulator is available until the gcloud SDK Cloud
+    # Datastore emulator supports gRPC. To use it you must [download the gRPC
+    # emulator](https://storage.googleapis.com/gcd/tools/cloud-datastore-emulator-1.1.1.zip)
+    # and use the `cloud_datastore_emulator` script.
+    #
+    # When you run the Cloud Datastore emulator you will see a message similar
+    # to the following printed:
+    #
+    # ```
+    # If you are using a library that supports the DATASTORE_EMULATOR_HOST
+    # environment variable, run:
+    #
+    # export DATASTORE_EMULATOR_HOST=localhost:8978
+    # ```
+    #
+    # Now you can connect to the emulator using the `DATASTORE_EMULATOR_HOST`
+    # environment variable:
+    #
+    # ```ruby
+    # require "google/cloud"
+    #
+    # # Make Datastore use the emulator
+    # ENV["DATASTORE_EMULATOR_HOST"] = "localhost:8978"
+    #
+    # gcloud = Google::Cloud.new "emulator-project-id"
+    # datastore = gcloud.datastore
+    #
+    # task = datastore.entity "Task", "emulatorTask" do |t|
+    #   t["type"] = "Testing"
+    #   t["done"] = false
+    #   t["priority"] = 5
+    #   t["description"] = "Use Datastore Emulator"
+    # end
+    #
+    # datastore.save task
+    # ```
+    #
+    module Datastore
+    end
+  end
+end