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

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

Query

Represents the search criteria against a Datastore.

Inherits

  • Object

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task").
  where("done", "=", false).
  where("priority", ">=", 4).
  order("priority", :desc)

tasks = datastore.run query

Run the query within a namespace with the namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").
  where("done", "=", false)
tasks = datastore.run query, namespace: "example-ns"

Methods

#aggregate_query

def aggregate_query() -> AggregateQuery

Creates an AggregateQuery object for the query.

Returns
Example 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task")
     .where("done", "=", false)

Create an aggregate query
aggregate_query = query.aggregate_query

#ancestor

def ancestor(parent)

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
query.kind("Task").
  ancestor(task_list_key)

tasks = datastore.run query

#cursor

def cursor(cursor)
Alias Of: #start

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).
  start(page_cursor)

tasks = datastore.run query

#distinct_on

def distinct_on(*names)
Alias Of: #group_by

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").
  order("type").
  order("priority")

tasks = datastore.run query

#filter

def and(name, operator, value)
def and(filter)
Alias Of: #where

Add a property filter to the query.

Overloads 
def and(name, operator, value)
Joins the filter with a property filter
Parameters
  • name (String) — The property to filter by.
  • operator (String) — The operator to filter by. Defaults to nil.
  • 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
def and(filter)
Joins the filter with a Filter object
Parameter
Examples 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task").
  where("done", "=", false)

tasks = datastore.run query

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).
  where("priority", ">=", 4)

tasks = datastore.run query

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

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

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)).
  where("created", "<", Time.utc(2000, 1, 1))

tasks = datastore.run query

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").
  where("tag", "=", "programming")

tasks = datastore.run query

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").
  where("tag", "<", "math")

tasks = datastore.run query

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"))

tasks = datastore.run query

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)

tasks = datastore.run query

#group_by

def group_by(*names)
Aliases

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").
  order("type").
  order("priority")

tasks = datastore.run query

#initialize

def initialize() -> Query

Returns a new query object.

Returns
  • (Query) — a new instance of Query
Example 
require "google/cloud/datastore"

query = Google::Cloud::Datastore::Query.new

#kind

def kind(*kinds)

Add the kind of entities to query.

Special entity kinds such as namespace, kind, and property can be used for metadata queries.

Example 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind "Task"

tasks = datastore.run query

#limit

def limit(num)

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)

tasks = datastore.run query

#offset

def offset(num)

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).
  offset(10)

tasks = datastore.run query

#order

def order(name, direction = :asc)

Sort the results by a property name. By default, an ascending sort order will be used. To sort in descending order, provide a second argument of a string or symbol that starts with "d".

Examples

With ascending sort order:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task").
  order("created")

tasks = datastore.run query

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)

tasks = datastore.run query

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).
  order("created")

tasks = datastore.run query

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).
  order("priority").
  order("created")

tasks = datastore.run query

#projection

def projection(*names)
Alias Of: #select

Retrieve only select properties from the matched entities.

Examples 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task").
  select("priority", "percent_complete")

priorities = []
percent_completes = []
datastore.run(query).each do |t|
  priorities << t["priority"]
  percent_completes << t["percent_complete"]
end

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__")

keys = datastore.run(query).map(&:key)

#select

def select(*names)
Aliases

Retrieve only select properties from the matched entities.

Examples 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task").
  select("priority", "percent_complete")

priorities = []
percent_completes = []
datastore.run(query).each do |t|
  priorities << t["priority"]
  percent_completes << t["percent_complete"]
end

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__")

keys = datastore.run(query).map(&:key)

#start

def start(cursor)
Aliases

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).
  start(page_cursor)

tasks = datastore.run query

#where

def and(name, operator, value)
def and(filter)
Aliases

Add a property filter to the query.

Overloads 
def and(name, operator, value)
Joins the filter with a property filter
Parameters
  • name (String) — The property to filter by.
  • operator (String) — The operator to filter by. Defaults to nil.
  • 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
def and(filter)
Joins the filter with a Filter object
Parameter
Examples 
require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task").
  where("done", "=", false)

tasks = datastore.run query

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).
  where("priority", ">=", 4)

tasks = datastore.run query

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

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

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)).
  where("created", "<", Time.utc(2000, 1, 1))

tasks = datastore.run query

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").
  where("tag", "=", "programming")

tasks = datastore.run query

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").
  where("tag", "<", "math")

tasks = datastore.run query

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"))

tasks = datastore.run query

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)

tasks = datastore.run query