google-cloud-datastore 0.21.0 → 0.23.0

data/lib/google/cloud/datastore/entity.rb

@@ -34,6 +34,10 @@ module Google
       #   Properties, and Keys
       #
       # @example Create a new entity using a block:
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
       #   task = datastore.entity "Task", "sampleTask" do |t|
       #     t["type"] = "Personal"
       #     t["created"] = Time.now
@@ -44,6 +48,10 @@ module Google
       #   end
       #
       # @example Create a new entity belonging to an existing parent entity:
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
       #   task_key = datastore.key "Task", "sampleTask"
       #   task_key.parent = datastore.key "TaskList", "default"
       #
@@ -84,6 +92,7 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   task = datastore.find "Task", "sampleTask"
         #   task["description"] #=> "Learn Cloud Datastore"
         #
@@ -91,6 +100,7 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   task = datastore.find "Task", "sampleTask"
         #   task[:description] #=> "Learn Cloud Datastore"
         #
@@ -98,23 +108,25 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   user = datastore.find "User", "alice"
-        #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+        #   user["avatar"].class #=> StringIO
         #
         # @example Getting a geo point value returns a Hash:
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   user = datastore.find "User", "alice"
-        #   user["location"] #=> { longitude: -122.0862462,
-        #                    #     latitude: 37.4220041 }
+        #   user["location"].keys #=> [:latitude, :longitude]
         #
         # @example Getting a blob value returns a StringIO object:
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   user = datastore.find "User", "alice"
-        #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+        #   user["avatar"].class #=> StringIO
         #
         def [] prop_name
           properties[prop_name]
@@ -137,6 +149,7 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   task = datastore.find "Task", "sampleTask"
         #   task["description"] = "Learn Cloud Datastore"
         #   task["tags"] = ["fun", "programming"]
@@ -145,6 +158,7 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   task = datastore.find "Task", "sampleTask"
         #   task[:description] = "Learn Cloud Datastore"
         #   task[:tags] = ["fun", "programming"]
@@ -153,14 +167,16 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   user = datastore.find "User", "alice"
         #   user["avatar"] = File.open "/avatars/alice.png"
-        #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+        #   user["avatar"].class #=> StringIO
         #
         # @example Setting a geo point value using a Hash:
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   user = datastore.find "User", "alice"
         #   user["location"] = { longitude: -122.0862462, latitude: 37.4220041 }
         #
@@ -168,9 +184,10 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   user = datastore.find "User", "alice"
         #   user["avatar"] = File.open "/avatars/alice.png"
-        #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+        #   user["avatar"].class #=> StringIO
         #
         def []= prop_name, prop_value
           properties[prop_name] = prop_value
@@ -183,6 +200,12 @@ module Google
         # @return [Google::Cloud::Datastore::Properties]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task = datastore.find "Task", "sampleTask"
+        #
         #   task.properties[:description] = "Learn Cloud Datastore"
         #   task.properties["description"] #=> "Learn Cloud Datastore"
         #
@@ -191,15 +214,33 @@ module Google
         #   end
         #
         # @example A property's existence can be determined by calling `exist?`:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task = datastore.find "Task", "sampleTask"
+        #
         #   task.properties.exist? :description #=> true
         #   task.properties.exist? "description" #=> true
         #   task.properties.exist? :expiration #=> false
         #
         # @example A property can be removed from the entity:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task = datastore.find "Task", "sampleTask"
+        #
         #   task.properties.delete :description
-        #   task.save
+        #   datastore.update task
         #
         # @example The properties can be converted to a hash:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task = datastore.find "Task", "sampleTask"
+        #
         #   prop_hash = task.properties.to_h
         #
         attr_reader :properties
@@ -214,6 +255,7 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   task = Google::Cloud::Datastore::Entity.new
         #   task.key = datastore.key "Task"
         #   datastore.save task
@@ -222,11 +264,12 @@ module Google
         #   require "google/cloud/datastore"
         #
         #   datastore = Google::Cloud::Datastore.new
+        #
         #   task = datastore.find "Task", "sampleTask"
         #   task.persisted? #=> true
-        #   task.key = datastore.key "Task" #=> RuntimeError
+        #   task.key = datastore.key "Task" #=> raise RuntimeError
         #   task.key.frozen? #=> true
