Перейти к основному содержимому

Пагинация

Узлы и грани

Для пагинации результатов запросы должны отправляться через поле пути edges.

При получении больших объёмов данных может стать проблемой их отображение в удобном для пользователя виде. GraphQL API предоставляет гибкие возможности постраничного вывода данных, для чего используется целый ряд полей и аргументов.

Курсор​

Для удобства определения объектов в возвращаемом ответе каждому объекту присваивется собственный идентификатор, именуемый курсором. Чтобы получить этот идентификатор, в тело операции нужно добавить поле cursor:

Пример запроса
{
  instruments {
    edges {
      cursor
      node {
        basicInformation {
            ...
        }
      }
    }
  }
}

В ответ система вернёт для cursor идентификатор выбранного объекта в базе данных системы:

Пример ответа
{
  "data": {
    "instruments": {
      "edges": [
        {
          "cursor": "MA==",
          "node": {
            "basicInformation": {
              ...
            }
          }
        },
      ]
    }
  }
}

Курсор как отправная точка​

Полученный курсор можно использовать как отправную точку для формирования страницы результатов. Для этого используются аргументы корневого поля пути, в качестве значения которых указывается полученный cursor:

  • before — объекты, идущие в списке перед указанным курсором
  • after — объекты, следующие в списке после указанного курсора
Указание количества

Без указания количества возвращаемых объектов с помощью аргументов first или last система вернёт только ближайшие 10 записей.

Пример запроса
{
  instruments(first: 10, after: "MA==") {
    edges {
      cursor
      node {
        basicInformation {
          ...
        }
      }
    }
  }
}
предупреждение

Указанный в before/after курсор не входит в выборку на отображаемой странице.

Постраничная навигация​

Для последовательной навигации по страницам используются данные типа PageInfo:

  • hasNextPage — существует ли в заданных условиях следующая страница (формат данных Boolean)
  • hasPreviousPage — существует ли в заданных условиях предыдущая страница (формат данных Boolean)
  • startCursor — первый курсор на отображаемой странице (формат данных String)
  • endCursor — последний курсор на отображаемой странице (формат данных String)

Поле PageInfo структурно подчиняется напрямую корневому полю операции, в связи с чем должно располагаться на одном уровне с edges, а не внутри него:

Пример запроса
{
  instruments(first: 5, after: "MjQ=") {
    edges {
      cursor
      node {
        basicInformation {
          ...
        }
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}
Пример ответа
{
  "data": {
    "instruments": {
      "edges": [
        {
          "cursor": "MjU=",
          "node": {
            "basicInformation": {
              ...
            }
          }
        },
        {
          "cursor": "MjY=",
          "node": {
            "basicInformation": {
              ...
            }
          }
        },
        {
          "cursor": "Mjc=",
          "node": {
            "basicInformation": {
              ...
            }
          }
        },
        {
          "cursor": "Mjg=",
          "node": {
            "basicInformation": {
              ...
            }
          }
        },
        {
          "cursor": "Mjk=",
          "node": {
            "basicInformation": {
              ...
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": true,
        "startCursor": "MjU=",
        "endCursor": "Mjk="
      }
    }
  }
}

Общее количество объектов​

Определить суммарное количество записей в базе данных системы позволяет totalCount, располагающийся на одном уровне с edge и pageInfo:

Пример запроса
{
  instruments(first: 5, after: "MjQ=") {
    edges {
      cursor
      node {
        basicInformation {
          ...
        }
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}
Пример ответа
{
  "data": {
    "instruments": {
      "edges": [
        ...
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": true,
        "startCursor": "MjU=",
        "endCursor": "Mjk="
      },
      "totalCount": 41357
    }
  }
}

Таким образом, полученный в ответе startCursor/endCursor можно использовать как новое значение аргумента before/after, значение hasNextPage/hasPreviousPage позволяет определить, возможно ли движение в заданном направлении, а общее количество объектов из totalCount позволяет создать список страниц для более удобной навигации.

Что дальше?​