Back to top

    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(r.hashMap("data", r.hashMap("age", 19).with("job", "Engineer")))
     .run(conn);
    
    // Result:
    {
        "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(r.hashMap("data", r.literal(r.hashMap("age", 19).with("job", "Engineer"))))
     .run(conn);
    
    // Result:
    {
        "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(r.hashMap("data", r.literal())).run(conn);
    
    // Result:
    {
        "id": 1,
        "name": "Alice"
    }
    

    Get more help

    Couldn't find what you were looking for?