Class: Google::Cloud::Firestore::Query

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

Overview

Query

Represents a query to the Firestore API.

Instances of this class are immutable. All methods that refine the query return new instances.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Create a query
query = firestore.col(:cities).select(:population)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Direct Known Subclasses

CollectionReference

Instance Method Summary collapse

Instance Method Details

#end_at(*values) ⇒ Query

Ends query results at a set of field values. The result set will include the document specified by values.

If the current query already has specified end_before or end_at, this will overwrite it.

The values provided here are for the field paths provides to order. Values provided to end_at without an associated field path provided to order will result in an error.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.end_at("NYC").order(firestore.document_id)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • values (Object, Array<Object>) —

    The field value to end the query at.

Returns:

  • (Query) —

    New query with end_at called on it.



517
518
519
520
521
522
523
524
525
526
527
 
# File 'lib/google/cloud/firestore/query.rb', line 517

def end_at *values
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  values = values.flatten.map { |value| Convert.raw_to_value value }
  new_query.end_at = Google::Firestore::V1beta1::Cursor.new(
    values: values, before: false
  )

  Query.start new_query, parent_path, client
end

#end_before(*values) ⇒ Query

Ends query results before a set of field values. The result set will not include the document specified by values.

If the current query already has specified end_before or end_at, this will overwrite it.

The values provided here are for the field paths provides to order. Values provided to end_before without an associated field path provided to order will result in an error.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.end_before("NYC").order(firestore.document_id)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • values (Object, Array<Object>) —

    The field value to end the query before.

Returns:

  • (Query) —

    New query with end_before called on it.



474
475
476
477
478
479
480
481
482
483
484
 
# File 'lib/google/cloud/firestore/query.rb', line 474

def end_before *values
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  values = values.flatten.map { |value| Convert.raw_to_value value }
  new_query.end_at = Google::Firestore::V1beta1::Cursor.new(
    values: values, before: true
  )

  Query.start new_query, parent_path, client
end

#get {|documents| ... } ⇒ Enumerator<DocumentSnapshot> Also known as: run

Retrieves document snapshots for the query.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.select(:population)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Yields:

  • (documents) —

    The block for accessing the document snapshots.

Yield Parameters:

Returns:



552
553
554
555
556
557
558
559
560
561
562
 
# File 'lib/google/cloud/firestore/query.rb', line 552

def get
  ensure_service!

  return enum_for(:run) unless block_given?

  results = service.run_query parent_path, @query
  results.each do |result|
    next if result.document.nil?
    yield DocumentSnapshot.from_query_result(result, client)
  end
end

#limit(num) ⇒ Query

Limits a query to return a fixed number of results. If the current query already has a limit set, this will overwrite it.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.offset(10).limit(5)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • num (Integer) —

    The maximum number of results to return.

Returns:

  • (Query) —

    New query with limit called on it.



348
349
350
351
352
353
354
355
 
# File 'lib/google/cloud/firestore/query.rb', line 348

def limit num
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  new_query.limit = Google::Protobuf::Int32Value.new(value: num)

  Query.start new_query, parent_path, client
end

#offset(num) ⇒ Query

Skips to an offset in a query. If the current query already has specified an offset, this will overwrite it.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.limit(5).offset(10)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • num (Integer) —

    The number of results to skip.

Returns:

  • (Query) —

    New query with offset called on it.



316
317
318
319
320
321
322
323
 
# File 'lib/google/cloud/firestore/query.rb', line 316

def offset num
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  new_query.offset = num

  Query.start new_query, parent_path, client
end

#order(field, direction = :asc) ⇒ Query Also known as: order_by

Specifies an "order by" clause on a field.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.order(:name)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Order by name descending:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.order(:name, :desc)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • field (FieldPath, String, Symbol) —

    A field path to order results with.

    If a FieldPath object is not provided then the field will be treated as a dotted string, meaning the string represents individual fields joined by ".". Fields containing ~, *, /, [, ], and . cannot be in a dotted string, and should provided using a FieldPath object instead.

  • direction (String, Symbol) (defaults to: :asc) —

    The direction to order the results by. Values that start with "a" are considered ascending. Values that start with "d" are considered descending. Default is ascending. Optional.

Returns:

  • (Query) —

    New query with order called on it.



276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
 
# File 'lib/google/cloud/firestore/query.rb', line 276

