mongo-ruby-driver/docs/READ_PREFERENCE.md

# Read Preference in Ruby

## Setting the read preference

You can using the `:read` option to specify a query's read preference. There are for now two possible options:

    @collection.find({:doc => 'foo'}, :read => :primary)
    @collection.find({:doc => 'foo'}, :read => :secondary)

In the first case, the query will be directed to the primary node in a replica set. In the second, the query will be sent
to a secondary node. The driver will attempt to choose a secondary node that's nearby, as determined by ping time. If more
than one secondary node is closeby (e.g, responds to pings within 10ms), then a random node within this subset will be chosen.

## Read preference inheritance

The Ruby driver allows you to set read preference on each of four levels: the connection, database, collection, and cursor (or read operation).
Objects will inherit the default read preference from their parents. Thus, if you set a read preference of `{:read => :secondary}` when creating
a new connection, then all databases and collections created from that connection will inherit the same setting. See this code example:

    @con = Mongo::ReplSetConnection.new(['localhost:27017','localhost:27018'], :read => :secondary)
    @db  = @con['test']
    @collection = @db['foo']
    @collection.find({:name => 'foo'})

    @collection.find({:name => 'bar'}, :read => :primary)

Here, the first call to Collection#find will use the inherited read preference, `{:read => :secondary}`. But the second call
to Collection#find overrides this setting by setting the preference to `:primary`.

You can examine the read preference on any object by calling its `read_preference` method:

    @con.read_preference
    @db.read_preference
    @collection.read_preference

## Future work

In the v2.0 release of the driver, you'll also be able to specify a read preference consisting of a set of tags. This way,
you'll be able to direct reads to a replica set member. You can follow this issue's progress here: (https://jira.mongodb.org/browse/RUBY-326).