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

Version latest

• 2.9.0 (latest)
• 2.8.0
• 2.7.1
• 2.6.0
• 2.5.0
• 2.4.0
• 2.3.1
• 2.2.4

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

• (AggregateQuery) — New empty aggregate query.

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

• filter (Filter)

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

• #distinct_on

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

• #projection

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

• #cursor

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

• #filter

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

• filter (Filter)

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