literal.md

layout	api-command
language	Python
permalink	api/python/literal/
command	literal
related_commands	merge filter merge/ filter/

Command syntax

{% apibody %} r.literal(object) → special {% endapibody %}

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"
}