@@ -38,9 +38,9 @@ rows.each { |row| pp row } # records we find. coll.find('a' => 1) -# Find records sort by 'a', offset 1, limit 2 records. +# Find records sort by 'a', skip 1, limit 2 records. # Sort can be single name, array, or hash. -coll.find({}, {:offset => 1, :limit => 2, :sort => 'a'}) +coll.find({}, {:skip => 1, :limit => 2, :sort => 'a'}) # Find all records with 'a' > 1. There is also $lt, $gte, and $lte. coll.find({'a' => {'$gt' => 1}}) examples/queries.rb @@ -88,7 +88,8 @@ module Mongo # set ("_id" will always be included). By limiting results # to a certain subset of fields you can cut down on network # traffic and decoding time. - # :offset :: Start at this record when returning records + # :skip :: Number of documents to omit (from the start of the result set) + # when returning the results # :limit :: Maximum number of records to return # :sort :: Either hash of field names as keys and 1/-1 as values; 1 == # ascending, -1 == descending, or array of field names (all @@ -102,7 +103,11 @@ module Mongo def find(selector={}, options={}) fields = options.delete(:fields) fields = ["_id"] if fields && fields.empty? - offset = options.delete(:offset) || 0 + skip = options.delete(:offset) || nil + if !skip.nil? + warn "the :offset option to find is deprecated and will be removed. please use :skip instead" + end + skip = options.delete(:skip) || skip || 0 limit = options.delete(:limit) || 0 sort = options.delete(:sort) hint = options.delete(:hint) @@ -114,7 +119,7 @@ module Mongo end raise RuntimeError, "Unknown options [#{options.inspect}]" unless options.empty? - cursor = @db.query(self, Query.new(selector, fields, offset, limit, sort, hint, snapshot)) + cursor = @db.query(self, Query.new(selector, fields, skip, limit, sort, hint, snapshot)) if block_given? yield cursor cursor.close() lib/mongo/collection.rb @@ -107,7 +107,7 @@ module Mongo # # Raises InvalidOperation if this cursor has already been used. # - # This method overrides any offset specified in the Collection#find method, + # This method overrides any skip specified in the Collection#find method, # and only the last skip applied has an effect. def skip(number_to_skip) check_modifiable lib/mongo/cursor.rb @@ -38,8 +38,7 @@ module Mongo # (Called :fields in calls to Collection#find.) # # number_to_skip :: Number of records to skip before returning - # records. (Called :offset in calls to - # Collection#find.) Default is 0. + # records. Default is 0. # # number_to_return :: Max number of records to return. (Called :limit # in calls to Collection#find.) Default is 0 (all lib/mongo/query.rb @@ -11,5 +11,5 @@ if $DEBUG (5..15).each { |i| c.insert(:x => 2, :y => i, :z => (i+64).chr) } end -cursor = db.collection('c').find({'x' => 1}, :sort => 'y', :offset => 20, :limit => 10) +cursor = db.collection('c').find({'x' => 1}, :sort => 'y', :skip => 20, :limit => 10) cursor.each { |row| puts row['z'] } test/mongo-qa/find1 @@ -165,7 +165,7 @@ class TestCollection < Test::Unit::TestCase assert_equal 1, x i = 0 - @@test.find({}, :offset => 5) do |cursor| + @@test.find({}, :skip => 5) do |cursor| cursor.each do |doc| i = i + 1 end @@ -199,6 +199,23 @@ class TestCollection < Test::Unit::TestCase # assert_equal :mike, @@test.find_one("foo" => "mike")["foo"] end + def test_limit_and_skip + 10.times do |i| + @@test.save(:foo => i) + end + + # TODO remove test for deprecated :offset option + assert_equal 5, @@test.find({}, :offset => 5).next_object()["foo"] + + assert_equal 5, @@test.find({}, :skip => 5).next_object()["foo"] + assert_equal nil, @@test.find({}, :skip => 10).next_object() + + assert_equal 5, @@test.find({}, :limit => 5).to_a.length + + assert_equal 3, @@test.find({}, :skip => 3, :limit => 5).next_object()["foo"] + assert_equal 5, @@test.find({}, :skip => 3, :limit => 5).to_a.length + end + def test_group_with_scope @@test.save("a" => 1) @@test.save("b" => 1) test/test_collection.rb @@ -43,7 +43,7 @@ class CursorTest < Test::Unit::TestCase assert_equal 10, @@coll.find().count() assert_kind_of Integer, @@coll.find().count() assert_equal 10, @@coll.find({}, :limit => 5).count() - assert_equal 10, @@coll.find({}, :offset => 5).count() + assert_equal 10, @@coll.find({}, :skip => 5).count() assert_equal 1, @@coll.find({"x" => 1}).count() assert_equal 5, @@coll.find({"x" => {"$lt" => 5}}).count() test/test_cursor.rb 2b701119e1deb19726778f2ec4188f0ae2101a6c Mike Dirolf mike@10gen.com http://github.com/jnunemaker/mongo-ruby-driver/commit/70c23e2d32db3fdb50c1e54e46e6a59522a93a83 70c23e2d32db3fdb50c1e54e46e6a59522a93a83 2009-09-17T13:45:03-07:00 2009-09-17T13:45:03-07:00 deprecate :offset option to find in favor of :skip ec0d4166db9e03165706d9de0598e46085059501 Mike Dirolf mike@10gen.com