google-cloud-datastore 2.5.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ded45a15f44ec5a2e095ef0369db26c2a4a65e59c2af1e08bb8f6028736062ea
-  data.tar.gz: 8d7321547294a1c1ab492df132e19300a0466f252e74f9c7122fb7941bbaeac7
+  metadata.gz: b372b670c25604994c20b79779906b9a7c00b21bdf3ada9a23eb2cbb5968d053
+  data.tar.gz: 2cb8cac3d2de7b1b631d1c9ee7332b7391a73a720968bf09dc0608430de2a472
 SHA512:
-  metadata.gz: 8a4039bbc1c34698507c3b7a1e2c22b011f4df3ea66a57927c7dd147c4468d97c85f15b49efa6c06dcb124815ad5fc4098eeaa8e6f54d23570489e6da0d8dbf3
-  data.tar.gz: af0981ba4ea2bd054ba35ddd372399addbbb5e0d0c8e4032f518b48ab03065771af8a6185dea29483a9948ae42147011c0f6a100c747dd08100736780a5cb286
+  metadata.gz: dba07c333a2230e08f4c315dce2b8e28c748a082561c0692d9e419ba47565496b4b47463912e6cebea34ca3c33732df257ec6b4bcd9419b664cc16a4338b9b76
+  data.tar.gz: e817d031036cefd768ccf202a291435c6a710f69292ea61f2349bd5456732b3e0253ce94c75006abbcbc231c6c6e664bd4340dd2836f20978542dc2bb30b3b45

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Release History
 
