mongo 1.12.5 → 2.0.0.beta

data/lib/mongo/collection/view.rb

@@ -0,0 +1,169 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# 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
+#
+#   http://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 'mongo/collection/view/immutable'
+require 'mongo/collection/view/iterable'
+require 'mongo/collection/view/explainable'
+require 'mongo/collection/view/aggregation'
+require 'mongo/collection/view/map_reduce'
+require 'mongo/collection/view/readable'
+require 'mongo/collection/view/writable'
+
+module Mongo
+  class Collection
+
+    # Representation of a query and options producing a result set of documents.
+    #
+    # A +View+ can be modified using helpers. Helpers can be chained,
+    # as each one returns a +View+ if arguments are provided.
+    #
+    # The query message is sent to the server when a "terminator" is called.
+    # For example, when #each is called on a +View+, a Cursor object is
+    # created, which then sends the query to the server.
+    #
+    # A +View+ is not created directly by a user. Rather, +View+
+    # creates a +View+ when a CRUD operation is called and returns it to
+    # the user to interact with.
+    #
+    # @note The +View+ API is semipublic.
+    # @api semipublic
+    class View
+      extend Forwardable
+      include Enumerable
+      include Immutable
+      include Iterable
+      include Readable
+      include Explainable
+      include Writable
+
+      # @return [ View ] The +View+ to query.
+      attr_reader :collection
+      # @return [ Hash ] The query selector.
+      attr_reader :selector
+
+      # Delegate necessary operations to the collection.
+      def_delegators :collection, :client, :cluster, :database, :read_preference, :write_concern
+
+      # Delegate to the cluster for the next primary.
+      def_delegators :cluster, :next_primary
+
+      # Compare two +View+ objects.
+      #
+      # @example Compare the view with another object.
+      #   view == other
+      #
+      # @return [ true, false ] Equal if collection, selector, and options of two
+      #   +View+ match.
+      #
+      # @since 2.0.0
+      def ==(other)
+        return false unless other.is_a?(View)
+        collection == other.collection &&
+            selector == other.selector &&
+            options == other.options
+      end
+      alias_method :eql?, :==
+
+      # A hash value for the +View+ composed of the collection namespace,
+      # hash of the options and hash of the selector.
+      #
+      # @example Get the hash value.
+      #   view.hash
+      #
+      # @return [ Integer ] A hash value of the +View+ object.
+      #
+      # @since 2.0.0
+      def hash
+        [ collection.namespace, options.hash, selector.hash ].hash
+      end
+
+      # Creates a new +View+.
+      #
+      # @example Find all users named Emily.
+      #   View.new(collection, {:name => 'Emily'})
+      #
+      # @example Find all users named Emily skipping 5 and returning 10.
+      #   View.new(collection, {:name => 'Emily'}, :skip => 5, :limit => 10)
+      #
+      # @example Find all users named Emily using a specific read preference.
+      #   View.new(collection, {:name => 'Emily'}, :read => :secondary_preferred)
+      #
+      # @param [ Collection ] collection The +Collection+ to query.
+      # @param [ Hash ] selector The query selector.
+      # @param [ Hash ] options The additional query options.
+      #
+      # @option options :comment [ String ] Associate a comment with the query.
+      # @option options :batch_size [ Integer ] The number of docs to return in
+      #   each response from MongoDB.
+      # @option options :fields [ Hash ] The fields to include or exclude in
+      #   returned docs.
+      # @option options :hint [ Hash ] Override default index selection and force
+      #   MongoDB to use a specific index for the query.
+      # @option options :limit [ Integer ] Max number of docs to return.
+      # @option options :max_scan [ Integer ] Constrain the query to only scan the
+      #   specified number of docs. Use to prevent queries from running too long.
+      # @option options :read [ Symbol ] The read preference to use for the query.
+      #   If none is provided, the collection's default read preference is used.
+      # @option options :show_disk_loc [ true, false ] Return disk location info as
+      #   a field in each doc.
+      # @option options :skip [ Integer ] The number of documents to skip.
+      # @option options :snapshot [ true, false ] Prevents returning a doc more than
+      #   once.
+      # @option options :sort [ Hash ] The key and direction pairs used to sort the
+      #   results.
+      #
+      # @since 2.0.0
+      def initialize(collection, selector = {}, options = {})
+        @collection = collection
+        @selector = selector.dup
+        @options = options.dup
+      end
+
+      # Get a human-readable string representation of +View+.
+      #
+      # @example Get the inspection.
+      #   view.inspect
+      #
+      # @return [ String ] A string representation of a +View+ instance.
+      #
+      # @since 2.0.0
+      def inspect
+        "<Mongo::Collection::View:0x#{object_id} namespace='#{collection.namespace}" +
+            " @selector=#{selector.inspect} @options=#{options.inspect}>"
+      end
+
+      private
+
+      def initialize_copy(other)
+        @collection = other.collection
+        @options = other.options.dup
+        @selector = other.selector.dup
+      end
+
+      def initial_query_op
+        Operation::Read::Query.new(query_spec)
+      end
+
+      def new(options)
+        View.new(collection, selector, options)
+      end
+
+      def send_initial_query(server)
+        initial_query_op.execute(server.context)
+      end
+
+      def view; self; end
+    end
+  end
+end