def order field, direction = :asc
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  field = FieldPath.parse field unless field.is_a? FieldPath

  new_query.order_by << StructuredQuery::Order.new(
    field: StructuredQuery::FieldReference.new(
      field_path: field.formatted_string
    ),
    direction: order_direction(direction)
  )

  Query.start new_query, parent_path, client
end

#select(*fields) ⇒ Query

Restricts documents matching the query to return only data for the provided fields.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.select(:population)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • fields (FieldPath, String, Symbol, Array<FieldPath|String|Symbol>) —

    A field path to filter results with and return only the specified fields. One or more field paths can be specified.

    If a FieldPath object is not provided then the field will be treated as a dotted string, meaning the string represents individual fields joined by ".". Fields containing ~, *, /, [, ], and . cannot be in a dotted string, and should provided using a FieldPath object instead.

Returns:

  • (Query) —

    New query with select called on it.



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/google/cloud/firestore/query.rb', line 87

def select *fields
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  field_refs = fields.flatten.compact.map do |field|
    field = FieldPath.parse field unless field.is_a? FieldPath
    StructuredQuery::FieldReference.new \
      field_path: field.formatted_string
  end

  new_query.select ||= StructuredQuery::Projection.new
  field_refs.each do |field_ref|
    new_query.select.fields << field_ref
  end

  Query.start new_query, parent_path, client
end

#start_after(*values) ⇒ Query

Starts query results after a set of field values. The result set will not include the document specified by values.

If the current query already has specified start_at or start_after, this will overwrite it.

The values provided here are for the field paths provides to order. Values provided to start_after without an associated field path provided to order will result in an error.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.start_after("NYC").order(firestore.document_id)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • values (Object, Array<Object>) —

    The field value to start the query after.

Returns:

  • (Query) —

    New query with start_after called on it.



431
432
433
434
435
436
437
438
439
440
441
 
# File 'lib/google/cloud/firestore/query.rb', line 431

def start_after *values
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  values = values.flatten.map { |value| Convert.raw_to_value value }
  new_query.start_at = Google::Firestore::V1beta1::Cursor.new(
    values: values, before: false
  )

  Query.start new_query, parent_path, client
end

#start_at(*values) ⇒ Query

Starts query results at a set of field values. The result set will include the document specified by values.

If the current query already has specified start_at or start_after, this will overwrite it.

The values provided here are for the field paths provides to order. Values provided to start_at without an associated field path provided to order will result in an error.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.start_at("NYC").order(firestore.document_id)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • values (Object, Array<Object>) —

    The field value to start the query at.

Returns:

  • (Query) —

    New query with start_at called on it.



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

def start_at *values
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  values = values.flatten.map { |value| Convert.raw_to_value value }
  new_query.start_at = Google::Firestore::V1beta1::Cursor.new(
    values: values, before: true
  )

  Query.start new_query, parent_path, client
end

#where(field, operator, value) ⇒ Query

Filters the query on a field.

Examples:

require "google/cloud/firestore"

firestore = Google::Cloud::Firestore.new

# Get a collection reference
cities_col = firestore.col "cities"

# Create a query
query = cities_col.where(:population, :>=, 1000000)

query.get do |city|
  puts "#{city.document_id} has #{city[:population]} residents."
end

Parameters:

  • field (FieldPath, String, Symbol) —

    A field path to filter results with.

    If a FieldPath object is not provided then the field will be treated as a dotted string, meaning the string represents individual fields joined by ".". Fields containing ~, *, /, [, ], and . cannot be in a dotted string, and should provided using a FieldPath object instead.

  • operator (String, Symbol) —

    The operation to compare the field to. Acceptable values include:

    • less than: <, lt
    • less than or equal: <=, lte
    • greater than: >, gt
    • greater than or equal: >=, gte
    • equal: =, ==, eq, eql, is
  • value (Object) —

    A value the field is compared to.

Returns:

  • (Query) —

    New query with where called on it.



215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/google/cloud/firestore/query.rb', line 215

def where field, operator, value
  new_query = @query.dup
  new_query ||= StructuredQuery.new

  field = FieldPath.parse field unless field.is_a? FieldPath

  new_query.where ||= default_filter
  new_query.where.composite_filter.filters << \
    filter(field.formatted_string, operator, value)

  Query.start new_query, parent_path, client
end