+### 2.7.0 (2023-04-12)
+
+#### Features
+
+* Support OR filter ([#21002](https://github.com/googleapis/google-cloud-ruby/issues/21002)) 
+
+### 2.6.0 (2023-02-13)
+
+#### Features
+
+* Added support for snapshot read ([#19422](https://github.com/googleapis/google-cloud-ruby/issues/19422)) 
+
 ### 2.5.0 (2023-02-09)
 
 #### Features

data/lib/google/cloud/datastore/dataset/lookup_results.rb

@@ -53,6 +53,15 @@ module Google
         #   descriptions.missing #=> raise NoMethodError
         #
         class LookupResults < DelegateClass(::Array)
+          ##
+          # The time at which these entities were read or found missing.
+          attr_reader :response_read_time
+
+          ##
+          # Time at which the entities are being read. This would not be
+          # older than 270 seconds.
+          attr_reader :read_time
+
           ##
           # Keys that were not looked up due to resource constraints.
           attr_accessor :deferred
@@ -110,9 +119,9 @@ module Google
             ensure_service!
             lookup_res = @service.lookup(
               *Array(@deferred).flatten.map(&:to_grpc),
-              consistency: @consistency, transaction: @transaction
+              consistency: @consistency, transaction: @transaction, read_time: @read_time
             )
-            self.class.from_grpc lookup_res, @service, @consistency
+            self.class.from_grpc lookup_res, @service, @consistency, nil, @read_time
           end
 
           ##
@@ -187,7 +196,7 @@ module Google
           ##
           # @private New Dataset::LookupResults from a
           # Google::Dataset::V1::LookupResponse object.
-          def self.from_grpc lookup_res, service, consistency = nil, transaction = nil
+          def self.from_grpc lookup_res, service, consistency = nil, transaction = nil, read_time = nil
             entities = to_gcloud_entities lookup_res.found
             deferred = to_gcloud_keys lookup_res.deferred
             missing  = to_gcloud_entities lookup_res.missing
@@ -195,6 +204,8 @@ module Google
               lr.instance_variable_set :@service,     service
               lr.instance_variable_set :@consistency, consistency
               lr.instance_variable_set :@transaction, transaction
+              lr.instance_variable_set :@read_time, read_time
+              lr.instance_variable_set :@response_read_time, lookup_res.read_time
               lr.instance_variable_set :@deferred,    deferred
               lr.instance_variable_set :@missing,     missing
             end

data/lib/google/cloud/datastore/dataset/query_results.rb

@@ -72,6 +72,24 @@ module Google
           # * `:NO_MORE_RESULTS`
           attr_reader :more_results
 
+          ##
+          # Read timestamp this batch was returned from.
+          # This applies to the range of results from the query's `start_cursor` (or
+          # the beginning of the query if no cursor was given) to this batch's
+          # `end_cursor` (not the query's `end_cursor`).
+          #
+          # In a single transaction, subsequent query result batches for the same query
+          # can have a greater timestamp. Each batch's read timestamp
+          # is valid for all preceding batches.
+          # This value will not be set for eventually consistent queries in Cloud
+          # Datastore.
+          attr_reader :batch_read_time
+
+          ##
+          # Time at which the entities are being read. This would not be
+          # older than 270 seconds.
+          attr_reader :read_time
+
           ##
           # @private
           attr_accessor :service, :namespace, :cursors, :query
@@ -162,8 +180,8 @@ module Google
               # Reduce the limit by the number of entities returned in the current batch
               query.limit.value -= count
             end
-            query_res = service.run_query query, namespace
-            self.class.from_grpc query_res, service, namespace, query
+            query_res = service.run_query query, namespace, read_time: read_time
+            self.class.from_grpc query_res, service, namespace, query, read_time
           end
 
           ##
@@ -360,7 +378,7 @@ module Google
           ##
           # @private New Dataset::QueryResults from a
           # Google::Dataset::V1::RunQueryResponse object.
-          def self.from_grpc query_res, service, namespace, query
+          def self.from_grpc query_res, service, namespace, query, read_time = nil
             r, c = Array(query_res.batch.entity_results).map do |result|
               [Entity.from_grpc(result.entity), Cursor.from_grpc(result.cursor)]
             end.transpose
@@ -373,6 +391,8 @@ module Google
               qr.service = service
               qr.namespace = namespace
               qr.query = query_res.query || query
+              qr.instance_variable_set :@read_time, read_time
+              qr.instance_variable_set :@batch_read_time, query_res.batch.read_time
             end
           end
 

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

@@ -337,6 +337,8 @@ module Google
         #   [Eventual Consistency in Google Cloud
         #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
         #   for more information.
+        # @param [Time] read_time Reads entities as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
         #
         # @return [Google::Cloud::Datastore::Entity, nil]
         #
@@ -355,12 +357,12 @@ module Google
         #
         #   task = datastore.find "Task", "sampleTask"
         #
-        def find key_or_kind, id_or_name = nil, consistency: nil
+        def find key_or_kind, id_or_name = nil, consistency: nil, read_time: nil
           key = key_or_kind
           unless key.is_a? Google::Cloud::Datastore::Key
             key = Key.new key_or_kind, id_or_name
           end
-          find_all(key, consistency: consistency).first
+          find_all(key, consistency: consistency, read_time: read_time).first
         end
         alias get find
 
@@ -377,6 +379,8 @@ module Google
         #   [Eventual Consistency in Google Cloud
         #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
         #   for more information.
+        # @param [Time] read_time Reads entities as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
         #
         # @return [Google::Cloud::Datastore::Dataset::LookupResults]
         #
@@ -389,12 +393,12 @@ module Google
         #   task_key2 = datastore.key "Task", "sampleTask2"
         #   tasks = datastore.find_all task_key1, task_key2
         #
-        def find_all *keys, consistency: nil
+        def find_all *keys, consistency: nil, read_time: nil
           ensure_service!
           check_consistency! consistency
           lookup_res = service.lookup(*Array(keys).flatten.map(&:to_grpc),
-                                      consistency: consistency)
-          LookupResults.from_grpc lookup_res, service, consistency
+                                      consistency: consistency, read_time: read_time)
+          LookupResults.from_grpc lookup_res, service, consistency, nil, read_time
         end
         alias lookup find_all
 
@@ -411,6 +415,8 @@ module Google
         #   [Eventual Consistency in Google Cloud
         #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
         #   for more information.
+        # @param [Time] read_time Reads entities as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
         #
         # @return [Google::Cloud::Datastore::Dataset::QueryResults]
         #
@@ -461,16 +467,16 @@ module Google
         #                             done: false
         #   tasks = datastore.run gql_query, namespace: "example-ns"
         #
-        def run query, namespace: nil, consistency: nil
+        def run query, namespace: nil, consistency: nil, read_time: nil
           ensure_service!
           unless query.is_a?(Query) || query.is_a?(GqlQuery)
             raise ArgumentError, "Cannot run a #{query.class} object."
           end
           check_consistency! consistency
           query_res = service.run_query query.to_grpc, namespace,
-                                        consistency: consistency
+                                        consistency: consistency, read_time: read_time
           QueryResults.from_grpc query_res, service, namespace,
-                                 query.to_grpc.dup
+                                 query.to_grpc.dup, read_time
         end
         alias run_query run
 
@@ -482,6 +488,8 @@ module Google
         # @param [Symbol] consistency The non-transactional read consistency to
         #   use. Cannot be set to `:strong` for global queries. Accepted values
         #   are `:eventual` and `:strong`.
+        # @param [Time] read_time Reads entities as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
         #
         #   The default consistency depends on the type of query used. See
         #   [Eventual Consistency in Google Cloud
@@ -545,14 +553,14 @@ module Google
         #                             done: false
         #   res = datastore.run_aggregation gql_query, namespace: "example-ns"
         #
-        def run_aggregation aggregate_query, namespace: nil, consistency: nil
+        def run_aggregation aggregate_query, namespace: nil, consistency: nil, read_time: nil
           ensure_service!
           unless aggregate_query.is_a?(AggregateQuery) || aggregate_query.is_a?(GqlQuery)
             raise ArgumentError, "Cannot run a #{aggregate_query.class} object."
           end
           check_consistency! consistency
           aggregate_query_res = service.run_aggregation_query aggregate_query.to_grpc, namespace,
-                                                              consistency: consistency
+                                                              consistency: consistency, read_time: read_time
           AggregateQueryResults.from_grpc aggregate_query_res
         end
 
@@ -677,6 +685,9 @@ module Google
         # @see https://cloud.google.com/datastore/docs/concepts/transactions
         #   Transactions
         #
+        # @param [Time] read_time Reads entities at the given time.
+        #   This may not be older than 60 seconds. Optional
+        #
         # @yield [tx] a block yielding a new transaction
         # @yieldparam [ReadOnlyTransaction] tx the transaction object
         #
@@ -698,8 +709,8 @@ module Google
         #     end
         #   end
         #
-        def read_only_transaction
-          tx = ReadOnlyTransaction.new service
+        def read_only_transaction read_time: nil
+          tx = ReadOnlyTransaction.new service, read_time: read_time
           return tx unless block_given?
 
           begin
@@ -970,6 +981,38 @@ module Google
           entity
         end
 
+        ##
+        # Create a new Filter instance. This is a convenience method to make the
+        # creation of Filter objects easier.
+        #
+        # @param name [String] The property to filter by.
+        # @param operator [String] The operator to filter by. Defaults to nil.
+        # @param value The value to compare the property to. Defaults to nil.
+        #       Possible values are:
+        #         - Integer
+        #         - Float/BigDecimal
+        #         - String
+        #         - Boolean
+        #         - Array
+        #         - Date/Time
+        #         - StringIO
+        #         - Google::Cloud::Datastore::Key
+        #         - Google::Cloud::Datastore::Entity
+        #         - nil
+        #
+        # @return [Google::Cloud::Datastore::Filter]
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = datastore.filter("done", "=", false)
+        #
+        def filter name, operator, value
+          Filter.new name, operator, value
+        end
+
         protected
 
         ##

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

@@ -0,0 +1,222 @@
+# Copyright 2023 Google LLC
+#
+# 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
+#
+#     https://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/v1"
+
+module Google
+  module Cloud
+    module Datastore
+      ##
+      # Filter
+      #
+      # Represents the filter criteria for a datastore query.
+      #
+      # @example Run a query with a simple property filter.
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
+      #   filter = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+      #
+      #   query = Google::Cloud::Datastore::Query.new
+      #   query.kind("Task")
+      #        .where(filter)
+      #
+      #   tasks = datastore.run query
+      #
+      # @example Construct a composite filter with a logical OR.
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
+      #   filter = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+      #                                            .or("priority", ">=", "4")
+      #
+      #   query = Google::Cloud::Datastore::Query.new
+      #   query.kind("Task")
+      #        .where(filter)
+      #
+      #   tasks = datastore.run query
+      #
+      # @example Construct a composite filter by combining multiple filters.
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new
+      #
+      #   filter_1 = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+      #   filter_2 = Google::Cloud::Datastore::Filter.new("priority", ">=", "4")
+      #   filter = filter_1.or(filter_2)
+      #
+      #   query = Google::Cloud::Datastore::Query.new
+      #   query.kind("Task")
+      #        .where(filter)
+      #
+      #   tasks = datastore.run query
+      #
+      class Filter
+        ##
+        # @private Object of type
+        # Google::Cloud::Datastore::V1::Filter
+        attr_accessor :grpc
+
+        ##
+        # Creates a new Filter.
+        #
+        # @example
+        #   require "google/cloud/datastore"
+        #
+        #   filter = Google::Cloud::Datastore::Filter.new("done", "=", "false")
+        #
+        def initialize name, operator, value
+          @grpc = create_property_filter name, operator, value
+        end
+
+        ##
+        # Joins two filters with an AND operator.
+        #
+        # @overload and(name, operator, value)
+        #   Joins the filter with a property filter
+        #   @param name [String]
+        #   @param operator [String]
+        #   @param value
+        #
+        # @overload and(filter)
+        #   Joins the filter with a Filter object
+        #   @param filter [Filter]
+        #
+        # @example Join the filter with a property filter
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .and("priority", ">=", 4)
+        #
+        # @example Join the filter with a filter object
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter_1 = Google::Cloud::Filter.new("done", "=", false)
+        #   filter_2 = Google::Cloud::Filter.new("priority", ">=", 4)
+        #
+        #   filter = filter_1.and(filter_2)
+        #
+        def and name_or_filter, operator = nil, value = nil
+          combine_filters composite_filter_and, name_or_filter, operator, value
+        end
+
+        ##
+        # Joins two filters with an OR operator.
+        #
+        # @overload or(name, operator, value)
+        #   Joins the filter with a property filter
+        #   @param name [String] The property to filter by.
+        #   @param operator [String] The operator to filter by. Defaults to nil.
+        #   @param value [Object] The value to compare the property to. Defaults to nil.
+        #       Possible values are:
+        #         - Integer
+        #         - Float/BigDecimal
+        #         - String
+        #         - Boolean
+        #         - Array
+        #         - Date/Time
+        #         - StringIO
+        #         - Google::Cloud::Datastore::Key
+        #         - Google::Cloud::Datastore::Entity
+        #         - nil
+        #
+        # @overload or(filter)
+        #   Joins the filter with a Filter object
+        #   @param flter [Filter]
+        #
+        # @example Join the filter with a property filter
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .or("priority", ">=", 4)
+        #
+        # @example Join the filter with a filter object
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter_1 = Google::Cloud::Filter.new("done", "=", false)
+        #   filter_2 = Google::Cloud::Filter.new("priority", ">=", 4)
+        #
+        #   filter = filter_1.or(filter_2)
+        #
+        def or name_or_filter, operator = nil, value = nil
+          combine_filters composite_filter_or, name_or_filter, operator, value
+        end
+
+        # @private
+        def to_grpc
+          @grpc
+        end
+
+        protected
+
+        ##
+        # @private
+        #
+        # Combines self.grpc and (name_or_filter, operator, value)
+        # into the new_filter object with the specified AND/OR operator
+        def combine_filters new_filter, name_or_filter, operator, value
+          new_filter.composite_filter.filters << to_grpc
+          new_filter.composite_filter.filters << if name_or_filter.is_a? Google::Cloud::Datastore::Filter
+                                                   name_or_filter.to_grpc
+                                                 else
+                                                   create_property_filter name_or_filter, operator, value
+                                                 end
+          dup.tap do |f|
+            f.grpc = new_filter
+          end
+        end
+
+        ##
+        # @private
+        def composite_filter_and
+          Google::Cloud::Datastore::V1::Filter.new(
+            composite_filter: Google::Cloud::Datastore::V1::CompositeFilter.new(op: :AND)
+          )
+        end
+
+        ##
+        # @private
+        def composite_filter_or
+          Google::Cloud::Datastore::V1::Filter.new(
+            composite_filter: Google::Cloud::Datastore::V1::CompositeFilter.new(op: :OR)
+          )
+        end
+
+        ##
+        # @private
+        def create_property_filter name, operator, value
+          Google::Cloud::Datastore::V1::Filter.new(
+            property_filter: Google::Cloud::Datastore::V1::PropertyFilter.new(
+              property: Google::Cloud::Datastore::V1::PropertyReference.new(
+                name: name
+              ),
+              op: Convert.to_prop_filter_op(operator),
+              value: Convert.to_value(value)
+            )
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -16,6 +16,7 @@
 require "google/cloud/datastore/entity"
 require "google/cloud/datastore/key"
 require "google/cloud/datastore/aggregate_query"
+require "google/cloud/datastore/filter"
 
 module Google
   module Cloud
@@ -96,6 +97,27 @@ module Google
         ##
         # Add a property filter to the query.
         #
+        # @overload and(name, operator, value)
+        #   Joins the filter with a property filter
+        #   @param name [String] The property to filter by.
+        #   @param operator [String] The operator to filter by. Defaults to nil.
+        #   @param value [Object] The value to compare the property to. Defaults to nil.
+        #       Possible values are:
+        #         - Integer
+        #         - Float/BigDecimal
+        #         - String
+        #         - Boolean
+        #         - Array
+        #         - Date/Time
+        #         - StringIO
+        #         - Google::Cloud::Datastore::Key
+        #         - Google::Cloud::Datastore::Entity
+        #         - nil
+        #
+        # @overload and(filter)
+        #   Joins the filter with a Filter object
+        #   @param filter [Filter]
+        #
         # @example
         #   require "google/cloud/datastore"
         #
@@ -119,6 +141,34 @@ module Google
         #
         #   tasks = datastore.run query
         #
+        # @example Add a composite "AND" filter:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .and("priority", ">=", 4)
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where(filter)
+        #
+        #   tasks = datastore.run query
+        #
+        # @example Add a composite "OR" filter:
+        #   require "google/cloud/datastore"
+        #
+        #   datastore = Google::Cloud::Datastore.new
+        #
+        #   filter = Google::Cloud::Filter.new("done", "=", false)
+        #                                 .or("priority", ">=", 4)
+        #
+        #   query = Google::Cloud::Datastore::Query.new
+        #   query.kind("Task")
+        #        .where(filter)
+        #
+        #   tasks = datastore.run query
+        #
         # @example Add an inequality filter on a **single** property only:
         #   require "google/cloud/datastore"
         #
@@ -177,22 +227,18 @@ module Google
         #
         #   tasks = datastore.run query
         #
-        def where name, operator, value
+        def where name_or_filter, operator = nil, value = nil
           @grpc.filter ||= Google::Cloud::Datastore::V1::Filter.new(
             composite_filter: Google::Cloud::Datastore::V1::CompositeFilter.new(
               op: :AND
             )
           )
-          @grpc.filter.composite_filter.filters << \
-            Google::Cloud::Datastore::V1::Filter.new(
-              property_filter: Google::Cloud::Datastore::V1::PropertyFilter.new(
-                property: Google::Cloud::Datastore::V1::PropertyReference.new(
-                  name: name
-                ),
-                op: Convert.to_prop_filter_op(operator),
-                value: Convert.to_value(value)
-              )
-            )
+          if name_or_filter.is_a? Google::Cloud::Datastore::Filter
+            @grpc.filter.composite_filter.filters << name_or_filter.to_grpc
+          else
+            @grpc.filter.composite_filter.filters << \
+              Google::Cloud::Datastore::Filter.new(name_or_filter, operator, value).to_grpc
+          end
 
           self
         end

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

@@ -59,13 +59,22 @@ module Google
         # @private The Service object.
         attr_accessor :service
 
+        ##
+        # Reads entities at the given time.
+        # This may not be older than 60 seconds.
+        attr_reader :read_time
+
         ##
         # @private Creates a new ReadOnlyTransaction instance.
         # Takes a Service instead of project and Credentials.
         #
-        def initialize service
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
+        #
+        def initialize service, read_time: nil
           @service = service
           reset!
+          @read_time = read_time
           start
         end
 
@@ -194,9 +203,8 @@ module Google
         #
         def start
           raise TransactionError, "Transaction already opened." unless @id.nil?
-
           ensure_service!
-          tx_res = service.begin_transaction read_only: true
+          tx_res = service.begin_transaction read_only: true, read_time: @read_time
           @id = tx_res.transaction
         end
         alias begin_transaction start

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

@@ -52,6 +52,7 @@ module Google
             config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}/databases/#{database}" }
           end
         end
+
         attr_accessor :mocked_service
 
         ##
@@ -63,20 +64,19 @@ module Google
 
         ##
         # Look up entities by keys.
-        def lookup *keys, consistency: nil, transaction: nil
-          read_options = generate_read_options consistency, transaction
-
+        def lookup *keys, consistency: nil, transaction: nil, read_time: nil
+          read_options = generate_read_options consistency, transaction, read_time
           service.lookup project_id: project, database_id: database, keys: keys, read_options: read_options
         end
 
         # Query for entities.
-        def run_query query, namespace = nil, consistency: nil, transaction: nil
+        def run_query query, namespace = nil, consistency: nil, transaction: nil, read_time: nil
           gql_query = nil
           if query.is_a? Google::Cloud::Datastore::V1::GqlQuery
             gql_query = query
             query = nil
           end
-          read_options = generate_read_options consistency, transaction
+          read_options = generate_read_options consistency, transaction, read_time
           if namespace
             partition_id = Google::Cloud::Datastore::V1::PartitionId.new(
               namespace_id: namespace
@@ -92,13 +92,13 @@ module Google
         end
 
         ## Query for aggregates
-        def run_aggregation_query query, namespace = nil, consistency: nil, transaction: nil
+        def run_aggregation_query query, namespace = nil, consistency: nil, transaction: nil, read_time: nil
           gql_query = nil
           if query.is_a? Google::Cloud::Datastore::V1::GqlQuery
             gql_query = query
             query = nil
           end
-          read_options = generate_read_options consistency, transaction
+          read_options = generate_read_options consistency, transaction, read_time
           if namespace
             partition_id = Google::Cloud::Datastore::V1::PartitionId.new(
               namespace_id: namespace
@@ -114,11 +114,13 @@ module Google
 
         ##
         # Begin a new transaction.
-        def begin_transaction read_only: nil, previous_transaction: nil
+        def begin_transaction read_only: nil, previous_transaction: nil, read_time: nil
           if read_only
             transaction_options = Google::Cloud::Datastore::V1::TransactionOptions.new
             transaction_options.read_only = \
-              Google::Cloud::Datastore::V1::TransactionOptions::ReadOnly.new
+              Google::Cloud::Datastore::V1::TransactionOptions::ReadOnly.new \
+                read_time: read_time_to_timestamp(read_time)
+
           end
           if previous_transaction
             transaction_options ||= \
@@ -152,7 +154,7 @@ module Google
 
         protected
 
-        def generate_read_options consistency, transaction
+        def generate_read_options consistency, transaction, read_time
           if consistency == :eventual
             return Google::Cloud::Datastore::V1::ReadOptions.new(
               read_consistency: :EVENTUAL
@@ -165,9 +167,25 @@ module Google
             return Google::Cloud::Datastore::V1::ReadOptions.new(
               transaction: transaction
             )
+          elsif read_time
+            return Google::Cloud::Datastore::V1::ReadOptions.new(
+              read_time: read_time_to_timestamp(read_time)
+            )
           end
           nil
         end
+
+        def read_time_to_timestamp time
+          return nil if time.nil?
+
+          # Force the object to be a Time object.
+          time = time.to_time.utc
+
+          Google::Protobuf::Timestamp.new(
+            seconds: time.to_i,
+            nanos: time.usec * 1000
+          )
+        end
       end
     end
   end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Datastore
-      VERSION = "2.5.0".freeze
+      VERSION = "2.7.0".freeze
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-datastore
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Mike Moore
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-02-09 00:00:00.000000000 Z
+date: 2023-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -210,6 +210,7 @@ files:
 - lib/google/cloud/datastore/dataset/query_results.rb
 - lib/google/cloud/datastore/entity.rb
 - lib/google/cloud/datastore/errors.rb
+- lib/google/cloud/datastore/filter.rb
 - lib/google/cloud/datastore/gql_query.rb
 - lib/google/cloud/datastore/key.rb
 - lib/google/cloud/datastore/properties.rb