Class: Google::Cloud::Firestore::Query
- Inherits:
-
Object
- Object
- Google::Cloud::Firestore::Query
- 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.
Direct Known Subclasses
Class Method Summary collapse
-
.from_json(json, client) ⇒ Query
Deserializes a JSON text string serialized from this class and returns it as a new instance.
Instance Method Summary collapse
-
#aggregate_query ⇒ AggregateQuery
Creates an AggregateQuery object for the query.
-
#end_at(*values) ⇒ Query
Ends query results at a set of field values.
-
#end_before(*values) ⇒ Query
Ends query results before a set of field values.
-
#get(read_time: nil) {|documents| ... } ⇒ Enumerator<DocumentSnapshot>
(also: #run)
Retrieves document snapshots for the query.
-
#limit(num) ⇒ Query
Limits a query to return only the first matching documents.
-
#limit_to_last(num) ⇒ Query
Limits a query to return only the last matching documents.
-
#listen {|callback| ... } ⇒ QueryListener
(also: #on_snapshot)
Listen to this query for changes.
-
#offset(num) ⇒ Query
Skips to an offset in a query.
-
#order(field, direction = :asc) ⇒ Query
(also: #order_by)
Specifies an "order by" clause on a field.
-
#select(*fields) ⇒ Query
Restricts documents matching the query to return only data for the provided fields.
-
#start_after(*values) ⇒ Query
Starts query results after a set of field values.
-
#start_at(*values) ⇒ Query
Starts query results at a set of field values.
-
#to_json(options = nil) ⇒ String
Serializes the instance to a JSON text string.
-
#where(field, operator, value) ⇒ Query
Filters the query on a field.
Class Method Details
.from_json(json, client) ⇒ Query
Deserializes a JSON text string serialized from this class and returns it as a new instance. See also #to_json.
1068 1069 1070 1071 1072 1073 1074 1075 1076 |
# File 'lib/google/cloud/firestore/query.rb', line 1068 def self.from_json json, client raise ArgumentError, "client is required" unless client json = JSON.parse json query_json = json["query"] raise ArgumentError, "Field 'query' is required" unless query_json query = Google::Cloud::Firestore::V1::StructuredQuery.decode_json query_json.to_json start query, json["parent_path"], client, limit_type: json["limit_type"]&.to_sym end |
Instance Method Details
#aggregate_query ⇒ AggregateQuery
Creates an AggregateQuery object for the query.
980 981 982 |
# File 'lib/google/cloud/firestore/query.rb', line 980 def aggregate_query AggregateQuery.new query, parent_path, client end |
#end_at(*values) ⇒ Query
Ends query results at a set of field values. The field values can
be specified explicitly as arguments, or can be specified implicitly
by providing a DocumentSnapshot object instead. 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 are associated with the field paths that have been provided
to order
, and must match the same sort order. An ArgumentError will
be raised if more explicit values are given than are present in
order
.
886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 |
# File 'lib/google/cloud/firestore/query.rb', line 886 def end_at *values raise ArgumentError, "must provide values" if values.empty? if limit_type == :last raise "cannot call end_at after calling limit_to_last" end new_query = @query.dup new_query ||= StructuredQuery.new cursor = values_to_cursor values, new_query cursor.before = false new_query.end_at = cursor Query.start new_query, parent_path, client, limit_type: limit_type end |
#end_before(*values) ⇒ Query
Ends query results before a set of field values. The field values can
be specified explicitly as arguments, or can be specified implicitly
by providing a DocumentSnapshot object instead. 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 are associated with the field paths that have been provided
to order
, and must match the same sort order. An ArgumentError will
be raised if more explicit values are given than are present in
order
.
777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 |
# File 'lib/google/cloud/firestore/query.rb', line 777 def end_before *values raise ArgumentError, "must provide values" if values.empty? if limit_type == :last raise "cannot call end_before after calling limit_to_last" end new_query = @query.dup new_query ||= StructuredQuery.new cursor = values_to_cursor values, new_query cursor.before = true new_query.end_at = cursor Query.start new_query, parent_path, client, limit_type: limit_type end |
#get(read_time: nil) {|documents| ... } ⇒ Enumerator<DocumentSnapshot> Also known as: run
Retrieves document snapshots for the query.
947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 |
# File 'lib/google/cloud/firestore/query.rb', line 947 def get read_time: nil ensure_service! return enum_for :get, read_time: read_time unless block_given? results = service.run_query parent_path, @query, read_time: read_time # Reverse the results for Query#limit_to_last queries since that method reversed the order_by directions. results = results.to_a.reverse if limit_type == :last 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 only the first matching documents.
If the current query already has a limit set, this will overwrite it.
396 397 398 399 400 401 402 403 404 405 406 407 |
# File 'lib/google/cloud/firestore/query.rb', line 396 def limit num if limit_type == :last raise "cannot call limit after calling limit_to_last" end new_query = @query.dup new_query ||= StructuredQuery.new new_query.limit = Google::Protobuf::Int32Value.new value: num Query.start new_query, parent_path, client, limit_type: :first end |
#limit_to_last(num) ⇒ Query
438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 |
# File 'lib/google/cloud/firestore/query.rb', line 438 def limit_to_last num new_query = @query.dup if new_query.nil? || new_query.order_by.nil? || new_query.order_by.empty? raise "specify at least one order clause before calling limit_to_last" end if limit_type != :last # Don't reverse order_by more than once. # Reverse the order_by directions since we want the last results. new_query.order_by.each do |order| order.direction = order.direction.to_sym == :DESCENDING ? :ASCENDING : :DESCENDING end # Swap the cursors to match the reversed query ordering. new_end_at = new_query.start_at.dup new_start_at = new_query.end_at.dup if new_end_at new_end_at.before = !new_end_at.before new_query.end_at = new_end_at end if new_start_at new_start_at.before = !new_start_at.before new_query.start_at = new_start_at end end new_query.limit = Google::Protobuf::Int32Value.new value: num Query.start new_query, parent_path, client, limit_type: :last end |
#listen {|callback| ... } ⇒ QueryListener Also known as: on_snapshot
Listen to this query for changes.
1008 1009 1010 1011 1012 1013 1014 |
# File 'lib/google/cloud/firestore/query.rb', line 1008 def listen &callback raise ArgumentError, "callback required" if callback.nil? ensure_service! QueryListener.new(self, &callback).start end |
#offset(num) ⇒ Query
Skips to an offset in a query. If the current query already has specified an offset, this will overwrite it.
363 364 365 366 367 368 369 370 |
# File 'lib/google/cloud/firestore/query.rb', line 363 def offset num new_query = @query.dup new_query ||= StructuredQuery.new new_query.offset = num Query.start new_query, parent_path, client, limit_type: limit_type end |
#order(field, direction = :asc) ⇒ Query Also known as: order_by
Specifies an "order by" clause on a field.
319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 |
# File 'lib/google/cloud/firestore/query.rb', line 319 def order field, direction = :asc if query_has_cursors? || limit_type == :last raise "cannot call order after calling limit_to_last, start_at, start_after, end_before, or end_at" end 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, limit_type: limit_type end |
#select(*fields) ⇒ Query
Restricts documents matching the query to return only data for the provided fields.
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 |
# File 'lib/google/cloud/firestore/query.rb', line 120 def select *fields new_query = @query.dup new_query ||= StructuredQuery.new fields = Array(fields).flatten.compact fields = [FieldPath.document_id] if fields.empty? 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, limit_type: limit_type end |
#start_after(*values) ⇒ Query
Starts query results after a set of field values. The field values can
be specified explicitly as arguments, or can be specified implicitly
by providing a DocumentSnapshot object instead. 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 are associated with the field paths that have been provided
to order
, and must match the same sort order. An ArgumentError will
be raised if more explicit values are given than are present in
order
.
668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 |
# File 'lib/google/cloud/firestore/query.rb', line 668 def start_after *values raise ArgumentError, "must provide values" if values.empty? if limit_type == :last raise "cannot call start_after after calling limit_to_last" end new_query = @query.dup new_query ||= StructuredQuery.new cursor = values_to_cursor values, new_query cursor.before = false new_query.start_at = cursor Query.start new_query, parent_path, client, limit_type: limit_type end |
#start_at(*values) ⇒ Query
Starts query results at a set of field values. The field values can be
specified explicitly as arguments, or can be specified implicitly by
providing a DocumentSnapshot object instead. 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 are associated with the field paths that have been provided
to order
, and must match the same sort order. An ArgumentError will
be raised if more explicit values are given than are present in
order
.
560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 |
# File 'lib/google/cloud/firestore/query.rb', line 560 def start_at *values raise ArgumentError, "must provide values" if values.empty? if limit_type == :last raise "cannot call start_at after calling limit_to_last" end new_query = @query.dup new_query ||= StructuredQuery.new cursor = values_to_cursor values, new_query cursor.before = true new_query.start_at = cursor Query.start new_query, parent_path, client, limit_type: limit_type end |
#to_json(options = nil) ⇒ String
Serializes the instance to a JSON text string. See also from_json.
1036 1037 1038 1039 1040 1041 1042 1043 |
# File 'lib/google/cloud/firestore/query.rb', line 1036 def to_json = nil query_json = Google::Cloud::Firestore::V1::StructuredQuery.encode_json query { "query" => JSON.parse(query_json), "parent_path" => parent_path, "limit_type" => limit_type }.to_json end |
#where(field, operator, value) ⇒ Query
Filters the query on a field.
254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 |
# File 'lib/google/cloud/firestore/query.rb', line 254 def where field, operator, value if query_has_cursors? raise "cannot call where after calling " \ "start_at, start_after, end_before, or end_at" end new_query = @query.dup new_query ||= StructuredQuery.new field = FieldPath.parse field unless field.is_a? FieldPath new_filter = filter field.formatted_string, operator, value add_filters_to_query new_query, new_filter Query.start new_query, parent_path, client, limit_type: limit_type end |