Filtrando dados no GraphQL (filter)

A filtragem restringe grandes conjuntos de dados a apenas os registros necessários. No GraphQL, o DAB (Construtor de API de Dados) dá suporte a um argumento estruturado filter em consultas de entidade. Cada filtro é compilado para SQL parametrizado para segurança e consistência.

Olhar rápido

eq

Igual a. Retorna registros em que o valor de um campo corresponde exatamente ao literal fornecido ou é nulo se estiver usando isNull.

Neste exemplo, estamos recebendo livros onde o título está 'Dune', o sinalizador disponível é verdadeiro, o preço é 20, a data publicada é 1º de janeiro de 2024 e a classificação é nula.

query {
  books(filter: {
    and: [
      { title: { eq: "Dune" } }
      { available: { eq: true } }
      { price: { eq: 20 } }
      { publishedOn: { eq: "2024-01-01T00:00:00Z" } }
      { rating: { isNull: true } }
    ]
  }) {
    items { id title available price publishedOn rating }
  }
}

SQL conceitual

SELECT id, title, available, price, publishedOn, rating
FROM Books
WHERE title = 'Dune'
  AND available = 1
  AND price = 20
  AND publishedOn = '2024-01-01T00:00:00Z'
  AND rating IS NULL;

neq

Não é igual a. Retorna registros em que o valor de um campo não corresponde ao literal ou não é nulo quando combinado com isNull: false.

Neste exemplo, estamos recebendo livros onde o título não 'Foundation'está, o sinalizador disponível não é falso, o preço não é zero, a data publicada não é 31 de dezembro de 2023 e a classificação não é nula.

query {
  books(filter: {
    and: [
      { title: { neq: "Foundation" } }
      { available: { neq: false } }
      { price: { neq: 0 } }
      { publishedOn: { neq: "2023-12-31T00:00:00Z" } }
      { rating: { isNull: false } }
    ]
  }) {
    items { id title available price publishedOn rating }
  }
}

SQL conceitual

SELECT id, title, available, price, publishedOn, rating
FROM Books
WHERE title <> 'Foundation'
  AND available <> 0
  AND price <> 0
  AND publishedOn <> '2023-12-31T00:00:00Z'
  AND rating IS NOT NULL;

gt

Maior que. Retorna registros em que o valor de um campo é estritamente maior do que o literal fornecido.

Neste exemplo, estamos recebendo livros cujo título é classificado em ordem alfabética depois 'A', o sinalizador disponível é verdadeiro, o preço é maior que 10 e a data publicada é após 1º de janeiro de 2020.

