Class Mongo::Collection::View::ChangeStream
In: lib/mongo/collection/view/change_stream/retryable.rb
lib/mongo/collection/view/change_stream.rb
Parent: Aggregation

Provides behavior around a `$changeStream` pipeline stage in the aggregation framework. Specifying this stage allows users to request that notifications are sent for all changes to a particular collection or database.

@note Only available in server versions 3.6 and higher. @note ChangeStreams do not work properly with JRuby because of the 

 issue documented here: https://github.com/jruby/jruby/issues/4212.
 Namely, JRuby eagerly evaluates #next on an Enumerator in a background
 green thread, therefore calling #next on the change stream will cause
 getMores to be called in a loop in the background.

@since 2.5.0

Methods

close   closed?   each   inspect   new   to_enum   try_next  

Included Modules

Retryable

Classes and Modules

Module Mongo::Collection::View::ChangeStream::Retryable

Constants

FULL_DOCUMENT_DEFAULT = 'default'.freeze   @return [ String ] The fullDocument option default value.

@since 2.5.0

DATABASE = :database   @return [ Symbol ] Used to indicate that the change stream should listen for changes on 
  the entire database rather than just the collection.

@since 2.6.0

CLUSTER = :cluster   @return [ Symbol ] Used to indicate that the change stream should listen for changes on 
  the entire cluster rather than just the collection.

@since 2.6.0

Attributes

options  [R]  @return [ BSON::Document ] The change stream options.

@since 2.5.0

Public Class methods

new(view, pipeline, changes_for, options = {})

Initialize the change stream for the provided collection view, pipeline and options.

@example Create the new change stream view. 

  ChangeStream.new(view, pipeline, options)

@param [ Collection::View ] view The collection view. @param [ Array<Hash> ] pipeline The pipeline of operators to filter the change notifications. @param [ Hash ] options The change stream options.

@option options [ String ] :full_document Allowed values: ‘default’, ‘updateLookup’. Defaults to ‘default’. 

  When set to 'updateLookup', the change notification for partial updates will include both a delta
  describing the changes to the document, as well as a copy of the entire document that was changed
  from some time after the change occurred.

@option options [ BSON::Document, Hash ] :resume_after Specifies the logical starting point for the 

  new change stream.

@option options [ Integer ] :max_await_time_ms The maximum amount of time for the server to wait 

  on new documents to satisfy a change stream query.

@option options [ Integer ] :batch_size The number of documents to return per batch. @option options [ BSON::Document, Hash ] :collation The collation to use. @option options [ BSON::Timestamp ] :start_at_operation_time Only 

  return changes that occurred at or after the specified timestamp. Any
  command run against the server will return a cluster time that can
  be used here. Only recognized by server versions 4.0+.

@since 2.5.0

Public Instance methods

close()

Close the change stream.

@example Close the change stream. 

  stream.close

@return [ nil ] nil.

@since 2.5.0

closed?()

Is the change stream closed?

@example Determine whether the change stream is closed. 

  stream.closed?

@return [ true, false ] If the change stream is closed.

@since 2.5.0

each() {|doc| ...}

Iterate through documents returned by the change stream.

This method retries once per error on resumable errors (two consecutive errors result in the second error being raised, an error which is recovered from resets the error count to zero).

@example Iterate through the stream of documents. 

  stream.each do |document|
    p document
  end

@return [ Enumerator ] The enumerator.

@since 2.5.0

@yieldparam [ BSON::Document ] Each change stream document.

inspect()

Get a formatted string for use in inspection.

@example Inspect the change stream object. 

  stream.inspect

@return [ String ] The change stream inspection.

@since 2.5.0

try_next()

Return one document from the change stream, if one is available.

Retries once on a resumable error.

Raises StopIteration if the change stream is closed.

This method will wait up to max_await_time_ms milliseconds for changes from the server, and if no changes are received it will return nil.

@note This method is experimental and subject to change.

@return [ BSON::Document | nil ] A change stream document. @api experimental @since 2.6.0

[Validate]