google-cloud-firestore 0.22.0 → 0.23.0

data/lib/google/cloud/firestore/document_listener.rb

@@ -0,0 +1,125 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/firestore/watch/listener"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # An ongoing listen operation on a document reference. This is returned by
+      # calling {DocumentReference#listen}.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Get a document reference
+      #   nyc_ref = firestore.doc "cities/NYC"
+      #
+      #   listener = nyc_ref.listen do |snapshot|
+      #     puts "The population of #{snapshot[:name]} "
+      #     puts "is #{snapshot[:population]}."
+      #   end
+      #
+      #   # When ready, stop the listen operation and close the stream.
+      #   listener.stop
+      #
+      class DocumentListener
+        ##
+        # @private
+        # Creates the watch stream and listener object.
+        def initialize doc_ref, &callback
+          @doc_ref = doc_ref
+          raise ArgumentError if @doc_ref.nil?
+
+          @callback = callback
+          raise ArgumentError if @callback.nil?
+
+          @listener = Watch::Listener.for_doc_ref doc_ref do |query_snp|
+            doc_snp = query_snp.docs.find { |doc| doc.path == @doc_ref.path }
+
+            if doc_snp.nil?
+              doc_snp = DocumentSnapshot.missing \
+                @doc_ref, read_at: query_snp.read_at
+            end
+
+            @callback.call doc_snp
+          end
+        end
+
+        ##
+        # @private
+        def start
+          @listener.start
+          self
+        end
+
+        ##
+        # Stops the client listening for changes.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   listener = nyc_ref.listen do |snapshot|
+        #     puts "The population of #{snapshot[:name]} "
+        #     puts "is #{snapshot[:population]}."
+        #   end
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def stop
+          @listener.stop
+        end
+
+        ##
+        # Whether the client has stopped listening for changes.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   listener = nyc_ref.listen do |snapshot|
+        #     puts "The population of #{snapshot[:name]} "
+        #     puts "is #{snapshot[:population]}."
+        #   end
+        #
+        #   # Checks if the listener is stopped.
+        #   listener.stopped? #=> false
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        #   # Checks if the listener is stopped.
+        #   listener.stopped? #=> true
+        #
+        def stopped?
+          @listener.stopped?
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/firestore/document_reference.rb

@@ -16,6 +16,7 @@
 require "google/cloud/firestore/v1beta1"
 require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/collection_reference"
+require "google/cloud/firestore/document_listener"
 
 module Google
   module Cloud
@@ -147,6 +148,40 @@ module Google
           client.get_all([self]).first
         end
 
+        ##
+        # Listen to this document reference for changes.
+        #
+        # @yield [callback] The block for accessing the document snapshot.
+        # @yieldparam [DocumentSnapshot] snapshot A document snapshot.
+        #
+        # @return [DocumentListener] The ongoing listen operation on the
+        #   document reference.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   listener = nyc_ref.listen do |snapshot|
+        #     puts "The population of #{snapshot[:name]} "
+        #     puts "is #{snapshot[:population]}."
+        #   end
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def listen &callback
+          raise ArgumentError, "callback required" if callback.nil?
+
+          ensure_client!
+
+          DocumentListener.new(self, &callback).start
+        end
+        alias on_snapshot listen
+
         ##
         # The collection the document reference belongs to.
         #

data/lib/google/cloud/firestore/document_snapshot.rb

@@ -17,6 +17,7 @@ require "google/cloud/firestore/v1beta1"
 require "google/cloud/firestore/document_reference"
 require "google/cloud/firestore/collection_reference"
 require "google/cloud/firestore/convert"
+require "google/cloud/firestore/watch/order"
 
 module Google
   module Cloud
@@ -29,6 +30,9 @@ module Google
       #
       # The snapshot can reference a non-existing document.
       #
+      # See {DocumentReference#get}, {DocumentReference#listen},
+      # {Query#get}, {Query#listen}, and {QuerySnapshot#docs}.
+      #
       # @example
       #   require "google/cloud/firestore"
       #
