Mutations

TigerGraph GraphQL Service uses 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:

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

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

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

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

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

{
  "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 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.

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

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

{
  "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.

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

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.

{
  "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 to specify the filter conditions. Edges that meet the conditions are deleted by the mutation.

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

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

{
  "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.

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

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.

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