---
title: "Mutations"
component: "graphql"
version: "3.9"
module: "ROOT"
html_url: "/graphql/3.9/mutation"
canonical_url: "https://www.tigergraph.com/docs/graphql/3.9/mutation"
markdown_url: "https://www.tigergraph.com/docs/graphql/3.9/mutation.md"
---

[View as HTML](https://www.tigergraph.com/docs/graphql/3.9/mutation)

# Mutations

TigerGraph GraphQL Service uses [mutations](https://graphql.org/learn/queries/#mutations) to insert and delete vertices and edges.

## Insert vertices

To insert vertices, use a mutation that specifies the graph to insert the vertices into, the primary IDs and any attribute values of the vertices.

Put the name of the graph in the top-level field of the mutation, and use `insert_<vertex_type_name>` as the name of the field that is one level deeper.

For the arguments of the `insert_<vertex_type_name>` field, use an `object` field. The object field can be a single object or a list of objects. The key-value pairs in the object are the primary ID and the attributes of the vertices you want to insert:

```graphql
mutation <operation_name> { (1)
  <graph_name> {
     insert_<vertex_type> (
        objects: [
            {
                <primary_id_attribute>: <primary_id_value>, (2)
                <attribute_name>: <attribute_value>
                ...
            },
            {
                <primary_id_attribute>: <primary_id_value>,
                <attribute_name>: <attribute_value>
                ...
            }
        ] )
    {
        <atrribute_name> (3)
    }
  }
}
```

| **1** | Specifying an operation name is optional. |
| --- | --- |
| **2** | The primary ID value of the vertices you want to insert is required. All other attributes are optional. |
| **3** | You can specify the fields of the newly inserted vertices to be returned. |

For example, the following request creates two `Person` vertices with ID `John` and `Mary`:

* Request
* Response

```graphql
mutation {
  DemoGraph {
     insert_person (
      objects: [
        {
          id: "person_1",
          name: "John",
        	birthYear: 1989
        },
        {
          id: "person_2",
          name: "Mary",
        	birthYear: 2001
        }] )
    {
     	id
    }
  }
}
```

```json
{
  "data": {
    "insert_person": {
      "DemoGraph": {
        "person": [
          {
            "id": "person_1"
          },
          {
            "id": "person_2"
          }
        ]
      }
    }
  },
  "errors": null
}
```

## Insert edges

To insert edges, use a mutation that specifies the endpoint vertices of the edges, and any attribute values for the edges you want to insert.

Put the name of the graph in the top-level field of the mutation, and use `insert_<edge_type_name>` as the name of the field that is one level deeper.

For the arguments of the `insert_<edge_type_name>` field, use an `object` field. The object field can be a single object or a list of objects. The key-value pairs in the object are the source(`from`) and sink(`to`) vertices and attributes of the edges you want to insert. If the edge type is undirected, you can use either endpoint vertices as either source or sink.

For the fields inside the `insert_<edge_type_name>` field:

```graphql
mutation <operation_name> {
  <graph_name> {
     insert_<edge_type> (
        objects:
          [ {
                from: {<primary_id_attribute>: <value>},
                to: {<primary_id_attribute>: <value>}
            }
          ])
     {
        to {
            <attribute_name>
            }
     }
  }
}
```

For example, the following mutation creates an edge between a `person` vertex and a `city` vertex:

* Request
* Response

```graphql
mutation {
  DemoGraph {
    insert_born_in(
      objects: [{ from: { id: "person_1" }, to: { id: "city_1" } }]
    ) {
      from {
        id
      }
    }
  }
}
```

```json
{
  "data": {
    "insert_born_in": {
      "DemoGraph": {
        "born_in": [
          {
            "from": {
              "id": "person_1"
            }
          }
        ]
      }
    }
  },
  "errors": null
}
```

## Delete vertices

There are two ways to delete vertices:

* Specify conditions using a `where` filter for attribute values and delete vertices that meet the condition.
* Specify the IDs of the vertices to delete.

### Delete by filter

To delete vertices that meet certain conditions, use the GraphQL `where` filter to specify the conditions.

Put the name of the graph in the top-level field of the mutation, and use `delete_<vertex_type_name>` as the name of the field that is one level deeper.

In the `delete_<vertex_type_name>` field, use a [where field](https://www.tigergraph.com/docs/graphql/3.9/filtering.md#_filter_with_graphql_where_argument) to specify the filter conditions. Vertices that meet the conditions are deleted by the mutation.

The filter conditions only apply to the attributes of a vertex. If a vertex's primary ID is not declared as an attribute, you cannot use the primary ID to filter for vertices to delete.

```graphql
mutation <operation_name> {
  <graph_name> {
     delete_<vertex_type> (
        where: {
            <conditions>
        })
    {
    <attribute_name>
    }
}
```

For example, the following mutation deletes vertices that have the name "John" or "Mary". In the response, the mutation asks for the ID of the deleted vertices:

* Request
* Response

```graphql
mutation {
  DemoGraph {
    delete_person(
      where: { _or: [{ name: { _eq: "John" } }, { name: { _eq: "Mary" } }] }
    ) {
      id
    }
  }
}
```

```json
{
  "data": {
    "delete_person": {
      "DemoGraph": {
        "person": [
          {
            "id": "person_1"
          },
          {
            "id": "John"
          },
          {
            "id": "person_2"
          }
        ]
      }
    }
  },
  "errors": null
}
```

### Delete by ID

You can delete vertices by their primary ID if the vertex type's primary ID is not an attribute.

Put the name of the graph in the top-level field of the mutation, and use `delete_by_id_<vertex_type_name>` as the name of the field that is one level deeper.

In the `delete_by_id_<vertex_type_name>` field, use an `ids` argument, whose value is a list of all the IDs of the vertices you want to delete.

```graphql
mutation <operation_name> {
  <graph_name> {
     delete_by_id_Person (ids: [<id_value>, <id_value>] ... )
    {
        id
    }
  }
}
```

For example, the following mutation deletes vertices with the ID `Amily`:

* Request
* Response

```graphql
mutation {
  Social { (1)
     delete_by_id_Person (
				ids: ["Amily"]
	)
    {
        name
        age
    }
}
}
```

| **1** | This example uses a different schema because all types in the `DemoGraph` example schema has primary ID as an attribute, which disables deletion by ID. |
| --- | --- |

```graphql
{
  "data": {
    "Social": {
      "Person": [
        {
          "age": 22,
          "name": "Amily"
        }
      ]
    }
  },
  "errors": null
}
```

## Delete an edge

There are two ways to delete an edge:

* Specify conditions using a `where` filter for attribute values and delete edges that meet the condition.
* Specify the IDs of endpoint vertices of the edge to delete.

### Delete by filter

To delete edges that meet certain conditions, use the GraphQL `where` filter to specify the conditions.

Put the name of the graph in the top-level field of the mutation, and use `delete_<edge_type_name>` as the name of the field that is one level deeper.

In the `delete_<edge_type_name>` field, use a [where field](https://www.tigergraph.com/docs/graphql/3.9/filtering.md#_filter_with_graphql_where_argument) to specify the filter conditions. Edges that meet the conditions are deleted by the mutation.

```graphql
mutation <operation_name> {
  <graph_name> {
     delete_<edge_type> (
        where: {
    	   <conditions>
        })
    {
        <attributes>
        <endpoint_vertex_attributes>
    }
  }
}
```

For example, the mutation below deletes edges with the `start_time` greater than `"2001-09-01"`:

* Request
* Response

```graphql
mutation {
  DemoGraph {
    delete_attend(where: { start_time: { _gt: "2001-09-01" } }) {
      from {
        id
      }
    }
  }
}
```

```json
{
  "data": {
    "delete_attend": {
      "DemoGraph": {
        "attend": [
          {
            "from": {
              "id": "Kevin"
            }
          },
          {
            "from": {
              "id": "Emily"
            }
          },
          {
            "from": {
              "id": "Tom"
            }
          },
          {
            "from": {
              "id": "Jenny"
            }
          }
        ]
      }
    }
  },
  "errors": null
}
```

### Delete by vertex IDs

You can delete edges by specifying the IDs of their endpoint vertices if their endpoint vertex types do not have their primary ID as an attribute.

Put the name of the graph in the top-level field of the mutation, and use `delete_by_id_<edge_type_name>` as the name of the field that is one level deeper.

In the `delete_by_id_<edge_type_name>` field, use an object with a `from` and `to` field, each containing the source and sink vertex of the edge. If the edge is undirected, you can use either of the endpoint vertices as the source or sink. As long as you provide both endpoint vertices, the edge is deleted.

```graphql
mutation <operation_name> {
  <graph_name> {
     delete_by_id_<edge_type_name> (
      ids: [
        {
            from:{ <primary_id_attribute>: <value> },
            to:{ <primary_id_attribute>: <value> }
        }] )
    {
        <attributes>
        <endpoint_vertex_attributes>
	}
}
}
```

For example, the following mutation deletes the friendship edge from Tom to Jenny:

* Request
* Response

```graphql
mutation {
  Social { (1)
    delete_by_id_Friendship (
      ids: [{from:{name: "Tom"}, to:{name:"Jenny"}}]
    ) {
      from { name }
      connect_day
    }
  }
}
```

| **1** | This example uses a different schema because all types in the `DemoGraph` example schema has primary ID as an attribute, which disables deletion by ID. |
| --- | --- |

```json
{
  "data": {
    "Social": {
      "Friendship": [
        {
          "connect_day": "2015-01-01 00:00:00",
          "from": {
            "id": "Tom"
          }
        }
      ]
    }
  },
  "errors": null
}
```