@@ -40,6 +44,22 @@ module Google
       #   # Get the document data
       #   nyc_snap[:population] #=> 1000000
       #
+      # @example Listen to a document reference for changes:
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Get a document reference
+      #   nyc_ref = firestore.doc "cities/NYC"
+      #
+      #   listener = nyc_ref.listen do |snapshot|
+      #     puts "The population of #{snapshot[:name]} "
+      #     puts "is #{snapshot[:population]}."
+      #   end
+      #
+      #   # When ready, stop the listen operation and close the stream.
+      #   listener.stop
+      #
       class DocumentSnapshot
         ##
         # @private The Google::Firestore::V1beta1::Document object.
@@ -118,9 +138,11 @@ module Google
         # @!group Data
 
         ##
-        # Retrieves the document data.
+        # Retrieves the document data. When the document exists the data hash is
+        # frozen and will not allow any changes. When the document does not
+        # exist `nil` will be returned.
         #
-        # @return [Hash] The document data.
+        # @return [Hash, nil] The document data.
         #
         # @example
         #   require "google/cloud/firestore"
@@ -134,7 +156,7 @@ module Google
         #
         def data
           return nil if missing?
-          Convert.fields_to_hash grpc.fields, ref.client
+          @data ||= Convert.fields_to_hash(grpc.fields, ref.client).freeze
         end
         alias fields data
 
@@ -192,8 +214,9 @@ module Google
           end
 
           nodes = field_path.fields.map(&:to_sym)
-          selected_data = data
+          return ref if nodes == [:__name__]
 
+          selected_data = data
           nodes.each do |node|
             unless selected_data.is_a? Hash
               err_msg = "#{field_path.formatted_string} is not " \
@@ -285,11 +308,46 @@ module Google
           grpc.nil?
         end
 
+        ##
+        # @private
+        def <=> other
+          return nil unless other.is_a? DocumentSnapshot
+          return data <=> other.data if path == other.path
+          path <=> other.path
+        end
+
+        ##
+        # @private
+        def eql? other
+          return nil unless other.is_a? DocumentSnapshot
+          return data.eql? other.data if path == other.path
+          path.eql? other.path
+        end
+
+        ##
+        # @private
+        def hash
+          @hash ||= [path, data].hash
+        end
+
+        ##
+        # @private
+        def query_comparisons_for query_grpc
+          @memoized_comps ||= {}
+          if @memoized_comps.key? query_grpc.hash
+            return @memoized_comps[query_grpc.hash]
+          end
+
+          @memoized_comps[query_grpc.hash] = query_grpc.order_by.map do |order|
+            Watch::Order.field_comparison get(order.field.field_path)
+          end
+        end
+
         ##
         # @private New DocumentSnapshot from a
         # Google::Firestore::V1beta1::RunQueryResponse object.
-        def self.from_query_result result, context
-          ref = DocumentReference.from_path result.document.name, context
+        def self.from_query_result result, client
+          ref = DocumentReference.from_path result.document.name, client
           read_at = Convert.timestamp_to_time result.read_time
 
           new.tap do |s|
@@ -299,17 +357,30 @@ module Google
           end
         end
 
+        ##
+        # @private New DocumentSnapshot from a
+        # Google::Firestore::V1beta1::DocumentChange object.
+        def self.from_document document, client, read_at: nil
+          ref = DocumentReference.from_path document.name, client
+
+          new.tap do |s|
+            s.grpc = document
+            s.instance_variable_set :@ref, ref
+            s.instance_variable_set :@read_at, read_at
+          end
+        end
+
         ##
         # @private New DocumentSnapshot from a
         # Google::Firestore::V1beta1::BatchGetDocumentsResponse object.
-        def self.from_batch_result result, context
+        def self.from_batch_result result, client
           ref = nil
           grpc = nil
           if result.result == :found
             grpc = result.found
-            ref = DocumentReference.from_path grpc.name, context
+            ref = DocumentReference.from_path grpc.name, client
           else
