Read array items

Choose a query

Requirement	Query
Traverse all items	listArrayItems
Read a known subset	lookupArrayItems
Read one item by returned service-generated ID	getArrayItem

Traverse an array with listArrayItems

listArrayItems uses forward-only cursor pagination.

Example: Read the first page of favorites

query ListFavorites($input: ListArrayItemsInput!) {
  listArrayItems(input: $input) {
    totalCount
    sort
    sortDirection
    data {
      key
      value
      id
      itemId
      sortString
      sortNumber
      sortDate
      dateModified
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

{
  "input": {
    "scope": "USER",
    "key": "content:favorites",
    "first": 20,
    "sort": "sortDate",
    "sortDirection": "desc"
  }
}

{
  "data": {
    "listArrayItems": {
      "totalCount": 2,
      "sort": "sortDate",
      "sortDirection": "desc",
      "data": [
        {
          "key": "content:favorites",
          "value": {
            "title": "Example Movie",
            "mediaType": "MOVIE"
          },
          "id": "66b100000000000000000001",
          "itemId": "movie:100",
          "sortString": "Example Movie",
          "sortNumber": 100,
          "sortDate": "2026-09-18T10:30:00.000Z",
          "dateModified": "2026-09-18T10:31:12.000Z"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "<opaque cursor returned by the service>"
      }
    }
  }
}

Response semantics

• Default first: 20.
• Default sort: id.
• Default direction: asc.
• totalCount describes the complete array and is not snapshot-consistent with the returned page.
• Separate cursor requests do not share a snapshot.

Find selected items with lookupArrayItems

lookupArrayItems accepts ids and itemIds. The lists form a union.

Example: Find favorites by itemId

query LookupFavorites($input: LookupArrayItemsInput!) {
  lookupArrayItems(input: $input) {
    totalCount
    data {
      key
      value
      id
      itemId
      sortString
      sortNumber
      sortDate
      dateModified
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

{
  "input": {
    "scope": "USER",
    "key": "content:favorites",
    "itemIds": ["movie:100", "movie:200"],
    "sort": "sortString",
    "sortDirection": "asc"
  }
}

{
  "data": {
    "lookupArrayItems": {
      "totalCount": 2,
      "data": [
        {
          "key": "content:favorites",
          "value": {
            "title": "Another Movie",
            "mediaType": "MOVIE"
          },
          "id": "66b100000000000000000002",
          "itemId": "movie:200",
          "sortString": "Another Movie",
          "sortNumber": 200,
          "sortDate": null,
          "dateModified": "2026-09-18T10:31:12.000Z"
        },
        {
          "key": "content:favorites",
          "value": {
            "title": "Example Movie",
            "mediaType": "MOVIE"
          },
          "id": "66b100000000000000000001",
          "itemId": "movie:100",
          "sortString": "Example Movie",
          "sortNumber": 100,
          "sortDate": "2026-09-18T10:30:00.000Z",
          "dateModified": "2026-09-18T10:31:12.000Z"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "<opaque cursor returned by the service>"
      }
    }
  }
}

Example: Combine itemId and service-generated ID selectors

{
  "input": {
    "scope": "USER",
    "key": "content:favorites",
    "itemIds": ["movie:100"],
    "ids": ["66b100000000000000000001"]
  }
}

The selectors form a union. A document matching both selector types is returned once.

Found-only results

Unknown selectors are omitted. Results are sorted according to the request, not aligned positionally to selector order. Associate each result using id or itemId.

Legacy duplicates

Qualifying legacy duplicates are returned as separate rows. Each row contributes to totalCount; lookupArrayItems does not modify or backfill them.

Read one item with getArrayItem

getArrayItem is supported and is not deprecated. It reads one item using a service-generated ID previously returned by the service.

Example: Read by service-generated ID

query GetFavorite($input: GetArrayItemInput!) {
  getArrayItem(input: $input) {
    key
    value
    id
    itemId
    sortString
    sortNumber
    sortDate
    dateModified
  }
}

{
  "input": {
    "scope": "USER",
    "key": "content:favorites",
    "id": "66b100000000000000000001"
  }
}

A missing item produces a GraphQL error. There is no stable operation-specific extensions.reason for this case; do not parse the human-readable message.

Array item response fields

Field	Meaning
key	Array key
value	Stored JSON value
id	Service-generated item ID
itemId	Stored or qualifying legacy identity; may be null
sortString	Optional customer-provided string sort value
sortNumber	Optional customer-provided numeric sort value
sortDate	Optional customer-provided date sort value
dateModified	Service-owned last-write timestamp

See Cursor pagination and sorting.