Class: Google::Cloud::Datastore::Dataset::LookupResults

Inherits:
Array
  • Object
show all
Defined in:
lib/google/cloud/datastore/dataset/lookup_results.rb

Overview

LookupResults is a special case Array with additional values. A LookupResults object is returned from #find_all and contains the entities as well as the Keys that were deferred from the results and the Entities that were missing in the dataset.

Please be cautious when treating the LookupResults as an Array. Many common Array methods will return a new Array instance.

Examples:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

tasks = datastore.find_all task_key1, task_key2, task_key3
tasks.size #=> 3
tasks.deferred #=> []
tasks.missing #=> []

Caution, many Array methods will return a new Array instance:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

tasks = datastore.find_all task_key1, task_key2, task_key3
tasks.size #=> 3
tasks.deferred #=> []
tasks.missing #=> []
descriptions = tasks.map { |t| t["description"] }
descriptions.size #=> 3
descriptions.deferred #=> raise NoMethodError
descriptions.missing #=> raise NoMethodError

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#deferred ⇒ Array<Google::Cloud::Datastore::Key>

Keys that were not looked up due to resource constraints.

Returns:



73
74
75
 
# File 'lib/google/cloud/datastore/dataset/lookup_results.rb', line 73

def deferred
  @deferred
end

#missing ⇒ Array<Google::Cloud::Datastore::Entity>

Entities not found, with only the key populated.

Returns:



78
79
80
 
# File 'lib/google/cloud/datastore/dataset/lookup_results.rb', line 78

def missing
  @missing
end

#read_time ⇒ Time?

Time at which the entities are being read. This would not be older than 270 seconds.

This is a copy of the input parameter supplied to the Google::Cloud::Datastore::Dataset#find_all function.

Returns:

  • (Time, nil) 


68
69
70
 
# File 'lib/google/cloud/datastore/dataset/lookup_results.rb', line 68

def read_time
  @read_time
end

#response_read_time ⇒ Google::Protobuf::Timestamp

The time at which these entities were read or found missing.

Returns:

  • (Google::Protobuf::Timestamp) 


59
60
61
 
# File 'lib/google/cloud/datastore/dataset/lookup_results.rb', line 59

def response_read_time
  @response_read_time
end

Instance Method Details

#all(request_limit: nil) {|result| ... } ⇒ Enumerator

Retrieves all lookup results by repeatedly loading #next until #next? returns false. Calls the given block once for each result, which is passed as the parameter.

An Enumerator is returned if no block is given.

This method may make several API calls until all lookup results are retrieved. Be sure to use as narrow a search criteria as possible. Please use with caution.

Examples:

Iterating each result by passing a block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", "sampleTask1"
task_key2 = datastore.key "Task", "sampleTask2"
tasks = datastore.find_all task_key1, task_key2
tasks.all do |t|
  puts "Task #{t.key.id} (#cursor)"
end

Using the enumerator by not passing a block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", "sampleTask1"
task_key2 = datastore.key "Task", "sampleTask2"
tasks = datastore.find_all task_key1, task_key2
all_keys = tasks.all.map(&:key)

Limit the number of API calls made:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", "sampleTask1"
task_key2 = datastore.key "Task", "sampleTask2"
tasks = datastore.find_all task_key1, task_key2
tasks.all(request_limit: 10) do |t|
  puts "Task #{t.key.id} (#cursor)"
end

Parameters:

  • request_limit (Integer) (defaults to: nil) —

    The upper limit of API requests to make to load all lookup results. Default is no limit.

Yields:

  • (result) —

    The block for accessing each lookup result.

Yield Parameters:

  • result (Entity) —

    The lookup result object.

Returns:

  • (Enumerator) 


190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/google/cloud/datastore/dataset/lookup_results.rb', line 190

def all request_limit: nil, &block
  request_limit = request_limit.to_i if request_limit
  unless block_given?
    return enum_for :all, request_limit: request_limit
  end
  results = self
  loop do
    results.each(&block)
    if request_limit
      request_limit -= 1
      break if request_limit.negative?
    end
    break unless results.next?
    results = results.next
  end
end

#next ⇒ LookupResults

Retrieve the next page of results.

Examples:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", "sampleTask1"
task_key2 = datastore.key "Task", "sampleTask2"
tasks = datastore.find_all task_key1, task_key2
if tasks.next?
  next_tasks = tasks.next
end

Returns:



128
129
130
131
132
133
134
135
136
 
# File 'lib/google/cloud/datastore/dataset/lookup_results.rb', line 128

def next
  return nil unless next?
  ensure_service!
  lookup_res = @service.lookup(
    *Array(@deferred).flatten.map(&:to_grpc),
    consistency: @consistency, transaction: @transaction, read_time: @read_time
  )
  self.class.from_grpc lookup_res, @service, @consistency, nil, @read_time
end

#next? ⇒ Boolean

Whether there are more results available.

Examples:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", "sampleTask1"
task_key2 = datastore.key "Task", "sampleTask2"
tasks = datastore.find_all task_key1, task_key2
if tasks.next?
  next_tasks = tasks.next
end

Returns:

  • (Boolean) 


107
108
109
 
# File 'lib/google/cloud/datastore/dataset/lookup_results.rb', line 107

def next?
  Array(@deferred).any?
end