-            ref = DocumentReference.from_path result.missing, context
+            ref = DocumentReference.from_path result.missing, client
           end
           read_at = Convert.timestamp_to_time result.read_time
 
@@ -319,6 +390,17 @@ module Google
             s.instance_variable_set :@read_at, read_at
           end
         end
+
+        ##
+        # @private New non-existant DocumentSnapshot from a
+        # DocumentReference object.
+        def self.missing doc_ref, read_at: nil
+          new.tap do |s|
+            s.grpc = nil
+            s.instance_variable_set :@ref, doc_ref
+            s.instance_variable_set :@read_at, read_at
+          end
+        end
       end
     end
   end

data/lib/google/cloud/firestore/field_path.rb

@@ -61,15 +61,15 @@ module Google
         #   user_snap.get(nested_field_path) #=> "Pizza"
         #
         def initialize *fields
-          @fields = fields.flatten.map(&:to_s)
-          @fields.each do |field|
-            raise ArgumentError, "empty paths not allowed" if field.empty?
-          end
+          @fields = fields.flatten.map(&:to_s).freeze
+
+          invalid_fields = @fields.detect(&:empty?)
+          raise ArgumentError, "empty paths not allowed" if invalid_fields
         end
 
         ##
         # @private The individual fields representing the nested field path for
-        # document data.
+        # document data. The fields are frozen.
         #
         # @return [Array<String>] The fields.
         #
@@ -129,9 +129,9 @@ module Google
         #   cities_col = firestore.col "cities"
         #
         #   # Create a query
-        #   query = cities_col.start_at("NYC").order(
+        #   query = cities_col.order(
         #     Google::Cloud::Firestore::FieldPath.document_id
-        #   )
+        #   ).start_at("NYC")
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
@@ -145,6 +145,8 @@ module Google
         # @private Creates a field path object representing the nested fields
         # for document data.
         #
+        # The values are memoized to increase performance.
+        #
         # @param [String] dotted_string A string representing the path of the
         #   document data. The string can represent as a string of individual
         #   fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
@@ -166,15 +168,23 @@ module Google
         #   field_path.fields #=> ["favorites", "food"]
         #
         def self.parse dotted_string
-          return new dotted_string if dotted_string.is_a? Array
+          # Memoize parsed field paths
+          @memoized_field_paths ||= {}
+          if @memoized_field_paths.key? dotted_string
+            return @memoized_field_paths[dotted_string]
+          end
+
+          if dotted_string.is_a? Array
+            return @memoized_field_paths[dotted_string] = new(dotted_string)
+          end
 
           fields = String(dotted_string).split(".")
-          fields.each do |field|
-            if INVALID_FIELD_PATH_CHARS.match field
-              raise ArgumentError, "invalid character, use FieldPath instead"
-            end
+
+          if fields.grep(INVALID_FIELD_PATH_CHARS).any?
+            raise ArgumentError, "invalid character, use FieldPath instead"
           end
-          new fields
+
+          @memoized_field_paths[dotted_string] = new(fields)
         end
 
         ##

data/lib/google/cloud/firestore/query.rb

@@ -15,6 +15,7 @@
 
 require "google/cloud/firestore/v1beta1"
 require "google/cloud/firestore/document_snapshot"
+require "google/cloud/firestore/query_listener"
 require "google/cloud/firestore/convert"
 
 module Google
@@ -40,6 +41,22 @@ module Google
       #     puts "#{city.document_id} has #{city[:population]} residents."
       #   end
       #
+      # @example Listen to a query for changes:
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Create a query
+      #   query = firestore.col(:cities).order(:population, :desc)
+      #
+      #   listener = query.listen do |snapshot|
+      #     puts "The query snapshot has #{snapshot.docs.count} documents "
+      #     puts "and has #{snapshot.changes.count} changes."
+      #   end
+      #
+      #   # When ready, stop the listen operation and close the stream.
+      #   listener.stop
+      #
       class Query
         ##
         # @private The parent path for the query.
