DocumentsSearch

A query DocumentsSearch retorna os documents de uma entidade que satisfazem um conjunto de condições sobre o conteúdo deles, paginados por cursor.

Ela é um campo separado da query Documents porque as duas têm fontes diferentes: documents é atendida pelo banco da loja, e documentsSearch pelo índice de busca.

Parâmetros

Argumento	Tipo	Obrigatório	Descrição
entityName	String	Sim	Nome da entidade. Não diferencia maiúsculas de minúsculas
filters	[DocumentFilterInput]!	Sim	Condições sobre o conteúdo do document. Exige ao menos uma condição
first	Int	Sim	Quantidade de itens a retornar. Máximo de 50
after	String	Não	Cursor de avanço: retorna os documents posteriores ao cursor informado
fields	[String]	Não	Campos a incluir no `data`. Quando omitido, retorna todos os campos públicos do document

🚧
A busca pagina apenas para frente
documentsSearch não expõe os argumentos last e before — usá-los é erro de validação do GraphQL, antes de qualquer chamada. Para navegar nos dois sentidos sem filtrar por conteúdo, use a query Documents.

Condições de filtro

Cada item de filters identifica a propriedade alvo (field), o operador (op) e os valores exigidos pelo operador:

Operador	Valores exigidos	Tipos de propriedade aceitos
`EQ`	`value`	string, número, data ou booleano
`IN`	`values` (lista)	string
`RANGE`	ao menos um de `gte`, `gt`, `lte`, `lt`	número ou data

Quando filters traz mais de uma condição, todas precisam ser satisfeitas pelo mesmo document. Cada requisição aceita no máximo 10 condições.

🚧
Somente propriedades filtráveis e públicas são critério
Pelo Storefront API, uma propriedade só pode ser usada em field se a entidade a declarar com filterable: true e publicView: true no schema. Propriedade não filtrável, inexistente no schema, ou filtrável mas privada (publicView: false) tem a busca recusada — sem retornar documents e sem que a existência de correspondência seja observável.
A restrição existe porque filtrar por uma propriedade revela informação sobre ela mesmo sem retorná-la. Os atributos são configurados na entidade, pela API Pública.

Campos de retorno

São os mesmos da query Documents: uma conexão de DocumentValueNode, com edges, nodes e pageInfo, e o data projetado apenas nas propriedades publicView: true.

Exemplo

query {
  documentsSearch(
    entityName: "ficha-tecnica"
    filters: [
      { field: "cor", op: EQ, value: "Azul" }
      { field: "preco", op: RANGE, gte: 100, lte: 200 }
    ]
    first: 20
  ) {
    edges {
      cursor
      node {
        id
        data
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Mostrar resposta

{
  "data": {
    "documentsSearch": {
      "edges": [
        {
          "cursor": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9",
          "node": {
            "id": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9",
            "data": {
              "sku": "ABC-123",
              "cor": "Azul"
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "eyJFbnRpdHkiOiJEb2N1bWVudFZhbHVlIiwiSWQiOjQ1MDF9"
      }
    }
  }
}

Para pedir a página seguinte, envie o endCursor em after reenviando as mesmas condições.

🚧
Busca e listagem não concordam no mesmo instante
documents é imediatamente consistente: um document criado aparece nela na consulta seguinte. documentsSearch é eventualmente consistente, porque o índice é alimentado de forma assíncrona: um document recém-criado ou recém-atualizado pode demorar alguns instantes para aparecer nela ou para refletir o novo conteúdo. Isso não é erro — é a garantia de cada fonte.
Pelo mesmo motivo, uma indisponibilidade do índice afeta apenas documentsSearch: documents e document continuam respondendo normalmente, inclusive na mesma resposta GraphQL.

Códigos de erro

Além dos códigos gerais da seção — veja Document Wake - visão geral —, a recusa de uma condição inválida traz, na extensão detail do erro GraphQL, a mensagem que identifica qual condição está errada e por quê: propriedade não declarada filterable, propriedade privada, operador incompatível com o tipo declarado, range sem limite, excesso de condições ou lista de condições vazia.

📘
A indisponibilidade da busca tem código próprio, distinto do erro genérico de serviço de documents indisponível: ele informa que apenas a busca está temporariamente fora, e pode surgir somente de documentsSearch.

Parâmetros

A busca pagina apenas para frente

Condições de filtro

Somente propriedades filtráveis e públicas são critério

Campos de retorno

Exemplo

Busca e listagem não concordam no mesmo instante

Códigos de erro

A indisponibilidade da busca tem código próprio, distinto do erro genérico de serviço de documents indisponível: ele informa que apenas a busca está temporariamente fora, e pode surgir somente de documentsSearch.

A indisponibilidade da busca tem código próprio, distinto do erro genérico de serviço de documents indisponível: ele informa que apenas a busca está temporariamente fora, e pode surgir somente de `documentsSearch`.