RUBY-1673 Document collection options (#2588)

* RUBY-1673 Document collection options

* RUBY-1673 remove read_preference option

* RUBY-1673 amend #with docs to include read_concern

* RUBY-1673 add missing options

* RUBY-1673 verify max and size options work

* RUBY-1673 nitpick

* RUBY-1673 alphabetize the options

* RUBY-1673 fix mmap tests

* RUBY-1673 fix mmap tests

Author: neilshweky

lib/mongo/collection.rb

@@ -100,19 +100,59 @@ def ==(other)
     # @param [ String, Symbol ] name The collection name.
     # @param [ Hash ] options The collection options.
     #
-    # @option options [ Hash ] :write Deprecated. Equivalent to :write_concern
+    # @option opts [ true | false ] :capped Create a fixed-sized collection.
+    # @option opts [ Hash ] :change_stream_pre_and_post_images Used to enable
+    #   pre- and post-images on the created collection.
+    #   The hash may have the following items:
+    #   - *:enabled* -- true or false.
+    # @option opts [ Hash ] :clustered_index Create a clustered index.
+    #   This option specifies how this collection should be clustered on _id.
+    #   The hash may have the following items:
+    #   - *:key* -- The clustered index key field. Must be set to { _id: 1 }.
+    #   - *:unique* -- Must be set to true. The collection will not accept
+    #     inserted or updated documents where the clustered index key value
+    #     matches an existing value in the index.
+    #   - *:name* -- Optional. A name that uniquely identifies the clustered index.
+    # @option opts [ Hash ] :collation The collation to use.
+    # @option opts [ Hash ] :encrypted_fields Hash describing encrypted fields
+    #   for queryable encryption.
+    # @option opts [ Integer ] :expire_after Number indicating
+    #   after how many seconds old time-series data should be deleted.
+    # @option opts [ Integer ] :max The maximum number of documents in a
+    #   capped collection. The size limit takes precedents over max.
+    # @option opts [ Array<Hash> ] :pipeline An array of pipeline stages.
+    #   A view will be created by applying this pipeline to the view_on
+    #   collection or view.
+    # @option options [ Hash ] :read_concern The read concern options hash,
+    #   with the following optional keys:
+    #   - *:level* -- the read preference level as a symbol; valid values
+    #      are *:local*, *:majority*, and *:snapshot*
+    # @option options [ Hash ] :read The read preference options.
+    #   The hash may have the following items:
+    #   - *:mode* -- read preference specified as a symbol; valid values are
+    #     *:primary*, *:primary_preferred*, *:secondary*, *:secondary_preferred*
+    #     and *:nearest*.
+    #   - *:tag_sets* -- an array of hashes.
+    #   - *:local_threshold*.
+    # @option opts [ Session ] :session The session to use for the operation.
+    # @option opts [ Integer ] :size The size of the capped collection.
+    # @option opts [ Hash ] :time_series Create a time-series collection.
+    #   The hash may have the following items:
+    #   - *:timeField* -- The name of the field which contains the date in each
+    #     time series document.
+    #   - *:metaField* -- The name of the field which contains metadata in each
+    #     time series document.
+    #   - *:granularity* -- Set the granularity to the value that is the closest
+    #     match to the time span between consecutive incoming measurements.
+    #     Possible values are "seconds" (default), "minutes", and "hours".
+    # @option opts [ Hash ] :validator Hash describing document validation
+    #   options for the collection.
+    # @option opts [ String ] :view_on The name of the source collection or
+    #   view from which to create a view.
+    # @option opts [ Hash ] :write Deprecated. Equivalent to :write_concern
     #   option.
-    # @option options [ Hash ] :write_concern The write concern options.
+    # @option opts [ Hash ] :write_concern The write concern options.
     #   Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.
-    # @option options [ Hash ] :time_series Create a time-series collection.
-    #   See https://mongodb.com/docs/manual/core/timeseries-collections/ for more
-    #   information about time-series collection.
-    # @option options [ Integer ] :expire_after Number indicating
-    #   after how many seconds old time-series data should be deleted.
-    # @options clustered_index [ Hash ] :clustered_index Create a clustered index.
-    #   This option specifies how this collection should be clustered on _id.
-    #   See https://www.mongodb.com/docs/v5.3/reference/method/db.createCollection/#std-label-db.createCollection.clusteredIndex
-    #   for more information about this option.
     #
     # @since 2.0.0
     def initialize(database, name, options = {})
@@ -204,17 +244,37 @@ def write_concern_with_session(session)
       wc
     end
 
-    # Provides a new collection with either a new read preference or new write concern
-    # merged over the existing read preference / write concern.
+    # Provides a new collection with either a new read preference, new read
+    # concern or new write concern merged over the existing read preference /
+    # read concern / write concern.
     #
     # @example Get a collection with a changed read preference.
     #   collection.with(read: { mode: :primary_preferred })
+
+    # @example Get a collection with a changed read concern.
+    #   collection.with(read_concern: { level: :majority })
     #
     # @example Get a collection with a changed write concern.
     #   collection.with(write_concern: { w:  3 })
-
+    #
     # @param [ Hash ] new_options The new options to use.
     #
+    # @option new_options [ Hash ] :read The read preference options.
+    #   The hash may have the following items:
+    #   - *:mode* -- read preference specified as a symbol; valid values are
+    #     *:primary*, *:primary_preferred*, *:secondary*, *:secondary_preferred*
+    #     and *:nearest*.
+    #   - *:tag_sets* -- an array of hashes.
+    #   - *:local_threshold*.
+    # @option new_options [ Hash ] :read_concern The read concern options hash,
+    #   with the following optional keys:
+    #   - *:level* -- the read preference level as a symbol; valid values
+    #      are *:local*, *:majority*, and *:snapshot*
+    # @option new_options [ Hash ] :write Deprecated. Equivalent to :write_concern
+    #   option.
+    # @option new_options [ Hash ] :write_concern The write concern options.
+    #   Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.
+    #
     # @return [ Mongo::Collection ] A new collection instance.
     #
     # @since 2.1.0
@@ -251,17 +311,48 @@ def capped?
     #
     # @param [ Hash ] opts The options for the create operation.
     #
-    # @option opts [ Session ] :session The session to use for the operation.
-    # @option opts [ Hash ] :write_concern The write concern options.
-    # @option opts [ Hash ] :time_series Create a time-series collection.
-    # @option opts [ Integer ] :expire_after Number indicating
-    #   after how many seconds old time-series data should be deleted.
+    # @option opts [ true | false ] :capped Create a fixed-sized collection.
     # @option opts [ Hash ] :change_stream_pre_and_post_images Used to enable
     #   pre- and post-images on the created collection.
+    #   The hash may have the following items:
+    #   - *:enabled* -- true or false.
+    # @option opts [ Hash ] :clustered_index Create a clustered index.
+    #   This option specifies how this collection should be clustered on _id.
+    #   The hash may have the following items:
+    #   - *:key* -- The clustered index key field. Must be set to { _id: 1 }.
+    #   - *:unique* -- Must be set to true. The collection will not accept
+    #     inserted or updated documents where the clustered index key value
+    #     matches an existing value in the index.
+    #   - *:name* -- Optional. A name that uniquely identifies the clustered index.
+    # @option opts [ Hash ] :collation The collation to use.
     # @option opts [ Hash ] :encrypted_fields Hash describing encrypted fields
     #   for queryable encryption.
+    # @option opts [ Integer ] :expire_after Number indicating
+    #   after how many seconds old time-series data should be deleted.
+    # @option opts [ Integer ] :max The maximum number of documents in a
+    #   capped collection. The size limit takes precedents over max.
+    # @option opts [ Array<Hash> ] :pipeline An array of pipeline stages.
+    #   A view will be created by applying this pipeline to the view_on
+    #   collection or view.
+    # @option opts [ Session ] :session The session to use for the operation.
+    # @option opts [ Integer ] :size The size of the capped collection.
+    # @option opts [ Hash ] :time_series Create a time-series collection.
+    #   The hash may have the following items:
+    #   - *:timeField* -- The name of the field which contains the date in each
+    #     time series document.
+    #   - *:metaField* -- The name of the field which contains metadata in each
+    #     time series document.
+    #   - *:granularity* -- Set the granularity to the value that is the closest
+    #     match to the time span between consecutive incoming measurements.
+    #     Possible values are "seconds" (default), "minutes", and "hours".
     # @option opts [ Hash ] :validator Hash describing document validation
     #   options for the collection.
+    # @option opts [ String ] :view_on The name of the source collection or
+    #   view from which to create a view.
+    # @option opts [ Hash ] :write Deprecated. Equivalent to :write_concern
+    #   option.
+    # @option opts [ Hash ] :write_concern The write concern options.
+    #   Can be :w => Integer|String, :fsync => Boolean, :j => Boolean.
     #
     # @return [ Result ] The result of the command.
     #

lib/mongo/query_cache.rb

@@ -114,24 +114,24 @@ def clear_namespace(namespace)
       #
       # @param [ Mongo::CachingCursor ] cursor The CachingCursor instance to store.
       #
-      # @option opts [ String | nil ] namespace The namespace of the query,
+      # @option opts [ String | nil ] :namespace The namespace of the query,
       #   in the format "database_name.collection_name".
-      # @option opts [ Array, Hash ] selector The selector passed to the query.
+      # @option opts [ Array, Hash ] :selector The selector passed to the query.
       #   For most queries, this will be a Hash, but for aggregations, this
       #   will be an Array representing the aggregation pipeline. May not be nil.
-      # @option opts [ Integer | nil ] skip The skip value of the query.
-      # @option opts [ Hash | nil ] sort The order of the query results
+      # @option opts [ Integer | nil ] :skip The skip value of the query.
+      # @option opts [ Hash | nil ] :sort The order of the query results
       #   (e.g. { name: -1 }).
-      # @option opts [ Integer | nil ] limit The limit value of the query.
-      # @option opts [ Hash | nil ] projection The projection of the query
+      # @option opts [ Integer | nil ] :limit The limit value of the query.
+      # @option opts [ Hash | nil ] :projection The projection of the query
       #   results (e.g. { name: 1 }).
-      # @option opts [ Hash | nil ] collation The collation of the query
+      # @option opts [ Hash | nil ] :collation The collation of the query
       #   (e.g. { "locale" => "fr_CA" }).
-      # @option opts [ Hash | nil ] read_concern The read concern of the query
+      # @option opts [ Hash | nil ] :read_concern The read concern of the query
       #   (e.g. { level: :majority }).
-      # @option opts [ Hash | nil ] read_preference The read preference of
+      # @option opts [ Hash | nil ] :read_preference The read preference of
       #   the query (e.g. { mode: :secondary }).
-      # @option opts [ Boolean | nil ] multi_collection Whether the query
+      # @option opts [ Boolean | nil ] :multi_collection Whether the query
       #   results could potentially come from multiple collections. When true,
       #   these results will be stored under the nil namespace key and cleared
       #   on every write command.
@@ -152,24 +152,24 @@ def set(cursor, **opts)
       # For the given query options, retrieve a cached cursor that can be used
       # to obtain the correct query results, if one exists in the cache.
       #
-      # @option opts [ String | nil ] namespace The namespace of the query,
+      # @option opts [ String | nil ] :namespace The namespace of the query,
       #   in the format "database_name.collection_name".
-      # @option opts [ Array, Hash ] selector The selector passed to the query.
+      # @option opts [ Array, Hash ] :selector The selector passed to the query.
       #   For most queries, this will be a Hash, but for aggregations, this
       #   will be an Array representing the aggregation pipeline. May not be nil.
-      # @option opts [ Integer | nil ] skip The skip value of the query.
-      # @option opts [ Hash | nil ] sort The order of the query results
+      # @option opts [ Integer | nil ] :skip The skip value of the query.
+      # @option opts [ Hash | nil ] :sort The order of the query results
       #   (e.g. { name: -1 }).
-      # @option opts [ Integer | nil ] limit The limit value of the query.
-      # @option opts [ Hash | nil ] projection The projection of the query
+      # @option opts [ Integer | nil ] :limit The limit value of the query.
+      # @option opts [ Hash | nil ] :projection The projection of the query
       #   results (e.g. { name: 1 }).
-      # @option opts [ Hash | nil ] collation The collation of the query
+      # @option opts [ Hash | nil ] :collation The collation of the query
       #   (e.g. { "locale" => "fr_CA" }).
-      # @option opts [ Hash | nil ] read_concern The read concern of the query
+      # @option opts [ Hash | nil ] :read_concern The read concern of the query
       #   (e.g. { level: :majority }).
-      # @option opts [ Hash | nil ] read_preference The read preference of
+      # @option opts [ Hash | nil ] :read_preference The read preference of
       #   the query (e.g. { mode: :secondary }).
-      # @option opts [ Boolean | nil ] multi_collection Whether the query
+      # @option opts [ Boolean | nil ] :multi_collection Whether the query
       #   results could potentially come from multiple collections. When true,
       #   these results will be stored under the nil namespace key and cleared
       #   on every write command.

lib/mongo/session.rb

@@ -522,7 +522,7 @@ def with_transaction(options=nil)
     #
     # @option options [ Integer ] :max_commit_time_ms The maximum amount of
     #   time to allow a single commitTransaction command to run, in milliseconds.
-    # @option options [ Hash ] read_concern The read concern options hash,
+    # @option options [ Hash ] :read_concern The read concern options hash,
     #   with the following optional keys:
     #   - *:level* -- the read preference level as a symbol; valid values
     #      are *:local*, *:majority*, and *:snapshot*

spec/mongo/collection_crud_spec.rb

@@ -4412,4 +4412,24 @@ def generate
       expect(result).to be_nil
     end
   end
+
+  context "when creating collection with view_on and pipeline" do
+    before do
+      authorized_client["my_view"].drop
+      authorized_collection.insert_one({ bar: "here!" })
+      authorized_client["my_view",
+        view_on: authorized_collection.name,
+        pipeline: [ { :'$project' => { "baz": "$bar" } } ]
+      ].create
+    end
+
+    it "the view has a document" do
+      expect(authorized_client["my_view"].find.to_a.length).to eq(1)
+    end
+
+    it "applies the pipeline" do
+      expect(authorized_client["my_view"].find.first).to have_key("baz")
+      expect(authorized_client["my_view"].find.first["baz"]).to eq("here!")
+    end
+  end
 end

spec/mongo/collection_spec.rb

@@ -647,7 +647,11 @@
     context 'when the collection is capped' do
 
       let(:collection) do
-        described_class.new(database, :specs, :capped => true, :size => 1024)
+        described_class.new(database, :specs, :capped => true, :size => 4096, :max => 512)
+      end
+
+      let(:collstats) do
+        database.read_command(:collstats => :specs).documents.first
       end
 
       before do
@@ -658,6 +662,12 @@
       it 'returns true' do
         expect(collection).to be_capped
       end
+
+      it "applies the options" do
+        expect(collstats["capped"]).to be true
+        expect(collstats["max"]).to eq(512)
+        expect(collstats["maxSize"]).to eq(4096)
+      end
     end
 
     context 'when the collection is not capped' do