Paginação e Cursores

O tipo de paginação adotada para todas as informações que são retornadas em formato de listas (Ex: lista de cursos, lista de pessoas, etc) é a paginação baseada em cursores. Neste tipo de paginação, cada item da lista vem acompanhando de uma informação denominada cursor, que o identifica unicamente na lista. O tamanho da página é fixo (Ex: de 20 em 20 registros). Para navegar para uma próxima página você deverá especificar a partir de qual registro deseja navegar, através de seu cursor, e em qual sentido: para frente ou para trás.

Foi definido um tipo denominado PaginationLimit, esse tipo aceita valores inteiros no intervalo de 1 a 100. Esse tipo é adotado em todas as paginações, ou seja, o número máximo de registros que pode ser retornado em um lista será até 100 registros.

Vamos listar os 3 primeiros cursos de Graduação modalidade Presencial da Instituição. Note que para os exemplos de paginação que adotaremos a consulta não será alterada, vamos variar apenas o preenchimento das variáveis

Query graphql

query cursosGraduacao(
  $first: PaginationLimit, $after: String, 
  $last: PaginationLimit, $before: String,
  $tipoCurso: TIPO_CURSO,
  $modalidade: MODALIDADE_CURSO
) {
  ensinoCursos(
    pagination:{ 
      first: $first, after: $after, 
      last: $last, before: $before
    } 
    tipoCurso: $tipoCurso, 
    modalidade: $modalidade
  ){
    edges {
      cursor
      node {
        curso
        nome
      }
    }
  }
}

Variáveis

{
  "first": 3,
  "tipoCurso": "GRADUACAO",
  "modalidade": "PRESENCIAL"
}

HTTP Headers

{
  "Application": "Bearer <token-da-aplicaca>"
}

O campo cursor é um índice para o registro específico,o campo node trás um registro de curso, o vetor de resultados recuperados ficam contido dentro do vetor edges.

Retorno

{
  "data": {
    "ensinoCursos": {
      "edges": [
        {
          "cursor": "WyJBRE1JTklTVFJBw4fDg08iLCJBRE0iXQ==",
          "node": {
            "curso": "ADM",
            "nome": "ADMINISTRAÇÃO"
          }
        },
        {
          "cursor": "WyJBR1JPTk9NSUEiLCJBR1IiXQ==",
          "node": {
            "curso": "AGR",
            "nome": "AGRONOMIA"
          }
        },
        {
          "cursor": "WyJBR1JPTk9NSUEiLCJBR1JVTkFJIl0=",
          "node": {
            "curso": "AGRUNAI",
            "nome": "AGRONOMIA"
          }
        }
      ]
    }
  }
}

Paginação para frente

Para buscar os próximos 3 registros, vamos utilizar o cursor do 3º registro, o curso com o código AGRUNAI, valor WyJBR1JPTk9NSUEiLCJBR1JVTkFJIl0=. Iremos adicionar a variável after com o valor do cursor de onde partiremos para os próximos 3 registros.

Variáveis

{
  "first": 3,
  "after": "WyJBR1JPTk9NSUEiLCJBR1JVTkFJIl0=",
  "tipoCurso": "GRADUACAO",
  "modalidade": "PRESENCIAL"
}

Retorno

{
  "data": {
    "ensinoCursos": {
      "edges": [
        {
          "cursor": "WyJDYWxvdXJvcyIsIkNEQVJBIl0=",
          "node": {
            "curso": "CDARA",
            "nome": "Calouros"
          }
        },
        {
          "cursor": "WyJDScOKTkNJQSBFIFRFQ05PTE9HSUEiLCJCQ1QiXQ==",
          "node": {
            "curso": "BCT",
            "nome": "CIÊNCIA E TECNOLOGIA"
          }
        },
        {
          "cursor": "WyJDScOKTkNJQSBFIFRFQ05PTE9HSUEiLCJCQ1QtSkFOIl0=",
          "node": {
            "curso": "BCT-JAN",
            "nome": "CIÊNCIA E TECNOLOGIA"
          }
        }
      ]
    }
  }
}