-        #   task.key.id = 9876543221 #=> RuntimeError
+        #   task.key.id = 9876543221 #=> raise RuntimeError
         #
         def key= new_key
           fail "This entity's key is immutable." if persisted?
@@ -268,10 +311,22 @@ module Google
         #   Unindexed properties
         #
         # @example Single property values will return a single flag setting:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task = datastore.find "Task", "sampleTask"
+        #
         #   task["priority"] = 4
         #   task.exclude_from_indexes? "priority" #=> false
         #
         # @example A multi-valued property will return array of flag settings:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   task = datastore.find "Task", "sampleTask"
+        #
         #   task["tags"] = ["fun", "programming"]
         #   task.exclude_from_indexes! "tags", [true, false]
         #
@@ -311,18 +366,42 @@ module Google
         #   Unindexed properties
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   entity = datastore.find "Task", "sampleTask"
+        #
         #   entity["priority"] = 4
         #   entity.exclude_from_indexes! "priority", true
         #
         # @example Multi-valued properties can be given multiple exclude flags:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   entity = datastore.find "Task", "sampleTask"
+        #
         #   entity["tags"] = ["fun", "programming"]
         #   entity.exclude_from_indexes! "tags", [true, false]
         #
         # @example Or, a single flag can be applied to all values in a property:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   entity = datastore.find "Task", "sampleTask"
+        #
         #   entity["tags"] = ["fun", "programming"]
         #   entity.exclude_from_indexes! "tags", true
         #
         # @example Flags can also be set with a block:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   entity = datastore.find "Task", "sampleTask"
+        #
         #   entity["priority"] = 4
         #   entity.exclude_from_indexes! "priority" do |priority|
         #     priority > 4

data/lib/google/cloud/datastore/gql_query.rb

@@ -31,6 +31,10 @@ module Google
       #   Reference
       #
       # @example
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
       #   gql_query = Google::Cloud::Datastore::GqlQuery.new
       #   gql_query.query_string = "SELECT * FROM Task ORDER BY created ASC"
       #   tasks = datastore.run gql_query
@@ -40,6 +44,8 @@ module Google
         # Returns a new GqlQuery instance.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   gql_query = Google::Cloud::Datastore::GqlQuery.new
         #
         def initialize
@@ -102,6 +108,8 @@ module Google
         #   literal values
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   gql_query = Google::Cloud::Datastore::GqlQuery.new
         #   gql_query.query_string = "SELECT * FROM Task " \
         #                            "WHERE completed = false AND priority = 4"
@@ -138,6 +146,8 @@ module Google
         #   names in the query string to valid GQL arguments
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   gql_query = Google::Cloud::Datastore::GqlQuery.new
         #   gql_query.query_string = "SELECT * FROM Task " \
         #                            "WHERE done = @done " \
@@ -186,6 +196,8 @@ module Google
         #   of the numbered binding sites in the query string
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   gql_query = Google::Cloud::Datastore::GqlQuery.new
         #   gql_query.query_string = "SELECT * FROM Task" \
         #                            "WHERE completed = @1 AND priority = @2"

data/lib/google/cloud/datastore/key.rb

@@ -25,6 +25,8 @@ module Google
       # integer numeric ID, assigned automatically by Datastore.
       #
       # @example
+      #   require "google/cloud/datastore"
+      #
       #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
       #
       class Key
@@ -34,6 +36,8 @@ module Google
         # @return [String]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   key = Google::Cloud::Datastore::Key.new "TaskList"
         #   key.kind #=> "TaskList"
         #   key.kind = "Task"
@@ -88,6 +92,8 @@ module Google
         # @return [Google::Cloud::Datastore::Dataset::Key]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
         #
         def initialize kind = nil, id_or_name = nil
@@ -106,6 +112,8 @@ module Google
         # @return [Integer, nil]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
         #   task_key.id #=> nil
         #   task_key.name #=> "sampleTask"
@@ -124,6 +132,8 @@ module Google
         # @return [Integer, nil]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   task_key = Google::Cloud::Datastore::Key.new "Task", 123456
         #   task_key.id #=> 123456
         #
@@ -136,6 +146,8 @@ module Google
         # @return [String, nil]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   task_key = Google::Cloud::Datastore::Key.new "Task", 123456
         #   task_key.id #=> 123456
         #   task_key.name #=> nil