@@ -88,13 +105,15 @@ module Google
           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
+          new_query.select = StructuredQuery::Projection.new
           field_refs.each do |field_ref|
             new_query.select.fields << field_ref
           end
@@ -130,7 +149,7 @@ module Google
           new_query ||= StructuredQuery.new
 
           if new_query.from.empty?
-            raise "missing collection_id to specify descendants."
+            raise "missing collection_id to specify descendants"
           end
 
           new_query.from.last.all_descendants = true
@@ -166,7 +185,7 @@ module Google
           new_query ||= StructuredQuery.new
 
           if new_query.from.empty?
-            raise "missing collection_id to specify descendants."
+            raise "missing collection_id to specify descendants"
           end
 
           new_query.from.last.all_descendants = false
@@ -213,14 +232,18 @@ module Google
         #   end
         #
         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_query.where ||= default_filter
-          new_query.where.composite_filter.filters << \
-            filter(field.formatted_string, operator, value)
+          new_filter = filter field.formatted_string, operator, value
+          add_filters_to_query new_query, new_filter
 
           Query.start new_query, parent_path, client
         end
@@ -274,6 +297,11 @@ module Google
         #   end
         #
         def order field, direction = :asc
+          if query_has_cursors?
+            raise "cannot call order after calling " \
+                  "start_at, start_after, end_before, or end_at"
+          end
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -355,108 +383,285 @@ module Google
         end
 
         ##
-        # Starts query results at a set of field values. The result set will
+        # 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 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.
+        # 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`.
         #
-        # @param [Object, Array<Object>] values The field value to start the
-        #   query at.
+        # @param [DocumentSnapshot, Object, Array<Object>] values The field
+        #   values to start the query at.
         #
         # @return [Query] New query with `start_at` called on it.
         #
-        # @example
+        # @example Starting a query at a document reference id
         #   require "google/cloud/firestore"
         #
         #   firestore = Google::Cloud::Firestore.new
         #
         #   # Get a collection reference
         #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
         #
         #   # Create a query
-        #   query = cities_col.start_at("NYC").order(firestore.document_id)
+        #   query = cities_col.order(firestore.document_id)
+        #                     .start_at(nyc_doc_id)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Starting a query at a document reference object
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
+        #   nyc_ref = cities_col.doc nyc_doc_id
+        #
+        #   # Create a query
+        #   query = cities_col.order(firestore.document_id)
+        #                     .start_at(nyc_ref)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Starting a query at multiple explicit values
+        #   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(:population, :desc)
+        #                     .order(:name)
+        #                     .start_at(1000000, "New York City")
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Starting a query at a DocumentSnapshot
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get a document snapshot
+        #   nyc_snap = firestore.doc("cities/NYC").get
+        #
+        #   # Create a query
+        #   query = cities_col.order(:population, :desc)
+        #                     .order(:name)
+        #                     .start_at(nyc_snap)
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
         def start_at *values
+          raise ArgumentError, "must provide values" if values.empty?
+
           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
-          )
+          cursor = values_to_cursor values, new_query
+          cursor.before = true
+          new_query.start_at = cursor
 
           Query.start new_query, parent_path, client
         end
 
         ##
-        # Starts query results after a set of field values. The result set will
+        # 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 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.
+        # 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`.
         #
-        # @param [Object, Array<Object>] values The field value to start the
-        #   query after.
+        # @param [DocumentSnapshot, Object, Array<Object>] values The field
+        #   values to start the query after.
         #
         # @return [Query] New query with `start_after` called on it.
         #
-        # @example
+        # @example Starting a query after a document reference id
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
+        #
+        #   # Create a query
+        #   query = cities_col.order(firestore.document_id)
+        #                     .start_after(nyc_doc_id)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Starting a query after a document reference object
         #   require "google/cloud/firestore"
         #
         #   firestore = Google::Cloud::Firestore.new
         #
         #   # Get a collection reference
         #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
