---
title: "Mutation"
description: "The Mutation type is used to define declarative data mutations. It is required input for the useDataMutation hook, DataMutation component, and DataEngine.mutate method."
url: https://developers.dhis2.org/docs/app-runtime/types/Mutation
source: https://github.com/dhis2/app-runtime/tree/master/docs/types/Mutation.md
---

# Mutation

The Mutation type is used to define declarative data mutations. It is required input for the [useDataMutation](https://developers.dhis2.org/docs/app-runtime/hooks/useDataMutation.md) hook, [DataMutation](https://developers.dhis2.org/docs/app-runtime/components/DataMutation.md) component, and [DataEngine.mutate](https://developers.dhis2.org/docs/app-runtime/advanced/DataEngine.md) method.

A mutation defines a destructive operation performed on a collection or instance of a particular resource.

## Properties

|   Property   |              Type              |              | Description                                                                                                                                                |
| :----------: | :----------------------------: | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   **type**   |            _string_            | **required** | The type of mutation to perform, must be one of `create`, `update`, `json-patch`\*, or `delete`.                                                           |
| **resource** |            _string_            | **required** | The path to the resource being requested, i.e. `indicators`.                                                                                               |
|    **id**    | _string_ **or** _() => string_ |              | Required for `update` and `delete` mutations, not allowed for `create` mutations. Indicates that a particular **instance** of a collection will be mutated |
| **partial**  |           _boolean_            |              | If performing an `update` mutation, set `partial: true` to replace only the provided fields of the target object.                                          |
|  **params**  | _Object_ **or** _() => Object_ |              | A dictionary of properties which are translated into querystring parameters when the data is fetched                                                       |
|   **data**   | _Object_ **or** _() => Object_ |              | The "body" of the mutation, the content of the newly created or updated resource. Disallowed for `delete` mutations                                        |

> See the [Mutation type definition](https://github.com/dhis2/app-runtime/blob/master/services/data/src/engine/types/Mutation.ts) for more information

> \* When choosing the `json-patch` type, a PATCH request with content-type `application/json-patch+json` will be sent and the server will expect the "body" of the mutation to be a "patch document" (i.e. an array of operations). See [jsonpatch.com](http://jsonpatch.com) for a brief overview, or JSON Patch specifications in [RFC 6902](http://tools.ietf.org/html/rfc6902) for full details.

## Examples

Delete an existing indicator

```js
const deleteMutation = {
    type: 'delete',
    resource: 'indicators',
    id: 'xyz123',
}
```

Update an existing indicator, only overwriting the `name` property

```js
const updateMutation = {
    type: 'update',
    partial: true,
    resource: 'indicators',
    id: 'xyz123',
    data: {
        name: 'MyNewName',
    },
}
```

Create a new indicator, accepting the `name` as a variable, allowing it to be specified at the time the mutation is executed

```js
const dynamicCreateMutation = {
    type: 'create',
    resource: 'indicators',
    data: ({ name }) => ({
        name,
        shortName: name,
        indicatorType: {
            id: 'bWuNrMHEoZ0',
        },
        numerator: '#{fbfJHSPpUQD}',
        denominator: '#{h0xKKjijTdI}',
    }),
}
```