Documents

A query Documents retorna os documents de uma entidade, paginados por cursor, com no máximo 50 itens por página.

A paginação segue o padrão de conexões do Storefront API: os cursores (after/before) são a hash do document e a ordenação é crescente pelo identificador do document, ou seja, na ordem em que os documents foram criados.

Parâmetros

Argumento	Tipo	Obrigatório	Descrição
entityName	String	Sim	Nome da entidade. Não diferencia maiúsculas de minúsculas
first	Int	Sim*	Quantidade de itens a retornar, a partir do início da página. Máximo de 50
last	Int	Sim*	Quantidade de itens a retornar, a partir do fim da página. Máximo de 50. Exige `before`
after	String	Não	Cursor de avanço: retorna os documents posteriores ao cursor informado
before	String	Não	Cursor de retorno: retorna os documents anteriores ao cursor informado
fields	[String]	Não	Campos a incluir no `data`. Quando omitido, retorna todos os campos públicos do document

*Informe first ou last — um dos dois é obrigatório.

❗️
Combinações inválidas de paginação

first e last juntos;

after e before juntos;

last sem before;

first com before;

last com after;

nem first nem last.

📘
Sobre o argumento fields
Os campos pedidos que não existirem no document — ou que não forem públicos — são retornados como null, e não omitidos. Quando fields é omitido, todos os itens da página são normalizados com o mesmo conjunto de campos, preenchendo com null os que faltarem em cada document.

Campos de retorno

Campo	Tipo	Descrição
edges	[DocumentValueNodeEdge]	Itens da página, cada um com o `cursor` e o `node`
edges.cursor	String	Cursor do item, igual ao `id` do document
edges.node.id	String	Identificador do document, em hash
edges.node.data	Any	O document em JSON, com os campos públicos projetados
nodes	[DocumentValueNode]	Atalho para os nós da página, sem os cursores
pageInfo.hasNextPage	Boolean	Indica se existem documents após a página atual
pageInfo.hasPreviousPage	Boolean	Indica se existem documents antes da página atual
pageInfo.startCursor	String	Cursor do primeiro item da página. `null` quando a página é vazia
pageInfo.endCursor	String	Cursor do último item da página. `null` quando a página é vazia

Exemplo

query {
  documents(entityName: "ficha-tecnica", first: 2) {
    edges {
      cursor
      node {
        id
        data
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Mostrar resposta

{
  "data": {
    "documents": {
      "edges": [
        {
          "cursor": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9",
          "node": {
            "id": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9",
            "data": {
              "sku": "ABC-123",
              "cor": "Azul"
            }
          }
        },
        {
          "cursor": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDJ9",
          "node": {
            "id": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDJ9",
            "data": {
              "sku": "DEF-456",
              "cor": "Preto"
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9",
        "endCursor": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDJ9"
      }
    }
  }
}

Exemplo com `after` e `fields`

Para avançar para a próxima página, envie em after o endCursor da página anterior enquanto hasNextPage for true:

query {
  documents(
    entityName: "ficha-tecnica"
    first: 2
    after: "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDJ9"
    fields: ["sku", "custo"]
  ) {
    nodes {
      id
      data
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Mostrar resposta

{
  "data": {
    "documents": {
      "nodes": [
        {
          "id": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDN9",
          "data": {
            "sku": "GHI-789",
            "custo": null
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDN9"
      }
    }
  }
}

No exemplo acima, custo retorna null porque a propriedade não é pública (publicView: false) na entidade.

Parâmetros

Combinações inválidas de paginação

Sobre o argumento fields

Campos de retorno

Exemplo

Exemplo com after e fields

Sobre o argumento `fields`

Exemplo com `after` e `fields`