Command syntax

Description

Return all the elements in a sequence for which the given predicate is true. The return value of filter will be the same as the input (sequence, stream, or array). Documents can be filtered in a variety of ways—ranges, nested values, boolean conditions, and the results of anonymous functions.

By default, filter will silently skip documents with missing fields: if the predicate tries to access a field that doesn’t exist (for instance, the predicate {:age => 30} applied to a document with no age field), that document will not be returned in the result set, and no error will be generated. This behavior can be changed with the default optional argument.

• If default is set to true, documents with missing fields will be returned rather than skipped.
• If default is set to r.error(), an ReqlRuntimeError will be thrown when a document with a missing field is tested.
• If default is set to false (the default), documents with missing fields will be skipped.

Basic predicates

Example: Get all users who are 30 years old.

r.table('users').filter({:age => 30}).run(conn)

The predicate {'age': 30} selects documents in the users table with an age field whose value is 30. Documents with an age field set to any other value or with no age field present are skipped.

While the {'field': value} style of predicate is useful for exact matches, a more general way to write a predicate is to use a Ruby block that returns true or false.

r.table('users').filter{ |user|
    user["age"].eq(30)
}.run(conn)

In this case, the function returns true if the field age is equal to 30.

Predicates to filter are evaluated on the server, and must use ReQL expressions. Some Ruby comparison operators are overloaded by the RethinkDB driver and will be translated to ReQL, such as ==, </> and |/& (note the single character form, rather than ||/&&).

Also, predicates must evaluate document fields. They cannot evaluate secondary indexes.

Example: Get all users who are more than 18 years old.

r.table("users").filter{ |user|
    user["age"] > 18
}.run(conn)

Example: Get all users who are less than 18 years old and more than 13 years old.

r.table("users").filter{ |user|
    (user["age"] < 18) & (user["age"] > 13)
}.run(conn)

Example: Get all users who are more than 18 years old or have their parental consent.

r.table("users").filter{ |user|
    (user["age"] >= 18) | (user["hasParentalConsent"])
}.run(conn)

More complex predicates

Example: Retrieve all users who subscribed between January 1st, 2012 (included) and January 1st, 2013 (excluded).

r.table("users").filter{ |user|
    user["subscription_date"].during(r.time(2012, 1, 1, 'Z'),
        r.time(2013, 1, 1, 'Z'))
}.run(conn)

Example: Retrieve all users who have a gmail account (whose field email ends with @gmail.com).

r.table("users").filter{ |user|
    user["email"].match("@gmail.com$")
}.run(conn)

Example: Filter based on the presence of a value in an array.

Given this schema for the users table:

{
    :name => String
    :places_visited => [String]
}

Retrieve all users whose field places_visited contains France.

r.table("users").filter{|user|
    user["places_visited"].contains("France")
}.run(conn)

Example: Filter based on nested fields.

Given this schema for the users table:

{
    :id => String
    :name => {
        :first => String,
        :middle => String,
        :last => String
    }
}

Retrieve all users named “William Adama” (first name “William”, last name “Adama”), with any middle name.

r.table("users").filter({
    :name => {
        :first => "William",
        :last => "Adama"
    }
}).run(conn)

If you want an exact match for a field that is an object, you will have to use r.literal.

Retrieve all users named “William Adama” (first name “William”, last name “Adama”), and who do not have a middle name.

r.table("users").filter(r.literal({
    :name => {
        :first => "William",
        :last=> "Adama"
    }
})).run(conn)

You may rewrite these with blocks.

r.table("users").filter{ |user|
    (user["name"]["first"].eq("William")) &
    (user["name"]["last"].eq("Adama"))
}.run(conn)

r.table("users").filter{ |user|
    user["name"].eq({
        :first => "William",
        :last => "Adama"
    })
}.run(conn)

Handling missing fields

By default, documents missing fields tested by the filter predicate are skipped. In the previous examples, users without an age field are not returned. By passing the optional default argument to filter, you can change this behavior.

Example: Get all users less than 18 years old or whose age field is missing.

r.table("users").filter(:default => true){ |user| user["age"] < 18 }.run(conn)

Example: Get all users more than 18 years old. Throw an error if a document is missing the field age.

r.table("users").filter(:default => r.error()){
    |user| user["age"] > 18
}.run(conn)

Example: Get all users who have given their phone number (all the documents whose field phone_number exists and is not nil).

r.table('users').filter{ |user|
    user.has_fields('phone_number')
}.run(conn)

Example: Get all users with an “editor” role or an “admin” privilege.

r.table('users').filter{ |user|
    user['role'].eq('editor').default(false) |
        user['privilege'].eq('admin').default(false)
}.run(conn)

Instead of using the default optional argument to filter, we have to use default values on the fields within the or clause. Why? If the field on the left side of the or clause is missing from a document—in this case, if the user doesn’t have a role field—the predicate will generate an error, and will return false (or the value the default argument is set to) without evaluating the right side of the or. By using .default(false) on the fields, each side of the or will evaluate to either the field’s value or false if the field doesn’t exist.