<commit_before>---
layout: api-command
language: JavaScript
permalink: api/javascript/literal/
command: literal
io:
    -   - object
        - special
related_commands:
    merge: merge/
    filter: filter/
---
# Command syntax #

{% apibody %}
r.literal(object) &rarr; special
{% endapibody %}

# Description #

Replace an object in a field instead of merging it with an existing object in a `merge` or `update` operation.

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

Assume your users table has this structure:

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

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

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

Result:

```js
{
    "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`:

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

Result:

```js
{
    "id": 1,
    "name": "Alice",
    "data": {
        "age": 19,
        "job": "Engineer"
    }
}       
```
<commit_msg>Fix io for r.literal<commit_after>---
layout: api-command
language: JavaScript
permalink: api/javascript/literal/
command: literal
io:
    -   - r
        - special
related_commands:
    merge: merge/
    filter: filter/
---
# Command syntax #

{% apibody %}
r.literal(object) &rarr; special
{% endapibody %}

# Description #

Replace an object in a field instead of merging it with an existing object in a `merge` or `update` operation.

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

Assume your users table has this structure:

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

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

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

Result:

```js
{
    "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`:

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

Result:

```js
{
    "id": 1,
    "name": "Alice",
    "data": {
        "age": 19,
        "job": "Engineer"
    }
}       
```

{'fraction_non_alphanumeric': 0.1652864044168392, 'fraction_numerical': 0.010351966873706004, 'mean_word_length': 2.480192076830732, 'pattern_counts': {'":': 32, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1077257', 'n_tokens_mistral': 1018, 'n_tokens_neox': 953, 'n_words': 305}