> List queries, by-ID queries, mutations, relations, and error codes in raw GraphQL

# Queries & Mutations

All entities support list queries, by-ID queries, and create/update/delete mutations.

## List queries

```graphql filename="query"
query {
  customerList(
    pagination: { page: 1, per_page: 20 }
    filter: {
      query: [{
        condition: {
          field: "status"
          operator: equal
          value: "active"
        }
      }]
      sortby: [{ field: "created_at", order: desc }]
    }
  ) {
    data {
      id
      name
      email
      created_at
    }
    pagination {
      current_page
      per_page
      total
      last_page
      has_more_pages
    }
  }
}
```

### Pagination

| Input      | Type  | Default | Description               |
| ---------- | ----- | ------- | ------------------------- |
| `page`     | `Int` | `1`     | Page number (starts at 1) |
| `per_page` | `Int` | `20`    | Items per page            |

| Response         | Type      | Description              |
| ---------------- | --------- | ------------------------ |
| `current_page`   | `Int`     | Current page number      |
| `per_page`       | `Int`     | Items per page           |
| `total`          | `Int`     | Total number of items    |
| `last_page`      | `Int`     | Last page number         |
| `has_more_pages` | `Boolean` | Whether more pages exist |

## By-ID queries

```graphql filename="query"
query {
  customerById(id: "abc123") {
    data {
      id
      name
      email
      company {
        data {
          id
          name
        }
      }
      orders {
        data {
          id
          total
          created_at
        }
      }
    }
  }
}
```

## Relations

Related records live under a `data` wrapper:

```graphql filename="query"
query {
  orderList {
    data {
      id
      total
      # ManyToOne relation
      customer {
        data {
          id
          name
        }
      }
      # OneToMany relation
      line_items {
        data {
          id
          product_name
          quantity
          price
        }
      }
    }
  }
}
```

> **Nested pagination**
> OneToMany relations also accept a `pagination` argument to limit results.

## System fields

Every entity includes:

| Field        | Type       | Description                      |
| ------------ | ---------- | -------------------------------- |
| `id`         | `ID`       | Unique identifier (UUID)         |
| `integer_id` | `Int`      | Auto-incrementing ID             |
| `created_at` | `DateTime` | Creation timestamp (ISO 8601)    |
| `updated_at` | `DateTime` | Last update timestamp (ISO 8601) |

## Create

```graphql filename="mutation"
mutation {
  createCustomer(
    input: {
      name: "Acme Corp"
      email: "contact@acme.com"
      status: "active"
    }
  ) {
    data {
      id
      name
      email
      status
      created_at
    }
  }
}
```

### Creating with relations

Use `_connect` to link existing records:

```graphql filename="mutation"
mutation {
  createOrder(
    input: {
      total: 150.00
      status: "pending"
      customer_connect: [{ id: "customer-123" }]
    }
  ) {
    data {
      id
      total
      customer {
        data { id name }
      }
    }
  }
}
```

## Update

```graphql filename="mutation"
mutation {
  updateCustomer(
    input: {
      id: "customer-123"
      name: "Acme Corporation"
      status: "premium"
    }
  ) {
    data {
      id
      name
      status
      updated_at
    }
  }
}
```

### Managing relations

| Suffix        | Action                |
| ------------- | --------------------- |
| `_connect`    | Add relations         |
| `_disconnect` | Remove relations      |
| `_set`        | Replace all relations |

```graphql filename="mutation"
mutation {
  updateOrder(
    input: {
      id: "order-123"
      line_items_connect: [{ id: "item-1" }, { id: "item-2" }]
      line_items_disconnect: [{ id: "item-old" }]
    }
  ) {
    data {
      id
      line_items { data { id } }
    }
  }
}
```

## Delete

Pass an array of ids:

```graphql filename="mutation"
mutation {
  deleteCustomer(ids: ["customer-1", "customer-2"]) {
    data {
      success
    }
  }
}
```

## Input types

| Type                  | Used for         |
| --------------------- | ---------------- |
| `Create{Entity}Input` | Create mutations |
| `Update{Entity}Input` | Update mutations |

The update input requires `id`. All other fields are optional.

## Error handling

```json filename="response"
{
  "errors": [
    {
      "message": "Validation failed",
      "extensions": {
        "code": "VALIDATION_ERROR",
        "field": "email",
        "details": "Email already exists"
      }
    }
  ],
  "data": null
}
```

| Code               | Description                       |
| ------------------ | --------------------------------- |
| `VALIDATION_ERROR` | Input validation failed           |
| `NOT_FOUND`        | Record not found                  |
| `UNAUTHORIZED`     | Missing or invalid authentication |
| `FORBIDDEN`        | Insufficient permissions          |

Next: [Filtering](/reference/graphql-filtering)