# CDF Graph Query Syntax

The `query_instances` tool executes graph queries that can traverse relationships
and return data from multiple views in a single call.

## Query Structure

```json
{
  "with": {
    "<result_set_name>": {
      "nodes": { ... }    // or "edges": { ... }
    }
  },
  "select": {
    "<result_set_name>": {
      "sources": [
        {
          "source": {"space": "s", "externalId": "ViewId", "version": "v1"},
          "properties": ["prop1", "prop2"]
        }
      ]
    }
  }
}
```

## Basic Query: List Nodes from a View

```json
{
  "with": {
    "orders": {
      "nodes": {
        "filter": {
          "hasData": [{"space": "cdf_idm", "externalId": "CogniteMaintenanceOrder", "version": "v1", "type": "view"}]
        },
        "limit": 10
      }
    }
  },
  "select": {
    "orders": {
      "sources": [
        {
          "source": {"space": "cdf_idm", "externalId": "CogniteMaintenanceOrder", "version": "v1"},
          "properties": ["name", "description", "status", "priority", "startTime", "endTime"]
        }
      ]
    }
  }
}
```

## Traversal Query: Follow a Relationship

Start from one set of nodes and traverse a relationship to related nodes.

```json
{
  "with": {
    "assets": {
      "nodes": {
        "filter": {
          "equals": {
            "property": ["cdf_idm", "CogniteAsset/v1", "name"],
            "value": "Pump-001"
          }
        }
      }
    },
    "related_orders": {
      "nodes": {
        "from": "assets",
        "through": {"source": {"space": "cdf_idm", "externalId": "CogniteMaintenanceOrder", "version": "v1"}, "identifier": "asset"},
        "direction": "inwards"
      }
    }
  },
  "select": {
    "assets": {
      "sources": [
        {
          "source": {"space": "cdf_idm", "externalId": "CogniteAsset", "version": "v1"},
          "properties": ["name", "description"]
        }
      ]
    },
    "related_orders": {
      "sources": [
        {
          "source": {"space": "cdf_idm", "externalId": "CogniteMaintenanceOrder", "version": "v1"},
          "properties": ["name", "status", "priority"]
        }
      ]
    }
  }
}
```

## Key Concepts

### Result Set Expressions (`with`)
- `nodes`: Match node instances
- `edges`: Match edge instances
- `from`: Chain from another result set (for traversals)
- `through`: The relationship property to traverse (reference: `{"source": {"space": "...", "externalId": "...", "version": "..."}, "identifier": "propertyName"}`)
- `direction`: `"outwards"` (default) or `"inwards"`
- `filter`: Optional filter (same syntax as list_instances filters)
- `limit`: Max results per result set

### Select
- Maps result set names to the properties you want returned
- Each source specifies a view and which properties to include
- Omit `properties` to get all properties from that view

### Pagination
- Pass `"cursors": {"<result_set>": "<cursor_value>"}` from a previous response to page through results

## Notes

- Instance space filters are automatically injected by the server
- Each result set can have its own limit
- Traversals always start from a root result set (one without `from`)
- Multiple traversal hops are supported by chaining result sets
