DevelopersPortal
GraphQL API

Querying Patterns

Pagination, filtering, and sorting patterns for the Viio GraphQL API.

Last updated

The Viio GraphQL API uses cursor-based pagination and provides filtering and sorting on most collection fields.

Pagination

All collection queries use the Relay connection pattern with cursor-based pagination.

Forward Pagination

Use first to limit results and after to paginate forward:

query {
  applications(first: 10) {
    nodes {
      id
      application {
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

To fetch the next page, pass the endCursor value as after:

query {
  applications(first: 10, after: "eyJpZCI6Imxhc3RfaWQifQ==") {
    nodes {
      id
      application {
        name
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Backward Pagination

Use last and before to paginate backward from a cursor:

query {
  applications(last: 10, before: "eyJpZCI6InNvbWVfaWQifQ==") {
    nodes {
      id
      application {
        name
      }
    }
    pageInfo {
      hasPreviousPage
      startCursor
    }
  }
}

Pagination Arguments

ArgumentTypeDescription
firstIntNumber of items to return from the start of the list
afterStringReturn items after this cursor (pageInfo.endCursor)
lastIntNumber of items to return from the end of the list
beforeStringReturn items before this cursor (pageInfo.startCursor)

PageInfo Fields

FieldTypeDescription
hasNextPageBooleanWhether more items exist after this page
endCursorStringCursor of the last item in the page
hasPreviousPageBooleanWhether more items exist before this page
startCursorStringCursor of the first item in the page

Iterating Through All Pages

To fetch all results, loop until hasNextPage is false:

let allNodes = [];
let cursor = null;
let hasNextPage = true;

while (hasNextPage) {
  const { data } = await client.query({
    query: APPLICATIONS_QUERY,
    variables: { first: 50, after: cursor },
  });

  allNodes.push(...data.applications.nodes);
  hasNextPage = data.applications.pageInfo.hasNextPage;
  cursor = data.applications.pageInfo.endCursor;
}

Filtering

Use the where argument to filter results. Filters are passed as an object with field names and conditions:

query {
  applications(first: 20, where: { state: { eq: SANCTIONED } }) {
    nodes {
      id
      state
      application {
        name
      }
    }
  }
}

Filter Operators

The available operators depend on the field type. Common operators include:

Enum and scalar fields:

OperatorDescriptionExample
eqEqual to{ state: { eq: SANCTIONED } }
neqNot equal to{ state: { neq: DISCOVERED } }
inIn list{ state: { in: [SANCTIONED, IN_REVIEW] } }
ninNot in list{ state: { nin: [DISQUALIFIED, ARCHIVED] } }

String fields:

OperatorDescriptionExample
eqEqual to{ name: { eq: "Slack" } }
neqNot equal to{ name: { neq: "Slack" } }
containsContains substring{ name: { contains: "Slack" } }
ncontainsDoes not contain{ name: { ncontains: "test" } }
startsWithStarts with{ name: { startsWith: "Cloud" } }
nstartsWithDoes not start with{ name: { nstartsWith: "Test" } }
endsWithEnds with{ name: { endsWith: "Pro" } }
nendsWithDoes not end with{ name: { nendsWith: "Beta" } }
inIn list{ name: { in: ["Slack", "Zoom"] } }
ninNot in list{ name: { nin: ["Slack", "Zoom"] } }

Combining Filters

Multiple fields in the same filter object are combined with AND logic:

query {
  applications(
    first: 20
    where: {
      state: { eq: SANCTIONED }
      application: { name: { contains: "Cloud" } }
    }
  ) {
    nodes {
      id
      application {
        name
      }
    }
  }
}

You can also use explicit and / or arrays for more complex logic:

query {
  applications(
    first: 20
    where: {
      or: [
        { state: { eq: SANCTIONED } }
        { state: { eq: IN_REVIEW } }
      ]
    }
  ) {
    nodes {
      id
      state
    }
  }
}

Sorting

Use the order argument to sort results:

query {
  applications(first: 20, order: { application: { name: ASC } }) {
    nodes {
      id
      application {
        name
      }
    }
  }
}

Sorting by Multiple Fields

The order argument accepts an array, so you can sort by multiple fields. Items are sorted by the first field, with ties broken by subsequent fields:

query {
  applications(
    first: 20
    order: [
      { state: ASC }
      { application: { name: ASC } }
    ]
  ) {
    nodes {
      id
      state
      application {
        name
      }
    }
  }
}

Sort Directions

DirectionDescription
ASCAscending (A-Z, lowest first)
DESCDescending (Z-A, highest first)

API Overview

Introduction to the Viio GraphQL API — endpoint, available resources, and how to get started.

Mutation Patterns

How mutations work in the Viio GraphQL API — modifying data, input arguments, and handling responses.