Class: Google::Cloud::Datastore::Query

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/datastore/query.rb

Overview

Query

Represents the search criteria against a Datastore.

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"

See Also:

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Query

Returns a new query object.

Examples:

require "google/cloud/datastore"

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


65
66
67
 
# File 'lib/google/cloud/datastore/query.rb', line 65

def initialize
  @grpc = Google::Cloud::Datastore::V1::Query.new
end

Instance Method Details

#aggregate_query ⇒ AggregateQuery

Creates an AggregateQuery object for the query.

Examples:

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

Returns:



492
493
494
 
# File 'lib/google/cloud/datastore/query.rb', line 492

def aggregate_query
  AggregateQuery.new @grpc
end

#ancestor(parent) ⇒ Object

Add a filter for entities that inherit from a key.

Examples:

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


263
264
265
266
267
 
# File 'lib/google/cloud/datastore/query.rb', line 263

def ancestor parent
  # Use key if given an entity
  parent = parent.key if parent.respond_to? :key
  where "__key__", "~", parent
end

#group_by(*names) ⇒ Object Also known as: distinct_on

Group results by a list of properties.

Examples:

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


463
464
465
466
467
468
469
470
471
472
 
# File 'lib/google/cloud/datastore/query.rb', line 463

def group_by *names
  names.each do |name|
    grpc_property = Google::Cloud::Datastore::V1::PropertyReference.new(
      name: name
    )
    @grpc.distinct_on << grpc_property
  end

  self
end

#kind(*kinds) ⇒ Object

Add the kind of entities to query.

Special entity kinds such as __namespace__, __kind__, and __property__ can be used for metadata queries.

Examples:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

tasks = datastore.run query


86
87
88
89
90
91
92
93
94
95
 
# File 'lib/google/cloud/datastore/query.rb', line 86

def kind *kinds
  kinds.each do |kind|
    grpc_kind = Google::Cloud::Datastore::V1::KindExpression.new(
      name: kind
    )
    @grpc.kind << grpc_kind
  end

  self
end

#limit(num) ⇒ Object

Set a limit on the number of results to be returned.

Examples:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new
query.kind("Task").
  limit(5)

tasks = datastore.run query


347
348
349
350
351
 
# File 'lib/google/cloud/datastore/query.rb', line 347

def limit num
  @grpc.limit = Google::Protobuf::Int32Value.new value: num

  self
end

#offset(num) ⇒ Object

Set an offset for the results to be returned.

Examples:

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


368
369
370
371
372
 
# File 'lib/google/cloud/datastore/query.rb', line 368

def offset num
  @grpc.offset = num

  self
end

#order(name, direction = :asc) ⇒ Object

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


322
323
324
325
326
327
328
329
330
331
 
# File 'lib/google/cloud/datastore/query.rb', line 322

def order name, direction = :asc
  @grpc.order << Google::Cloud::Datastore::V1::PropertyOrder.new(
    property: Google::Cloud::Datastore::V1::PropertyReference.new(
      name: name
    ),
    direction: prop_order_direction(direction)
  )

  self
end

#select(*names) ⇒ Object Also known as: 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)


433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/google/cloud/datastore/query.rb', line 433

def select *names
  names.each do |name|
    grpc_projection = Google::Cloud::Datastore::V1::Projection.new(
      property: Google::Cloud::Datastore::V1::PropertyReference.new(
        name: name
      )
    )
    @grpc.projection << grpc_projection
  end

  self
end

#start(cursor) ⇒ Object Also known as: cursor

Set the cursor to start the results at.

Examples:

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


389
390
391
392
393
394
395
396
397
398
399
400
 
# File 'lib/google/cloud/datastore/query.rb', line 389

def start cursor
  case cursor
  when Cursor
    @grpc.start_cursor = cursor.to_grpc
  when String
    @grpc.start_cursor = Convert.decode_bytes cursor
  else
    raise ArgumentError, "Can't set a cursor using a #{cursor.class}."
  end

  self
end

#and(name, operator, value) ⇒ Object #and(filter) ⇒ Object Also known as: filter

Add a property filter to the query.

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

Overloads:

  • #and(name, operator, value) ⇒ Object

    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
  • #and(filter) ⇒ Object

    Joins the filter with a Filter object

    Parameters:



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/google/cloud/datastore/query.rb', line 230

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