+        #   nyc_ref = cities_col.doc nyc_doc_id
         #
         #   # Create a query
-        #   query = cities_col.start_after("NYC").order(firestore.document_id)
+        #   query = cities_col.order(firestore.document_id)
+        #                     .start_after(nyc_ref)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Starting a query after multiple explicit values
+        #   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(:population, :desc)
+        #                     .order(:name)
+        #                     .start_after(1000000, "New York City")
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Starting a query after a DocumentSnapshot
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get a document snapshot
+        #   nyc_snap = firestore.doc("cities/NYC").get
+        #
+        #   # Create a query
+        #   query = cities_col.order(:population, :desc)
+        #                     .order(:name)
+        #                     .start_after(nyc_snap)
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
         def start_after *values
+          raise ArgumentError, "must provide values" if values.empty?
+
           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
-          )
+          cursor = values_to_cursor values, new_query
+          cursor.before = false
+          new_query.start_at = cursor
 
           Query.start new_query, parent_path, client
         end
 
         ##
-        # Ends query results before a set of field values. The result set will
+        # 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 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.
+        # 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`.
         #
-        # @param [Object, Array<Object>] values The field value to end the query
-        #   before.
+        # @param [DocumentSnapshot, Object, Array<Object>] values The field
+        #   values to end the query before.
         #
         # @return [Query] New query with `end_before` called on it.
         #
-        # @example
+        # @example Ending a query before a document reference id
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
+        #
+        #   # Create a query
+        #   query = cities_col.order(firestore.document_id)
+        #                     .end_before(nyc_doc_id)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Ending a query before a document reference object
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
+        #   nyc_ref = cities_col.doc nyc_doc_id
+        #
+        #   # Create a query
+        #   query = cities_col.order(firestore.document_id)
+        #                     .end_before(nyc_ref)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Ending a query before multiple explicit values
+        #   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(:population, :desc)
+        #                     .order(:name)
+        #                     .end_before(1000000, "New York City")
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Ending a query before a DocumentSnapshot
         #   require "google/cloud/firestore"
         #
         #   firestore = Google::Cloud::Firestore.new
@@ -464,64 +669,131 @@ module Google
         #   # Get a collection reference
         #   cities_col = firestore.col "cities"
         #
+        #   # Get a document snapshot
+        #   nyc_snap = firestore.doc("cities/NYC").get
+        #
         #   # Create a query
-        #   query = cities_col.end_before("NYC").order(firestore.document_id)
+        #   query = cities_col.order(:population, :desc)
+        #                     .order(:name)
+        #                     .end_before(nyc_snap)
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
         def end_before *values
+          raise ArgumentError, "must provide values" if values.empty?
+
           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
-          )
+          cursor = values_to_cursor values, new_query
+          cursor.before = true
+          new_query.end_at = cursor
 
           Query.start new_query, parent_path, client
         end
 
         ##
-        # Ends query results at a set of field values. The result set will
+        # 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 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.
+        # 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`.
         #
-        # @param [Object, Array<Object>] values The field value to end the query
-        #   at.
+        # @param [DocumentSnapshot, Object, Array<Object>] values The field
+        #   values to end the query at.
         #
         # @return [Query] New query with `end_at` called on it.
         #
-        # @example
+        # @example Ending a query at a document reference id
         #   require "google/cloud/firestore"
         #
         #   firestore = Google::Cloud::Firestore.new
         #
         #   # Get a collection reference
         #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
         #
         #   # Create a query
-        #   query = cities_col.end_at("NYC").order(firestore.document_id)
+        #   query = cities_col.order(firestore.document_id)
+        #                     .end_at(nyc_doc_id)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Ending a query at a document reference object
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #   nyc_doc_id = "NYC"
+        #   nyc_ref = cities_col.doc nyc_doc_id
+        #
+        #   # Create a query
+        #   query = cities_col.order(firestore.document_id)
+        #                     .end_at(nyc_ref)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Ending a query at multiple explicit values
+        #   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(:population, :desc)
+        #                     .order(:name)
+        #                     .end_at(1000000, "New York City")
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        # @example Ending a query at a DocumentSnapshot
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Get a document snapshot
+        #   nyc_snap = firestore.doc("cities/NYC").get
+        #
+        #   # Create a query
+        #   query = cities_col.order(:population, :desc)
+        #                     .order(:name)
+        #                     .end_at(nyc_snap)
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
         def end_at *values
