---
schema_version: "1"
id: 555611663e9513bf3336cd3fd6ad545770a2d7b1bfb8071e8066f5936b296806
title: Writing GraphQL Queries and Mutations in DataGraph
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/datagraph/write-queries-tutorial.md
canonical_url: https://docs.mulesoft.com/datagraph/write-queries-tutorial
source_site: docs.mulesoft.com
content_type: documentation
content_hash: e59ad0fd16885128292ad40bd9d3ab4b82acbea64528f3b483d3ab0c3f7cdf1f
description: MuleSoft Documentation Site
latest: true
---
---
product: DataGraph
---

# Writing GraphQL Queries and Mutations in DataGraph

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

This brief tutorial introduces key concepts for writing GraphQL queries in Anypoint DataGraph.

Learn how to use the Anypoint DataGraph query editor to:

1.  Discover and add a query operation

2.  Add input parameters to a query

3.  Discover which fields are available to query

4.  Add nested types

5.  Add a query alias

6.  Write a mutation and understand query types

## Discover and Add a Query Operation

In GraphQL, query methods serve as the entry points to retrieve the data you want. Start by using
the schema explorer in the Anypoint DataGraph query editor to discover which query methods are
available for an API schema.

For example, the Catalyst Order API schema, used in the
[DataGraph quick start guide](https://docs.mulesoft.com/datagraph/datagraph-qsg), has two query methods associated with it:
`ordersCustomerByCustomerId` and `ordersByOrderId`:

![Two query methods listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-query-method.png)

Consider `ordersByOrderId`: This query method returns data about the object type `OrderResponse` and
requires an argument for `orderID` in the form of a string:

`ordersByOrderId (orderId:String!):OrderResponse`

In GraphQL, you add the query method to start a query:

```copy
{
  ordersByOrderId(orderId:String!)
}
```

## Add Input Parameters

Notice that the input parameter for the query method `orderID` is a non-nullable field, as indicated
by the exclamation point (`!`). This field requires a string data type that is not a null value.

In this case, you need to add an order ID to the query:

```copy
{
  ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3")
}
```

## Add Fields

Fields represent a type’s dataset that is returned in a query response, and you can choose whatever
fields you need when writing a query. For example, as previously mentioned, the `ordersByOrderID`
query method returns the `OrderResponse` object type, which returns the following fields:

![Available fields listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-fields.png)

As you write a query, you can add or remove any of these fields. The following query a uses some of
the available fields:

```copy
{
  ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") {
    customerId
    status
    subtotal
    taxPrice
    total
    trackingNumber
  }
}
```

`OrderResponse` is a Level-1 type, meaning you can access it directly with a query method, as in the
previous example.

## Add Fields for Nested Types

Many of the fields returned by the OrderResponse object type, such as `billingAddress`, are object
types themselves that contain additional data that can make your query result more valuable. These
additional types are known as nested types.

The `billingAddress` object type returns the `PostalAddress` object type, which itself returns
several additional fields. To query `billingAddress`, you must specify which fields to return from
`PostalAddress`. For example:

```copy
{
  ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") {
    billingAddress {
      state
      city
      postalCode
    }
  }
}
```

As a result, your final query looks like:

```none
{
  ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") {
    customerId
    status
    subtotal
    taxPrice
    total
    trackingNumber
    billingAddress {
      state
      city
      postalCode
    }
  }
}
```

For this query, Anypoint DataGraph returns:

```none
{
  "data": {
    "ordersByOrderId": {
      "customerId": "1964401a-a8b3-40c1-b86e-d8b9f75b5842",
      "status": "Draft",
      "subtotal": "100.21",
      "taxPrice": "15.22",
      "total": "125.43",
      "trackingNumber": "",
      "billingAddress": {
        "state": "CA",
        "city": "San Francisco",
        "postalCode": "94210"
      }
    }
  }
}
```

## Add a Query Alias

You can use aliases to rename individual keys in the query response.

For example, you can rename the total field to `totalPrice` and the status field to `orderStatus` in
only your query response.

```copy
{
  ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") {
    billingAddress {
      state
      city
      postalCode
    }
    totalPrice : total
    orderStatus : status
  }
}
```

If you want to get the same fields for two or more query operations using different input
parameters, you can provide an alias to the query operations.

```copy
{
  Order1: ordersByOrderId(orderId: "51c0ba3a-7e64-11e7-bb31-be2e44b06b3") {
    billingAddress {
      state
      city
      postalCode
    }
    totalPrice : total
    orderStatus : status
  }

  Order2: ordersByOrderId(orderId: "87c0ba4a-de28-12o7-pd11-eew12094b0w4) {
    billingAddress {
      state
      city
      postalCode
    }
    totalPrice : total
    orderStatus : status
  }
}
```

This helps to avoid errors if the same fields get different values.

## Write a Mutation

_Mutations_ are operations you use to add, update, and delete data objects. In GraphQL, mutation
operations represent the POST, PUT, PATCH, and DELETE HTTP methods you’ve defined in your REST API
specification.

To simplify the schema, inputs to mutations are handled by _input types_, which represent the
attributes of objects created by mutation operations. Input types are POST, PUT, and DELETE request
objects you use to modify information in your unified schema when you run mutations.

For example, the schema shown in the following example has six mutation operations associated with
it:

![Six mutation operations listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-mutation-method.png)

Consider `createCustomer`: This mutation takes the `CustomerInput` object as an input and creates a
new object of type `Customer`.

So in this case, the input type `CustomerInput` has the following fields:

![Fields for CustomerInput listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-mutation-fields.png)

Notice that the address field has data from the `AddressInput` input type:

![Fields for AddressInput listed in the schema explorer](/mulesoft/current/en-us/datagraph/_images/schema-explorer-mutation-fields2.png)

As you execute the mutation operation, you provide a value for each field in the input type:

```copy
mutation {
  createCustomer(input: {
    firstName: "Lydia",
    lastName: "Millet",
    address: {
      city: "Tucson",
      state: "Arizona",
      street: "Speedway",
      postalCode: "1234"
    }
  })
  {
    id
  }
}
```

Because this mutation creates a new customer, DataGraph returns the following:

{ "data": { "createCustomer": { "id": 42 } } }

Note that the `CustomerInput` input type does not have an `id` field, so the mutation doesn’t
include that field in the input to the mutation. However, the `Customer` type includes an `id`
field, the value of which is generated based on the values provided in the input.

## Additional Resources

- [GraphQL Query Documentation](https://graphql.org/learn/queries/)

- [Anypoint DataGraph Terminology](https://docs.mulesoft.com/datagraph/datagraph-terms)

- [Understanding the Elements in an API Schema](https://docs.mulesoft.com/datagraph/schemas)

- [Running Queries and Mutations](https://docs.mulesoft.com/datagraph/query-unified-schema)