# graphql

Executes queries and mutations against Shopify's GraphQL Admin API. The response is stored in a variable for further processing.

```liquid
{% graphql query: product_query, variables: my_variables as result %}

{% if result.product %}
  {% log result.product.title %}
{% endif %}
```

#### Syntax

```liquid
{% graphql query: query_string, variables: variables_object as result_variable %}
```

#### Parameters

| Parameter   | Required | Description                                           |
| ----------- | -------- | ----------------------------------------------------- |
| `query`     | Yes      | GraphQL query or mutation string                      |
| `variables` | No       | Object containing variables for the GraphQL operation |

#### Result Object

The result contains the returned data directly accessible at the top level. Query fields are available as properties on the result variable.

Example query:

```liquid
{% graphql query: product_query, variables: vars as result %}
{% comment %} Access result.product directly, not result.data.product {% endcomment %}
```

If errors occur, they are available in the `errors` property:

| Property | Type       | Description                                    |
| -------- | ---------- | ---------------------------------------------- |
| `errors` | array/null | Array of error objects if the operation failed |

Example result for a product query:

```json
{
  "product": {
    "id": "gid://shopify/Product/123",
    "title": "Example Product"
  }
}
```

#### Examples

**Basic product query:**

```liquid
{% capture query %}
  query getProduct($id: ID!) {
    product(id: $id) {
      id
      title
      handle
      status
    }
  }
{% endcapture %}

{% json variables %}
  {
    "id": "gid://shopify/Product/{{ product_id }}"
  }
{% endjson %}

{% graphql query: query, variables: variables as result %}

{% if result.product %}
  {% log "Product title:" %}
  {% log result.product.title %}
{% endif %}
```

**Update product with mutation:**

```liquid
{% capture mutation %}
  mutation updateProduct($input: ProductInput!) {
    productUpdate(input: $input) {
      product {
        id
        title
      }
      userErrors {
        field
        message
      }
    }
  }
{% endcapture %}

{% json variables %}
  {
    "input": {
      "id": "gid://shopify/Product/{{ product_id }}",
      "title": "{{ new_title }}"
    }
  }
{% endjson %}

{% graphql query: mutation, variables: variables as result %}

{% if result.productUpdate.userErrors.size > 0 %}
  {% for error in result.productUpdate.userErrors %}
    {% log error.message %}
  {% endfor %}
{% else %}
  {% log "Product updated successfully" %}
{% endif %}
```

**Paginated query with cursor:**

```liquid
{% capture query %}
  query getCustomers($cursor: String, $query: String) {
    customers(first: 50, after: $cursor, query: $query) {
      edges {
        node {
          id
          email
          firstName
          lastName
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
{% endcapture %}

{% assign cursor = null %}
{% assign all_customers = "" | split: "" %}

{% for i in (1..100) %}
  {% json variables %}
    {
      "cursor": {{ cursor | json }},
      "query": "tag:vip"
    }
  {% endjson %}

  {% graphql query: query, variables: variables as result %}

  {% for edge in result.customers.edges %}
    {% assign all_customers = all_customers | push: edge.node %}
  {% endfor %}

  {% if result.customers.pageInfo.hasNextPage %}
    {% assign cursor = result.customers.pageInfo.endCursor %}
  {% else %}
    {% break %}
  {% endif %}
{% endfor %}

{% log "Total customers found: " | append: all_customers.size %}
```

**Query with dynamic variables:**

```liquid
{% capture query %}
  query getOrder($id: ID!) {
    order(id: $id) {
      id
      name
      totalPriceSet {
        shopMoney {
          amount
          currencyCode
        }
      }
      lineItems(first: 50) {
        edges {
          node {
            title
            quantity
          }
        }
      }
    }
  }
{% endcapture %}

{% assign order_gid = "gid://shopify/Order/" | append: order.id %}

{% json variables %}
  {
    "id": "{{ order_gid }}"
  }
{% endjson %}

{% graphql query: query, variables: variables as order_data %}

{% assign total = order_data.order.totalPriceSet.shopMoney.amount %}
{% log "Order total:" | append: total %}
```

**Handle errors gracefully:**

```liquid
{% capture query %}
  query getInventory($id: ID!) {
    inventoryItem(id: $id) {
      id
      tracked
      inventoryLevels(first: 10) {
        edges {
          node {
            available
            location {
              name
            }
          }
        }
      }
    }
  }
{% endcapture %}

{% json variables %}
  {
    "id": "gid://shopify/InventoryItem/{{ inventory_item_id }}"
  }
{% endjson %}

{% graphql query: query, variables: variables as result %}

{% if result.errors %}
  {% log "GraphQL error occurred:" %}
  {% for error in result.errors %}
    {% log error.message %}
  {% endfor %}
{% else %}
  {% for level in result.inventoryItem.inventoryLevels.edges %}
    {% log level.node.location.name %}
    {% log level.node.available %}
  {% endfor %}
{% endif %}
```

**Bulk operation query:**

```liquid
{% capture mutation %}
  mutation bulkOperationRunQuery($query: String!) {
    bulkOperationRunQuery(query: $query) {
      bulkOperation {
        id
        status
      }
      userErrors {
        field
        message
      }
    }
  }
{% endcapture %}

{% capture bulk_query %}
{
  products {
    edges {
      node {
        id
        title
        variants {
          edges {
            node {
              id
              sku
              inventoryQuantity
            }
          }
        }
      }
    }
  }
}
{% endcapture %}

{% json variables %}
  {
    "query": {{ bulk_query | json }}
  }
{% endjson %}

{% graphql query: mutation, variables: variables as result %}

{% if result.bulkOperationRunQuery.bulkOperation %}
  {% log "Bulk operation started:" %}
  {% log result.bulkOperationRunQuery.bulkOperation.id %}
{% endif %}
```

#### Notes

* Consumes 1 credit per operation
* Uses the store's API version configured in DataJet
* GraphQL errors are automatically logged to the script logs
* Variables must be a valid object (use `json` tag to construct complex variables)
* For large datasets, use pagination with cursors to avoid timeouts
* Result properties are accessed directly (e.g., `result.products`, not `result.data.products`)
* Refer to [Shopify's GraphQL Admin API documentation](https://shopify.dev/docs/api/admin-graphql) for available queries and mutations


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.datajet-app.com/liquid/tags/graphql.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.