data/lib/mongo/collection/view/aggregation.rb

@@ -0,0 +1,108 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# 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
+#
+#   http://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.
+
+module Mongo
+  class Collection
+    class View
+
+      # Provides behaviour around an aggregation pipeline on a collection view.
+      #
+      # @since 2.0.0
+      class Aggregation
+        extend Forwardable
+        include Enumerable
+        include Immutable
+        include Iterable
+        include Explainable
+
+        # @return [ View ] view The collection view.
+        attr_reader :view
+        # @return [ Array<Hash> ] pipeline The aggregation pipeline.
+        attr_reader :pipeline
+
+        # Delegate necessary operations to the view.
+        def_delegators :view, :collection, :read, :cluster
+
+        # Delegate necessary operations to the collection.
+        def_delegators :collection, :database
+
+        # Set to true if disk usage is allowed during the aggregation.
+        #
+        # @example Set disk usage flag.
+        #   aggregation.allow_disk_use(true)
+        #
+        # @param [ true, false ] value The flag value.
+        #
+        # @return [ true, false, Aggregation ] The aggregation if a value was
+        #   set or the value if used as a getter.
+        #
+        # @since 2.0.0
+        def allow_disk_use(value = nil)
+          configure(:allowDiskUse, value)
+        end
+
+        # Initialize the aggregation for the provided collection view, pipeline
+        # and options.
+        #
+        # @example Create the new aggregation view.
+        #   Aggregation.view.new(view, pipeline)
+        #
+        # @param [ Collection::View ] view The collection view.
+        # @param [ Array<Hash> ] pipeline The pipeline of operations.
+        # @param [ Hash ] options The aggregation options.
+        #
+        # @since 2.0.0
+        def initialize(view, pipeline, options = {})
+          @view = view
+          @pipeline = pipeline.dup
+          @options = options.dup
+        end
+
+        private
+
+        def aggregate_spec
+          { :selector => {
+              :aggregate => collection.name,
+              :pipeline => pipeline,
+              :cursor => view.batch_size ? { :batchSize => view.batch_size } : {}
+            }.merge!(options),
+            :db_name => database.name,
+            :options => view.options }
+        end
+
+        def explain_options
+          { :explain => true }
+        end
+
+        def new(options)
+          Aggregation.new(view, pipeline, options)
+        end
+
+        def initial_query_op
+          Operation::Aggregate.new(aggregate_spec)
+        end
+
+        def send_initial_query(server)
+          begin
+            initial_query_op.execute(server.context)
+          rescue Mongo::Operation::Aggregate::NeedPrimaryServer
+            warn 'Rerouting the Aggregation operation to the primary server.'
+            server = ServerSelector.get(mode: :primary).select_server(cluster)
+            initial_query_op.execute(server.context)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/collection/view/explainable.rb

@@ -0,0 +1,49 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# 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
+#
+#   http://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.
+
+module Mongo
+  class Collection
+    class View
+
+      # Defines explain related behaviour for collection view.
+      #
+      # @since 2.0.0
+      module Explainable
+
+        # Get the explain plan for the query.
+        #
+        # @example Get the explain plan for the query.
+        #   view.explain
+        #
+        # @return [ Hash ] A single document with the explain plan.
+        #
+        # @since 2.0.0
+        def explain
+          self.class.new(collection, selector, options.merge(explain_options)).first
+        end
+
+        private
+
+        def explained?
+          !!options[:explain]
+        end
+
+        def explain_options
+          explain_limit = limit || 0
+          { :limit => -explain_limit.abs, :explain => true }
+        end
+      end
+    end
+  end
+end

data/lib/mongo/collection/view/immutable.rb

@@ -0,0 +1,43 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# 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
+#
+#   http://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.
+
+module Mongo
+  class Collection
+    class View
+      module Immutable
+
+        # @return [ Hash ] options The additional query options.
+        attr_reader :options
+
+        private
+
+        # @api private
+        #
+        # @note In the including class, the method #immutable needs to be
+        #   implemented in order to define how a new class of that type needs to
+        #   be instantiated.
+        def configure(field, value)
+          return options[field] if value.nil?
+          new(options.merge(field => value))
+        end
+
+        def configure_flag(flag)
+          new(options.dup).tap do |view|
+            view.send(:flags).push(flag)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongo/collection/view/iterable.rb

@@ -0,0 +1,48 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# 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
+#
+#   http://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.
+
+module Mongo
+  class Collection
+    class View
+
+      # Defines iteration related behaviour for collection views, including
+      # cursor instantiation.
+      #
+      # @since 2.0.0
+      module Iterable
+
+        # Iterate through documents returned by a query with this +View+.
+        #
+        # @example Iterate through the result of the view.
+        #   view.each do |document|
+        #     p document
+        #   end
+        #
+        # @return [ Enumerator ] The enumerator.
+        #
+        # @since 2.0.0
+        #
+        # @yieldparam [ Hash ] Each matching document.
+        def each
+          server = read.select_server(cluster)
+          cursor = Cursor.new(view, send_initial_query(server), server).to_enum
+          cursor.each do |doc|
+            yield doc
+          end if block_given?
+          cursor
+        end
+      end
+    end
+  end
+end

