---
title: "upsert document · RUAL Documentation"
description: "Creates or updates a document with the given GUID. If the document does not exist, it will be created. If it already exists, the mutations will be appli…"
canonical: https://docs.rual.nl/block-types/storage/function_upsert_document_from_mutations
language: en
---

# upsert document

This block is part of the [`storage`](https://docs.rual.nl/block-types/storage) group and was last modified in core [`v15.0.0`](https://docs.rual.nl/core-versions/150000).

### Storage Selection Required

This block relies on a storage to perform its storage releated actions. You must manually select the storage you want to use in your flow using the storage selector modal. To access the modal, click the white button on the block.

Creates or updates a document with the given GUID. If the document does not exist, it will be created. If it already exists, the mutations will be applied to the existing document.

- flow `flow`

- guid required `value` The GUID for this document. If a document with this GUID exists it will be updated, otherwise a new document will be created. • Hidden when other fields are filled

- GUID seed `v15.0.0` `value` Optional fallback when `guid` is not connected: derives the document GUID from this seed exactly like `create document`'s `guid_seed` (the sha256 of the seed), so a create/update/remove/upsert set wired to the same raw seed always addresses the same document. Always wire the RAW seed : never the output of the `generate guid` block, which is already a hash and would be hashed again. • Hidden when other fields are filled

- mutations required `mutations` Provide the mutations for this document. e.g. use `set fields` to set existing/new fields.

- expiry `date` When a document is given an expiry date, the document will be unrecoverably deleted on the given date.

- options `object` Options can be given e.g. `skip_revisions` to skip create revisions for high-update docs or `skip_on_saved` to skip the on-events for this document.

- Storage required `storage` The storage this document will be created in or updated.

- flow `flow`

- success `condition`

- guid `value`

- object `object`

- timestamp `number` timestamp in ms, can be used to wait for the document to be available in search.

- error `value`

- created `condition` Returns `true` if the document was created, `false` if an existing document was updated.

- has changes `v15.0.0` `condition` Returns `true` if the document was created or an existing document had any changes, `false` if an existing document was updated without any effective changes.

A typical wiring for [upsert document](https://docs.rual.nl/block-types/storage/function_upsert_document_from_mutations): [generate guid](https://docs.rual.nl/block-types/value/value_guid) feeds the `guid` pin; [branch](https://docs.rual.nl/block-types/flow/branch) feeds the `flow` pin; [set fields](https://docs.rual.nl/block-types/mutations/mutations_set_bp_field_multiple) feeds the `mutations` pin; the `flow` out pin feeds [return Exposed Data](https://docs.rual.nl/block-types/function%20execution/function_return_exposed); the `success` out pin feeds [branch](https://docs.rual.nl/block-types/flow/branch).

![Studio canvas example for the upsert document block: typical wiring for upsert document.](https://docs.rual.nl/canvas-examples/function_upsert_document_from_mutations.png)

### Commonly used with

In production blueprints, this block is most often wired together with:

- [branch](https://docs.rual.nl/block-types/flow/branch): wired in both directions with this block.

- [generate guid](https://docs.rual.nl/block-types/value/value_guid): feeds into this block. Generates a unique GUID. When a seed is provided, the GUID is deterministic (same seed always produces the same GUID) — the sha256 of the seed, the same derivation the document blocks apply to their guid_seed pin. Wire this output into verbatim guid pins (get / update / remove) to address seed-created documents. Never wire it into a guid_seed pin: that would hash the already-hashed value again and address a different document — give guid_seed pins the raw seed instead.

- [return Exposed Data](https://docs.rual.nl/block-types/function%20execution/function_return_exposed): this block feeds into it. Adds a custom array for each iteration in ForEach, allows you to expose values back to the original flow.

- [set fields](https://docs.rual.nl/block-types/mutations/mutations_set_bp_field_multiple): feeds into this block. Generates an array of mutations based on the given filled fields.

- [reply in JSON](https://docs.rual.nl/block-types/json/httpconnection_set_json): this block feeds into it. Reply to any httpconnection as JSON body.

- [multiple](https://docs.rual.nl/block-types/mutations/mutations_add): feeds into this block. combine multiple mutations into one.

### Version history

Introduced in [`v14.0.5`](https://docs.rual.nl/core-versions/140005).

Last modified in [`v15.0.0`](https://docs.rual.nl/core-versions/150000).