+          raise ArgumentError, "must provide values" if values.empty?
+
           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
-          )
+          cursor = values_to_cursor values, new_query
+          cursor.before = false
+          new_query.end_at = cursor
 
           Query.start new_query, parent_path, client
         end
@@ -552,7 +824,7 @@ module Google
         def get
           ensure_service!
 
-          return enum_for(:run) unless block_given?
+          return enum_for(:get) unless block_given?
 
           results = service.run_query parent_path, @query
           results.each do |result|
@@ -562,6 +834,39 @@ module Google
         end
         alias run get
 
+        ##
+        # Listen to this query for changes.
+        #
+        # @yield [callback] The block for accessing the query snapshot.
+        # @yieldparam [QuerySnapshot] snapshot A query snapshot.
+        #
+        # @return [QueryListener] The ongoing listen operation on the query.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a query
+        #   query = firestore.col(:cities).order(:population, :desc)
+        #
+        #   listener = query.listen do |snapshot|
+        #     puts "The query snapshot has #{snapshot.docs.count} documents "
+        #     puts "and has #{snapshot.changes.count} changes."
+        #   end
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def listen &callback
+          raise ArgumentError, "callback required" if callback.nil?
+
+          ensure_service!
+
+          QueryListener.new(self, &callback).start
+        end
+        alias on_snapshot listen
+
         ##
         # @private Start a new Query.
         def self.start query, parent_path, client
@@ -608,41 +913,180 @@ module Google
 
         def filter name, op, value
           field = StructuredQuery::FieldReference.new field_path: name.to_s
-          op = FILTER_OPS[op.to_s.downcase] || :EQUAL
+          operator = FILTER_OPS[op.to_s.downcase]
+          raise ArgumentError, "unknown operator #{op}" if operator.nil?
 
           is_value_nan = value.respond_to?(:nan?) && value.nan?
           if UNARY_VALUES.include?(value) || is_value_nan
-            if op != :EQUAL
+            if operator != :EQUAL
               raise ArgumentError,
-                    "can only check equality for #{value} values."
+                    "can only check equality for #{value} values"
             end
 
