Firestore in Datastore mode API - Class Google::Cloud::Datastore::Dataset::QueryResults (v2.9.0)

Reference documentation and code samples for the Firestore in Datastore mode API class Google::Cloud::Datastore::Dataset::QueryResults.

QueryResults is a special case Array with additional values. A QueryResults object is returned from Dataset#run and contains the Entities from the query as well as the query's cursor and more_results value.

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

Inherits

  • Array

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task")
tasks = datastore.run query

tasks.size #=> 3
tasks.cursor.to_s #=> "c2Vjb25kLXBhZ2UtY3Vyc29y"

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

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task")
tasks = datastore.run query

tasks.size #=> 3
tasks.cursor.to_s #=> "c2Vjb25kLXBhZ2UtY3Vyc29y"
descriptions = tasks.map { |t| t["description"] }
descriptions.size #=> 3
descriptions.cursor #=> raise NoMethodError

Methods

#all

def all(request_limit: nil, &block) { |result| ... } -> Enumerator

Retrieves all query results by repeatedly loading #next until #next? returns false. Calls the given block once for each query 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 query results are retrieved. Be sure to use as narrow a search criteria as possible. Please use with caution.

Parameter
  • request_limit (Integer) (defaults to: nil) — The upper limit of API requests to make to load all query results. Default is no limit.
Yields
  • (result) — The block for accessing each query result.
Yield Parameter
  • result (Entity) — The query result object.
Returns
  • (Enumerator)
Examples

Iterating each query result by passing a block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query
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

query = datastore.query "Task"
tasks = datastore.run query
tasks.all.map(&:key).each do |key|
  puts "Key #{key.id}"
end

Limit the number of API calls made:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query
tasks.all(request_limit: 10) do |t|
  puts "Task #{t.key.id} (#cursor)"
end

#all_with_cursor

def all_with_cursor(request_limit: nil, &block) { |result, cursor| ... } -> Enumerator

Retrieves all query results and cursors by repeatedly loading #next until #next? returns false. Calls the given block once for each result and cursor combination, which are passed as parameters.

An Enumerator is returned if no block is given.

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

Parameter
  • request_limit (Integer) (defaults to: nil) — The upper limit of API requests to make to load all tables. Default is no limit.
Yields
  • (result, cursor) — The block for accessing each query result and cursor.
Yield Parameters
  • result (Entity) — The query result object.
  • cursor (Cursor) — The cursor object.
Returns
  • (Enumerator)
Examples

Iterating all results and cursors by passing a block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query
tasks.all_with_cursor do |task, cursor|
  puts "Task #{task.key.id} (#cursor)"
end

Using the enumerator by not passing a block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query
tasks.all_with_cursor.count # number of result/cursor pairs

Limit the number of API calls made:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query
tasks.all_with_cursor(request_limit: 10) do |task, cursor|
  puts "Task #{task.key.id} (#cursor)"
end

#batch_read_time

def batch_read_time()

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.

#cursor

def cursor() -> Google::Cloud::Datastore::Cursor
Alias Of: #end_cursor

The end_cursor of the QueryResults.

Returns

#cursor_for

def cursor_for(result) -> Cursor

Retrieve the Cursor for the provided result.

Parameter
  • result (Entity) — The entity object to get a cursor for.
Returns
Example 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query

first_task = tasks.first
first_cursor = tasks.cursor_for first_task

#each_with_cursor

def each_with_cursor() { |result, cursor| ... } -> Enumerator

Calls the given block once for each result and cursor combination, which are passed as parameters.

An Enumerator is returned if no block is given.

Yields
  • (result, cursor) — The block for accessing each query result and cursor.
Yield Parameters
  • result (Entity) — The query result object.
  • cursor (Cursor) — The cursor object.
Returns
  • (Enumerator)
Example 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query
tasks.each_with_cursor do |task, cursor|
  puts "Task #{task.key.id} (#cursor)"
end

#end_cursor

def end_cursor() -> Google::Cloud::Datastore::Cursor
Aliases

The end_cursor of the QueryResults.

Returns

#more_after_cursor?

def more_after_cursor?() -> Boolean

Convenience method for determining if the more_results value is :MORE_RESULTS_AFTER_CURSOR

Returns
  • (Boolean)

#more_after_limit?

def more_after_limit?() -> Boolean

Convenience method for determining if the more_results value is :MORE_RESULTS_AFTER_LIMIT

Returns
  • (Boolean)

#more_results

def more_results()

The state of the query after the current batch.

Expected values are:

  • :NOT_FINISHED
  • :MORE_RESULTS_AFTER_LIMIT
  • :MORE_RESULTS_AFTER_CURSOR
  • :NO_MORE_RESULTS

#next

def next() -> QueryResults

Retrieve the next page of results.

Returns
Example 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query

if tasks.next?
  next_tasks = tasks.next
end

#next?

def next?() -> Boolean

Whether there are more results available.

Returns
  • (Boolean)
Example 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query "Task"
tasks = datastore.run query

if tasks.next?
  next_tasks = tasks.next
end

#no_more?

def no_more?() -> Boolean

Convenience method for determining if the more_results value is :NO_MORE_RESULTS

Returns
  • (Boolean)

#not_finished?

def not_finished?() -> Boolean

Convenience method for determining if the more_results value is :NOT_FINISHED

Returns
  • (Boolean)

#read_time

def read_time()

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