Command syntax

{% apibody %} value.default(default_value | function) → any sequence.default(default_value | function) → any {% endapibody %}

Description

Provide a default value in case of non-existence errors. The default command evaluates its first argument (the value it's chained to). If that argument returns None or a non-existence error is thrown in evaluation, then default returns its second argument. The second argument is usually a default value, but it can be a function that returns a value.

Example: Retrieve the titles and authors of the table posts. In the case where the author field is missing or None, we want to retrieve the string Anonymous.

r.table("posts").map(lambda post:
    {
        "title": post["title"],
        "author": post["author"].default("Anonymous")
    }
).run(conn)

We can rewrite the previous query with r.branch too.

r.table("posts").map(lambda post:
    r.branch(
        post.has_fields("author"),
        {
            "title": post["title"],
            "author": post["author"]
        },
        {
            "title": post["title"],
            "author": "Anonymous"
        }
    )
).run(conn)

Example: The default command can also be used to filter documents. Retrieve all our users who are not grown-ups or whose age is unknown (i.e., the field age is missing or equals None).

r.table("users").filter(lambda user:
    (user["age"] < 18).default(True)
).run(conn)

One more way to write the previous query is to set the age to be -1 when the field is missing.

r.table("users").filter(lambda user:
    user["age"].default(-1) < 18
).run(conn)

This can be accomplished with has_fields rather than default.

r.table("users").filter(lambda user:
    user.has_fields("age").not_() | (user["age"] < 18)
).run(conn)

The body of every filter is wrapped in an implicit .default(False). You can overwrite the value False with the default option.

r.table("users").filter(
    lambda user: (user["age"] < 18).default(True),
    default=True
).run(conn)

Example: The function form of default receives the error message as its argument.

r.table("posts").map(lambda post:
    {
        "title": post["title"],
        "author": post["author"].default(lambda err: err)
    }
).run(conn)

This particular example simply returns the error message, so it isn't very useful. But it would be possible to change the default value based on the specific error message thrown.