> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-repository-api/graphql-basics/graphql-tips-and-patterns.md).

# GraphQL tips and patterns

{% hint style="warning" %}
**Navixy Repository API is a work in progress.** This documentation is published for preview purposes only and doesn't reflect a stable release. Structure, field names, and behaviors are subject to change.
{% endhint %}

This article covers patterns that make your GraphQL code cleaner, more maintainable, and easier to debug. If you're new to GraphQL, start with [GraphQL basics ](/docs/navixy-repository-api/graphql-basics.md)first.

## Variables

When you're testing queries, it's easy to write values directly into the query string. But real applications need to pass different values each time: a user might click on another device, select a different filter, or navigates to the next page.

Variables solve this by separating what you're asking for (the query) from the specific values (the variables). Think of it like a function: the query is the function definition, and variables are the arguments you pass in.

Here's a query without variables:

```graphql
query GetDevice {
  device(id: "550e8400-e29b-41d4-a716-446655440001") {
    title
  }
}
```

And here's the same query with a variable:

```graphql
query GetDevice($deviceId: ID!) {
  device(id: $deviceId) {
    title
  }
}
```

The variable `$deviceId` is declared in parentheses after the operation name. The `ID!` part specifies the type (must match what the schema expects). Then you use `$deviceId` wherever you need that value in the query.

The actual value is passed separately as JSON:

```json
{
  "deviceId": "550e8400-e29b-41d4-a716-446655440001"
}
```

When you send the request, include both the query and the variables. GraphQL tools and client libraries handle this for you — you just provide the variables object.

### Multiple variables

You can declare as many variables as you need:

```graphql
query ListDevices($orgId: ID!, $statusIds: [ID!], $limit: Int = 20) {
  devices(
    organizationId: $orgId
    filter: { statusIds: $statusIds }
    first: $limit
  ) {
    nodes {
      id
      title
    }
  }
}
```

In this example:

* `$orgId: ID!` is required (`!` means it cannot be null)
* `$statusIds: [ID!]` is an optional array of IDs (no `!` after the brackets)
* `$limit: Int = 20` is optional with a default value of 20

Variables in JSON:

```json
{
  "orgId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "statusIds": ["a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"],
  "limit": 50
}
```

## Operation names

You can give your operations custom names to make them easier to identify in logs, debugging tools, and network traces.

The name `GetDevice` appears after the operation type (`query`, `mutation`, or `subscription`). It doesn't affect execution, as the API ignores it, but helps in several ways:

* Debugging: Error messages and server logs reference the operation name
* Tooling: GraphQL clients use names for caching and request deduplication
* Analytics: Track which operations are called most frequently
* Readability: Self-documenting code, especially with multiple operations

Mutations benefit from naming too:

```graphql
query GetDevice($id: ID!) {
  device(id: $id) {
    title
    status { code }
  }
}
```

Common naming conventions use PascalCase with a verb prefix: `GetDevice`, `ListDevices`, `UpdateAsset`, `CreateGeoObject`, `DeleteSchedule`.

## Fragments

Fragments let you define reusable sets of fields. They're useful when you need the same fields in multiple queries.

Define a fragment on a specific type:

```graphql
fragment DeviceFields on Device {
  id
  version
  title
  status { code title }
  organization { id title }
}
```

Use it in queries with the spread operator (`...`):

```graphql
query GetDevice($id: ID!) {
  device(id: $id) {
    ...DeviceFields
    customFields
  }
}

query ListDevices($orgId: ID!) {
  devices(organizationId: $orgId, first: 10) {
    nodes {
      ...DeviceFields
    }
  }
}
```

Both queries now share the same field selection for core device data.

### Inline fragments for interfaces

When working with interfaces like [Node](/docs/navixy-repository-api/graphql-reference/all-operations-and-types/interfaces.md#node), use inline fragments to request type-specific fields:

```graphql
query GetNode($id: ID!) {
  node(id: $id) {
    id
    ... on Device {
      title
      status { code }
    }
    ... on Asset {
      title
      type { code title }
    }
    ... on Organization {
      title
      features
    }
  }
}
```

The `node` query returns any entity by ID. The inline fragments (`... on Type`) tell GraphQL what fields to return based on the actual type.

## Aliases

Aliases let you rename fields in the response or fetch the same field multiple times with different arguments.

### Renaming fields

```graphql
query GetTwoDevices {
  truck: device(id: "device-uuid-1") {
    title
  }
  trailer: device(id: "device-uuid-2") {
    title
  }
}
```

Response:

```json
{
  "data": {
    "truck": { "title": "Truck 42" },
    "trailer": { "title": "Trailer A7" }
  }
}
```

### Comparing entities

Fetch the same entity at different points or with different parameters:

```graphql
query CompareOrganizations {
  parent: organization(id: "parent-org-uuid") {
    title
    features
    children(first: 5) {
      total { count }
    }
  }
  child: organization(id: "child-org-uuid") {
    title
    features
    parent { title }
  }
}
```

### Batch mutations

Aliases enable batch operations in a single request:

```graphql
mutation BatchUpdateDevices {
  device1: deviceUpdate(input: {
    id: "uuid-1"
    version: 3
    title: "Truck 42 - Updated"
  }) {
    device { id version title }
  }
  device2: deviceUpdate(input: {
    id: "uuid-2"
    version: 5
    title: "Truck 43 - Updated"
  }) {
    device { id version title }
  }
}
```

Each aliased mutation executes independently. If one fails, others can still succeed (check the `errors` array for partial failures).

## Directives

Directives modify how fields are executed. GraphQL includes [six built-in directives](/docs/navixy-repository-api/core-api-reference/directives.md) for conditional field inclusion.

Directives can be used to:

* Hide fields the user can't access
* Skip expensive fields when not needed
* Fetch fewer fields on mobile devices

```graphql
query ListDevices(
  $orgId: ID!
  $includeDetails: Boolean!
  $includeAudit: Boolean!
) {
  devices(organizationId: $orgId, first: 20) {
    nodes {
      id
      title
      status @include(if: $includeDetails) { code title }
      organization @include(if: $includeDetails) { title }
      type @include(if: $includeAudit) { code }
      version @include(if: $includeAudit)
    }
  }
}
```

## See also

* Browse available operations and types by category, starting with [Directives](/docs/navixy-repository-api/core-api-reference/directives.md) and [Common resources](/docs/navixy-repository-api/core-api-reference/common.md)
* [Error handling](/docs/navixy-repository-api/error-handling.md): Understand error responses and codes


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://navixy.com/docs/navixy-repository-api/graphql-basics/graphql-tips-and-patterns.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.