ReQL command: literal

Command syntax

r.literal(object) → special

Description

Replace an object in a field instead of merging it with an existing object in a merge or update operation. Using literal with no arguments in a merge or update operation will remove the corresponding field.

Assume your users table has this structure:

[
    {
        :id => 1,
        :name => "Alice",
        :data => {
            :age => 18,
            :city => "Dallas"
        }
    }       
    ...
]

Using update to modify the data field will normally merge the nested documents:

r.table('users').get(1).update({ :data => { :age => 19, :job => 'Engineer' } }).run(conn)

{
    :id => 1,
    :name => "Alice",
    :data => {
        :age => 19,
        :city => "Dallas",
        :job => "Engineer"
    }
}       

That will preserve city and other existing fields. But to replace the entire data document with a new object, use literal.

Example: Replace one nested document with another rather than merging the fields.

r.table('users').get(1).update({ :data => r.literal({ :age => 19, :job => 'Engineer' }) }).run(conn)

{
    :id => 1,
    :name => "Alice",
    :data => {
        :age => 19,
        :job => "Engineer"
    }
}       

Example: Use literal to remove a field from a document.

r.table('users').get(1).merge({:data => r.literal() }).run(conn)

{
    :id => 1,
    :name => "Alice"
}

Related commands

• merge
• filter

Get more help

Couldn't find what you were looking for?

• Ask a question on Stack Overflow
• Chat with us and our community on Slack
• Talk to the team on IRC on #[email protected] — via Webchat
• Ping @rethinkdb on Twitter
• Post an issue on the documentation issue tracker on GitHub