query {
  books(filter: {
    and: [
      { title: { gt: "A" } }
      { available: { gt: false } }
      { price: { gt: 10 } }
      { publishedOn: { gt: "2020-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL conceitual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title > 'A'
  AND available > 0
  AND price > 10
  AND publishedOn > '2020-01-01T00:00:00Z';

gte

Maior ou igual a. Retorna registros em que o valor de um campo é maior ou igual ao literal fornecido.

Neste exemplo, estamos recebendo livros cujo título é 'A' ou posterior, o sinalizador disponível é verdadeiro, o preço é pelo menos 10 e a data publicada é em ou após 1º de janeiro de 2020.

query {
  books(filter: {
    and: [
      { title: { gte: "A" } }
      { available: { gte: false } }
      { price: { gte: 10 } }
      { publishedOn: { gte: "2020-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL conceitual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title >= 'A'
  AND available >= 0
  AND price >= 10
  AND publishedOn >= '2020-01-01T00:00:00Z';

lt

Menor que. Retorna registros em que o valor de um campo é estritamente menor do que o literal fornecido.

Neste exemplo, estamos recebendo livros cujo título classifica antes 'Z', o sinalizador disponível é falso, o preço é menor que 50 e a data publicada é antes de 1º de janeiro de 2030.

query {
  books(filter: {
    and: [
      { title: { lt: "Z" } }
      { available: { lt: true } }
      { price: { lt: 50 } }
      { publishedOn: { lt: "2030-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL conceitual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title < 'Z'
  AND available < 1
  AND price < 50
  AND publishedOn < '2030-01-01T00:00:00Z';

lte

Menor ou igual a. Retorna registros em que o valor de um campo é menor ou igual ao literal fornecido.

Neste exemplo, estamos recebendo livros cujo título classifica antes ou igual a 'Z', o sinalizador disponível é verdadeiro, o preço é 100 ou menos, e a data publicada é em ou antes de 1º de janeiro de 2030.

query {
  books(filter: {
    and: [
      { title: { lte: "Z" } }
      { available: { lte: true } }
      { price: { lte: 100 } }
      { publishedOn: { lte: "2030-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL conceitual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE title <= 'Z'
  AND available <= 1
  AND price <= 100
  AND publishedOn <= '2030-01-01T00:00:00Z';

and

AND lógico. Combina vários predicados que devem ser todos verdadeiros para que um registro corresponda.

Neste exemplo, estamos recebendo livros que estão disponíveis, custam menos de 30 e foram publicados após 1º de janeiro de 2022.

query {
  books(filter: {
    and: [
      { available: { eq: true } }
      { price: { lt: 30 } }
      { publishedOn: { gt: "2022-01-01T00:00:00Z" } }
    ]
  }) {
    items { id title available price publishedOn }
  }
}

SQL conceitual

SELECT id, title, available, price, publishedOn
FROM Books
WHERE available = 1
  AND price < 30
  AND publishedOn > '2022-01-01T00:00:00Z';

or

OR lógico. Retorna registros em que pelo menos um predicado na matriz é avaliado como true.

Neste exemplo, estamos recebendo livros que estão fora do estoque ou com preço acima de 50.

query {
  books(filter: {
    or: [
      { available: { eq: false } }
      { price: { gt: 50 } }
    ]
  }) {
    items { id title available price }
  }
}

SQL conceitual

SELECT id, title, available, price
FROM Books
WHERE available = 0
   OR price > 50;

contains

Correspondência de subcadeia de caracteres. Retorna registros em que o campo contém a subcadeia de caracteres fornecida (a confidencialidade de maiúsculas e minúsculas depende da ordenação do banco de dados).

Neste exemplo, estamos recebendo livros cujo título inclui a palavra "Duna".

query {
  books(filter: { title: { contains: "Dune" } }) {
    items { id title }
  }
}

SQL conceitual

SELECT id, title
FROM Books
WHERE title LIKE '%Dune%';

notContains

Correspondência de subcadeia de caracteres negativa. Retorna registros em que o campo não contém a subcadeia de caracteres fornecida.

Neste exemplo, estamos recebendo livros cujo título não inclui "Guia".

query {
  books(filter: { title: { notContains: "Guide" } }) {
    items { id title }
  }
}

SQL conceitual

SELECT id, title
FROM Books
WHERE title NOT LIKE '%Guide%';

startsWith

Correspondência de prefixo. Retorna registros em que o campo começa com a cadeia de caracteres fornecida.

Neste exemplo, estamos recebendo livros cujo título começa com "O".

query {
  books(filter: { title: { startsWith: "The" } }) {
    items { id title }
  }
}

SQL conceitual

SELECT id, title
FROM Books
WHERE title LIKE 'The%';

endsWith

Correspondência de sufixo. Retorna registros em que o campo termina com a cadeia de caracteres fornecida.

Neste exemplo, estamos recebendo livros cujo título termina com "Chronicles".

query {
  books(filter: { title: { endsWith: "Chronicles" } }) {
    items { id title }
  }
}

SQL conceitual

SELECT id, title
FROM Books
WHERE title LIKE '%Chronicles';

in

Correspondência de associação. Retorna registros em que o valor do campo existe na lista fornecida.

Neste exemplo, estamos recebendo livros cujo gênero é "SciFi" ou "Fantasia".

query {
  books(filter: { genre: { in: ["SciFi", "Fantasy"] } }) {
    items { id title genre }
  }
}

SQL conceitual

SELECT id, title, genre
FROM Books
WHERE genre IN ('SciFi', 'Fantasy');

isNull

Verificação nula. Retorna registros em que o valor de um campo é nulo ou não nulo, dependendo do literal booliano.

Neste exemplo, estamos recebendo livros em que a classificação é nula.

query {
  books(filter: { rating: { isNull: true } }) {
    items { id title rating }
  }
}

SQL conceitual

SELECT id, title, rating
FROM Books
WHERE rating IS NULL;

Configuração de exemplo

{
  "runtime": {
    "pagination": {
      "default-page-size": 100,
      "max-page-size": 100000
    }
  },
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      },
      "mappings": {
        "sku_title": "title",
        "sku_price": "price"
      },
      "relationships": {
        "book_category": {
          "cardinality": "one",
          "target.entity": "Category",
          "source.fields": [ "category_id" ],
          "target.fields": [ "id" ]
        }
      }
    },
    "Category": {
      "source": {
        "type": "table",
        "object": "dbo.categories"
      },
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": [ "id" ],
          "target.fields": [ "category_id" ]
        }
      }
    }
  }
}

Consulte também