@@ -154,6 +166,8 @@ module Google
         # @return [String, nil]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
         #   task_key.name #=> "sampleTask"
         #
@@ -165,11 +179,15 @@ module Google
         # @return [Key, nil]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   parent_key = Google::Cloud::Datastore::Key.new "TaskList", "default"
         #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
         #   task_key.parent = parent_key
         #
         # @example With multiple levels:
+        #   require "google/cloud/datastore"
+        #
         #   user_key = Google::Cloud::Datastore::Key.new "User", "alice"
         #   list_key = Google::Cloud::Datastore::Key.new "TaskList", "default"
         #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
@@ -196,7 +214,7 @@ module Google
         #   query = datastore.query("Task").
         #     ancestor(task_list)
         #   lists = datastore.run query
-        #   lists.first.key.parent #=> Key("TaskList", "default")
+        #   lists.first.key.parent # Key("TaskList", "default")
         #
         attr_reader :parent
 
@@ -208,6 +226,8 @@ module Google
         # @return [Array<Array<(String, String)>>]
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   parent_key = Google::Cloud::Datastore::Key.new "TaskList", "default"
         #   task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
         #   task_key.parent = parent_key

data/lib/google/cloud/datastore/query.rb

@@ -30,6 +30,10 @@ module Google
       #   Datastore Metadata
       #
       # @example
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
       #   query = Google::Cloud::Datastore::Query.new
       #   query.kind("Task").
       #     where("done", "=", false).
@@ -43,6 +47,8 @@ module Google
         # Returns a new query object.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #
         def initialize
@@ -57,6 +63,10 @@ module Google
         # queries](https://cloud.google.com/datastore/docs/concepts/metadataqueries).
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind "Task"
         #
@@ -76,6 +86,10 @@ module Google
         # Add a property filter to the query.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     where("done", "=", false)
@@ -83,6 +97,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example Add a composite property filter:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     where("done", "=", false).
@@ -91,6 +109,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example Add an inequality filter on a **single** property only:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     where("created", ">=", Time.utc(1990, 1, 1)).
@@ -99,6 +121,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example Add a composite filter on an array property:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     where("tag", "=", "fun").
@@ -107,6 +133,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example Add an inequality filter on an array property :
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     where("tag", ">", "learn").
@@ -115,6 +145,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example Add a key filter using the special property `__key__`:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     where("__key__", ">", datastore.key("Task", "someTask"))
@@ -122,6 +156,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example Add a key filter to a *kindless* query:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   last_seen_key = datastore.key "Task", "a"
         #   query = Google::Cloud::Datastore::Query.new
         #   query.where("__key__", ">", last_seen_key)
@@ -152,6 +190,10 @@ module Google
         # Add a filter for entities that inherit from a key.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   task_list_key = datastore.key "TaskList", "default"
         #
         #   query = Google::Cloud::Datastore::Query.new
@@ -173,6 +215,10 @@ module Google
         # of a string or symbol that starts with "d".
         #
         # @example With ascending sort order:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     order("created")
@@ -180,6 +226,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example With descending sort order:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     order("created", :desc)
@@ -187,6 +237,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example With multiple sort orders:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     order("priority", :desc).
@@ -195,6 +249,10 @@ module Google
         #   tasks = datastore.run query
         #
         # @example A property used in inequality filter must be ordered first:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     where("priority", ">", 3).
@@ -217,6 +275,10 @@ module Google
         # Set a limit on the number of results to be returned.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     limit(5)
@@ -233,6 +295,10 @@ module Google
         # Set an offset for the results to be returned.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     limit(5).
@@ -250,6 +316,10 @@ module Google
         # Set the cursor to start the results at.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     limit(page_size).
@@ -274,6 +344,10 @@ module Google
         # Retrieve only select properties from the matched entities.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     select("priority", "percent_complete")
@@ -286,6 +360,10 @@ module Google
         #   end
         #
         # @example A keys-only query using the special property `__key__`:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     select("__key__")
@@ -308,6 +386,10 @@ module Google
         # Group results by a list of properties.
         #
         # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
         #   query = Google::Cloud::Datastore::Query.new
         #   query.kind("Task").
         #     distinct_on("type", "priority").