Logo
NeoArc Studio

Queries and Mutations

Document GraphQL queries for data retrieval and mutations for data modification. Learn patterns for CRUD operations, input types, and error handling.

Queries and mutations form the foundation of GraphQL API operations. Queries retrieve data without side effects, while mutations modify server state. This guide covers patterns and best practices for documenting both operation types.

Query Operations

Queries are read-only operations that fetch data from your API. They are idempotent, meaning the same query executed multiple times returns the same result (assuming no intervening mutations).

Common Query Patterns

Query Example

{
  "id": "query-products-001",
  "name": "products",
  "operationType": "query",
  "description": "Retrieves a paginated list of products with optional filtering by category, price range, and availability.",
  "returnTypeName": "ProductConnection!",
  "returnTypeNullable": false,
  "arguments": [
    {
      "id": "arg-first",
      "name": "first",
      "typeName": "Int",
      "nullable": true,
      "defaultValue": "20",
      "description": "Number of products to return",
      "validation": { "min": 1, "max": 100 }
    },
    {
      "id": "arg-after",
      "name": "after",
      "typeName": "String",
      "nullable": true,
      "description": "Cursor for pagination"
    },
    {
      "id": "arg-category",
      "name": "category",
      "typeName": "ProductCategory",
      "nullable": true,
      "description": "Filter by product category"
    }
  ],
  "complexity": 10,
  "tags": ["products", "catalogue"]
}

Mutation Operations

Mutations modify server state by creating, updating, or deleting resources. Unlike queries, mutations have side effects and should be documented with clear input requirements and possible outcomes.

Common Mutation Patterns

Mutation Example

{
  "id": "mutation-create-order-001",
  "name": "createOrder",
  "operationType": "mutation",
  "description": "Creates a new order with the specified items. Validates inventory availability and applies pricing rules.",
  "returnTypeName": "CreateOrderPayload!",
  "returnTypeNullable": false,
  "arguments": [
    {
      "id": "arg-input",
      "name": "input",
      "typeName": "CreateOrderInput",
      "nullable": false,
      "typeSchemaRef": "schemas/create-order-input.cf.schema.json",
      "description": "Order details including customer, items, and shipping address"
    }
  ],
  "exampleQuery": "mutation CreateOrder($input: CreateOrderInput!) {\n  createOrder(input: $input) {\n    order {\n      id\n      status\n      total\n    }\n    userErrors {\n      field\n      message\n    }\n  }\n}",
  "exampleVariables": "{\n  \"input\": {\n    \"customerId\": \"cust-123\",\n    \"items\": [\n      { \"productId\": \"prod-456\", \"quantity\": 2 }\n    ],\n    \"shippingAddressId\": \"addr-789\"\n  }\n}",
  "complexity": 25,
  "tags": ["orders", "commerce"]
}

Input Types

Complex mutations typically use input types to group related arguments. Reference input type schemas using the typeSchemaRef property:

{
  "id": "arg-input",
  "name": "input",
  "typeName": "CreateUserInput",
  "typeSchemaRef": "schemas/create-user-input.cf.schema.json",
  "nullable": false,
  "description": "User creation details"
}

Error Handling Patterns

Document how operations handle errors:

Related Content