Paginação para trás

Para realizar uma paginação para trás, vamos partir do último registro, curso BCT-JAN, copiando seu cursor, valor WyJDScOKTkNJQSBFIFRFQ05PTE9HSUEiLCJCQ1QtSkFOIl0=. Vamos pedir 4 registros para trás a partir dele. Para navegar para trás, utilizaremos agora os parâmetros para paginação last (número de registros) e before (a partir de qual registro).

Variáveis

{
  "last": 4,
  "before": "WyJDScOKTkNJQSBFIFRFQ05PTE9HSUEiLCJCQ1QtSkFOIl0=",
  "tipoCurso": "GRADUACAO",
  "modalidade": "PRESENCIAL"
}

Retorno

{
  "data": {
    "ensinoCursos": {
      "edges": [
        {
          "cursor": "WyJBR1JPTk9NSUEiLCJBR1IiXQ==",
          "node": {
            "curso": "AGR",
            "nome": "AGRONOMIA"
          }
        },
        {
          "cursor": "WyJBR1JPTk9NSUEiLCJBR1JVTkFJIl0=",
          "node": {
            "curso": "AGRUNAI",
            "nome": "AGRONOMIA"
          }
        },
        {
          "cursor": "WyJDYWxvdXJvcyIsIkNEQVJBIl0=",
          "node": {
            "curso": "CDARA",
            "nome": "Calouros"
          }
        },
        {
          "cursor": "WyJDScOKTkNJQSBFIFRFQ05PTE9HSUEiLCJCQ1QiXQ==",
          "node": {
            "curso": "BCT",
            "nome": "CIÊNCIA E TECNOLOGIA"
          }
        }
      ]
    }
  }
}

Informações de paginação

Vamos alterar nossa consulta para adicionar informações de paginação, adicionando o objeto pageInfo e suas propriedades.

Query

query cursosGraduacao(
  $first: PaginationLimit, $after: String, 
  $last: PaginationLimit, $before: String,
  $tipoCurso: TIPO_CURSO,
  $modalidade: MODALIDADE_CURSO
) {
  ensinoCursos(
    pagination:{ 
      first: $first, after: $after, 
      last: $last, before: $before
    } 
    tipoCurso: $tipoCurso, 
    modalidade: $modalidade
  ){
    edges {
      cursor
      node {
        curso
        nome
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Variáveis

{
  "first": 3,
  "tipoCurso": "GRADUACAO",
  "modalidade": "PRESENCIAL"
}

Retorno

{
  "data": {
    "ensinoCursos": {
      "edges": [
        {
          "cursor": "WyJBRE1JTklTVFJBw4fDg08iLCJBRE0iXQ==",
          "node": {
            "curso": "ADM",
            "nome": "ADMINISTRAÇÃO"
          }
        },
        {
          "cursor": "WyJBR1JPTk9NSUEiLCJBR1IiXQ==",
          "node": {
            "curso": "AGR",
            "nome": "AGRONOMIA"
          }
        },
        {
          "cursor": "WyJBR1JPTk9NSUEiLCJBR1JVTkFJIl0=",
          "node": {
            "curso": "AGRUNAI",
            "nome": "AGRONOMIA"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "WyJBRE1JTklTVFJBw4fDg08iLCJBRE0iXQ==",
        "endCursor": "WyJBR1JPTk9NSUEiLCJBR1JVTkFJIl0="
      }
    }
  }
}

Informações retornadas pelo pageInfo que ajudarão na navegação pela paginação:

• hasNextPage: existem registros para frente na paginação
• hasPreviousPage: existem registros pra trás
• startCursor: cursor do primeiro registro
• endCursor: cursor do último registr

Material complementar

• Artigo Entendendo paginação: REST, GraphQL e Relay
• Site Oficial do Javascript Framework Relay

Voltar para Documentação - GraphQL Playground