-            op = :IS_NULL
-            op = :IS_NAN if UNARY_NAN_VALUES.include?(value) || is_value_nan
+            operator = :IS_NULL
+            if UNARY_NAN_VALUES.include?(value) || is_value_nan
+              operator = :IS_NAN
+            end
 
             return StructuredQuery::Filter.new(unary_filter:
-              StructuredQuery::UnaryFilter.new(field: field, op: op))
+              StructuredQuery::UnaryFilter.new(field: field, op: operator))
           end
 
           value = Convert.raw_to_value value
           StructuredQuery::Filter.new(field_filter:
-              StructuredQuery::FieldFilter.new(field: field, op: op,
+              StructuredQuery::FieldFilter.new(field: field, op: operator,
                                                value: value))
         end
 
-        def default_filter
+        def composite_filter
           StructuredQuery::Filter.new(composite_filter:
               StructuredQuery::CompositeFilter.new(op: :AND))
         end
 
-        def order_direction direction
-          if direction.to_s.downcase.start_with? "a"
-            :ASCENDING
-          elsif direction.to_s.downcase.start_with? "d"
-            :DESCENDING
+        def add_filters_to_query query, filter
+          if query.where.nil?
+            query.where = filter
+          elsif query.where.filter_type == :composite_filter
+            query.where.composite_filter.filters << filter
           else
-            :DIRECTION_UNSPECIFIED
+            old_filter = query.where
+            query.where = composite_filter
+            query.where.composite_filter.filters << old_filter
+            query.where.composite_filter.filters << filter
+          end
+        end
+
+        def order_direction direction
+          return :DESCENDING if direction.to_s.downcase.start_with? "d".freeze
+          :ASCENDING
+        end
+
+        def query_has_cursors?
+          query.start_at || query.end_at
+        end
+
+        def values_to_cursor values, query
+          if values.count == 1 && values.first.is_a?(DocumentSnapshot)
+            return snapshot_to_cursor(values.first, query)
+          end
+
+          # pair values with their field_paths to ensure correct formatting
+          order_field_paths = order_by_field_paths query
+          if values.count > order_field_paths.count
+            # raise if too many values provided for the cursor
+            raise ArgumentError, "too many values"
+          end
+
+          values = values.zip(order_field_paths).map do |value, field_path|
+            if field_path == doc_id_path && !value.is_a?(DocumentReference)
+              value = document_reference value
+            end
+            Convert.raw_to_value value
+          end
+
+          Google::Firestore::V1beta1::Cursor.new values: values
+        end
+
+        def snapshot_to_cursor snapshot, query
+          if snapshot.parent.path != query_collection_path
+            raise ArgumentError, "cursor snapshot must belong to collection"
+          end
+
+          # first, add any inequality filters missing from existing order_by
+          ensure_inequality_field_paths_in_order_by! query
+
+          # second, make sure __name__ is present in order_by
+          ensure_document_id_in_order_by! query
+
+          # lastly, create cursor for all field_paths in order_by
+          values = order_by_field_paths(query).map do |field_path|
+            if field_path == doc_id_path
+              snapshot.ref
+            else
+              snapshot[field_path]
+            end
           end
+
+          values_to_cursor values, query
+        end
+
+        def ensure_inequality_field_paths_in_order_by! query
+          inequality_paths = inequality_filter_field_paths query
+          orig_order = order_by_field_paths query
+
+          inequality_paths.reverse.each do |field_path|
+            next if orig_order.include? field_path
+
+            query.order_by.unshift StructuredQuery::Order.new(
+              field: StructuredQuery::FieldReference.new(
+                field_path: field_path
+              ),
+              direction: :ASCENDING
+            )
+          end
+        end
+
+        def ensure_document_id_in_order_by! query
+          return if order_by_field_paths(query).include? doc_id_path
+
+          query.order_by.push StructuredQuery::Order.new(
+            field: StructuredQuery::FieldReference.new(
+              field_path: doc_id_path
+            ),
+            direction: last_order_direction(query)
+          )
+        end
+
+        def inequality_filter_field_paths query
+          return [] if query.where.nil?
+
+          # The way we construct a query, where is always a CompositeFilter
+          filters = if query.where.filter_type == :composite_filter
+                      query.where.composite_filter.filters
+                    else
+                      [query.where]
+                    end
+          ineq_filters = filters.select do |filter|
+            if filter.filter_type == :field_filter
+              filter.field_filter.op != :EQUAL
+            end
+          end
+          ineq_filters.map { |filter| filter.field_filter.field.field_path }
+        end
+
+        def order_by_field_paths query
+          query.order_by.map { |order_by| order_by.field.field_path }
+        end
+
+        def last_order_direction query
+          last_order_by = query.order_by.last
+          return :ASCENDING if last_order_by.nil?
+          last_order_by.direction
+        end
+
+        def document_reference document_path
+          if document_path.to_s.split("/").count.even?
+            raise ArgumentError, "document_path must refer to a document"
+          end
+
+          DocumentReference.from_path(
+            "#{query_collection_path}/#{document_path}", client
+          )
+        end
+
+        def query_collection_path
+          "#{parent_path}/#{query_collection_id}"
+        end
+
+        def query_collection_id
+          # We trust that query.from is always set, since Query cannot be
+          # created without it.
+          return nil if query.from.empty?
+          query.from.first.collection_id
+        end
+
+        def doc_id_path
+          "__name__".freeze
         end
 
         ##