33.4 Querying

A list root field returns a page: items, totalCount (the matches before paging), the pageIndex and pageSize used, and durationMs. Its arguments:

Argument	What it does
`filter`	Conditions on the type's fields. All must match; `and`, `or` and `not` combine them.
`search`	Free-text search, matched as `WhereSearch` does (§21). It filters, so the result is not ordered by relevance.
`orderBy`, `descending`	Order by one field. Only orderable fields are in the enum. Without `orderBy`, nodes come in the store's order.
`page`, `pageSize`	A zero-based page index, and the page size: `defaultPageSize` when not given, capped at `maxPageSize`.
`ids`	Only the nodes with these ids.

query Upcoming($from: DateTime!) {
  events(filter: { starts: { gte: $from } }, orderBy: starts, pageSize: 2) {
    totalCount
    items { id title starts price venue { name } }
  }
}

{
  "data": {
    "events": {
      "totalCount": 3,
      "items": [
        { "id": "7e51b1dd-a7a1-4c99-b16b-4f373ab2573b", "title": "Concert 2",
          "starts": "2026-11-02T19:00:00.0000000Z", "price": 200, "venue": { "name": "Opera House" } },
        { "id": "1459bd5a-9b4d-48c1-8c49-288fff8d5a2e", "title": "Concert 3",
          "starts": "2026-11-03T19:00:00.0000000Z", "price": 300, "venue": { "name": "Opera House" } }
      ]
    }
  },
  "extensions": { "durationMs": 46.223 }
}

Filters. A filter has one entry per field, each holding operators. Several operators on one field must all match, so { price: { gte: 100, lt: 300 } } is a range. Write enum values by name:

{
  cheapOrSoldOut: events(filter: { or: [ { price: { lt: 150 } }, { status: { eq: SoldOut } } ] }) { totalCount }
  notAtTheOpera:  events(filter: { not: { venue: { eq: "0b6e…" } } }) { totalCount }
  some:           events(filter: { status: { in: [Published, SoldOut] } }) { totalCount }
}

Relations and references are filtered by the related node's id only, with eq or in ({ venue: { id: { eq: "0b6e…" } } } works too). To filter on a venue's name, get the venue ids from a venues query first.
On a "many" relation, the condition matches when one of the related nodes has that id.
Strings match by equality only. Use search to match text.

Following relations. A relation field returns the related nodes, loaded with the root field's query. A "many" field returns all of them unless top limits them:

{
  venues {
    items {
      name
      events(top: 3) { title starts }
    }
  }
}

Nested lists cannot be filtered or ordered. Start from the other side instead, for example events(filter: { venue: { eq: $venue } }, orderBy: starts).

Files. A file property gives a FileInfo: name, size, contentType, width, height, and the url that db.GetUrl(file) gives (§18.1). Give url a width, height, crop (Fill, Fit, Stretch, Auto), format (Jpeg, Png, Webp, Avif, Gif) or quality, and it points to an image made from the file, or from a frame of a video. The image is made when the URL is first requested. Aliases ask for several sizes. If Venue had a [FileProperty] FileValue Photo:

{
  venues {
    items {
      name
      photo {
        url
        thumbnail: url(width: 320, height: 180, crop: Fill)
        large: url(width: 1600, format: Webp, quality: 80)
      }
    }
  }
}

Other files ignore the image arguments. Without format, the server picks one (Image variants adapt by default). URLs are relative unless the URL manager has a host (PrimaryBaseAddress or BaseAddressAssets). For clients on another origin, url(absolute: true) adds the scheme and host of the request. Serving the URL is the web application's job, as for any asset URL (§18).

The rest of GraphQL works as the specification says: variables with defaults, aliases, fragments, @include and @skip, __typename, several root fields in one request, and several operations in one document with operationName. Subscriptions are not supported.

Errors. A request that cannot run at all gets errors and no data. That happens for a syntax error, an unknown field, a wrong variable, or a depth limit:

{ "errors": [ { "message": "Field \"nope\" is not defined on type \"Event\".", "locations": [ { "line": 1, "column": 20 } ] } ] }

A root field that fails while running, such as one given a malformed id or a rejected mutation, becomes null with an error that carries its path. The other root fields still answer.