data/lib/mongo/collection/view/map_reduce.rb

@@ -0,0 +1,191 @@
+# Copyright (C) 2014-2015 MongoDB, Inc.
+#
+# 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
+#
+#   http://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.
+
+module Mongo
+  class Collection
+    class View
+
+      # Provides behaviour around a map/reduce operation on the collection
+      # view.
+      #
+      # @since 2.0.0
+      class MapReduce
+        extend Forwardable
+        include Enumerable
+        include Immutable
+        include Iterable
+
+        # @return [ View ] view The collection view.
+        attr_reader :view
+
+        # @return [ String ] map The map function.
+        attr_reader :map
+
+        # @return [ String ] reduce The reduce function.
+        attr_reader :reduce
+
+        # Delegate necessary operations to the view.
+        def_delegators :view, :collection, :read, :cluster
+
+        # Delegate necessary operations to the collection.
+        def_delegators :collection, :database
+
+        # Set or get the finalize function for the operation.
+        #
+        # @example Set the finalize function.
+        #   map_reduce.finalize(function)
+        #
+        # @param [ String ] function The finalize js function.
+        #
+        # @return [ MapReduce, String ] The new MapReduce operation or the
+        #   value of the function.
+        #
+        # @since 2.0.0
+        def finalize(function = nil)
+          configure(:finalize, function)
+        end
+
+        # Initialize the map/reduce for the provided collection view, functions
+        # and options.
+        #
+        # @example Create the new map/reduce view.
+        #
+        # @param [ Collection::View ] view The collection view.
+        # @param [ String ] map The map function.
+        # @param [ String ] reduce The reduce function.
+        # @param [ Hash ] options The map/reduce options.
+        #
+        # @since 2.0.0
+        def initialize(view, map, reduce, options = {})
+          @view = view
+          @map = map.freeze
+          @reduce = reduce.freeze
+          @options = options.dup
+        end
+
+        # Set or get the jsMode flag for the operation.
+        #
+        # @example Set js mode for the operation.
+        #   map_reduce.js_mode(true)
+        #
+        # @param [ true, false ] value The jsMode value.
+        #
+        # @return [ MapReduce, true, false ] The new MapReduce operation or the
+        #   value of the jsMode flag.
+        #
+        # @since 2.0.0
+        def js_mode(value = nil)
+          configure(:jsMode, value)
+        end
+
+        # Set or get the output location for the operation.
+        #
+        # @example Set the output to inline.
+        #   map_reduce.out(inline: 1)
+        #
+        # @example Set the output collection to merge.
+        #   map_reduce.out(merge: 'users')
+        #
+        # @example Set the output collection to replace.
+        #   map_reduce.out(replace: 'users')
+        #
+        # @example Set the output collection to reduce.
+        #   map_reduce.out(reduce: 'users')
+        #
+        # @param [ Hash ] location The output location details.
+        #
+        # @return [ MapReduce, Hash ] The new MapReduce operation or the value
+        #   of the output location.
+        #
+        # @since 2.0.0
+        def out(location = nil)
+          configure(:out, location)
+        end
+
+        # Set or get a scope on the operation.
+        #
+        # @example Set the scope value.
+        #   map_reduce.scope(value: 'test')
+        #
+        # @param [ Hash ] object The scope object.
+        #
+        # @return [ MapReduce, Hash ] The new MapReduce operation or thevalue
+        #   of the scope.
+        #
+        # @since 2.0.0
+        def scope(object = nil)
+          configure(:scope, object)
+        end
+
+        private
+
+        def inline?
+          out.nil? || out == { inline: 1 }
+        end
+
+        def map_reduce_spec
+          {
+            :db_name => database.name,
+            :selector => {
+              :mapreduce => collection.name,
+              :map => map,
+              :reduce => reduce,
+              :query => view.selector[:$query] || view.selector,
+              :out => { inline: 1 }
+            }.merge(options).merge(view.options)
+          }
+        end
+
+        def new(options)
+          MapReduce.new(view, map, reduce, options)
+        end
+
+        def initial_query_op
+          Operation::MapReduce.new(map_reduce_spec)
+        end
+
+        def send_initial_query(server)
+          result =
+            begin
+              initial_query_op.execute(server.context)
+            rescue Mongo::Error::NeedPrimaryServer
+              warn 'Rerouting the MapReduce operation to the primary server.'
+              server = ServerSelector.get(mode: :primary).select_server(cluster)
+              initial_query_op.execute(server.context)
+            end
+          if inline?
+            result
+          else
+            send_fetch_query(server)
+          end
+        end
+
+        def fetch_query_spec
+          { :selector  => {},
+            :options   => {},
+            :db_name   => database.name,
+            :coll_name => out.values.first }
+        end
+
+        def fetch_query_op
+          Operation::Read::Query.new(fetch_query_spec)
+        end
+
+        def send_fetch_query(server)
+          fetch_query_op.execute(server.context)
+        end
+      end
+    end
+  end
+end