Filtrando dados no GraphQL (filter)

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

Visão rápida

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 é 'Dune', a bandeira disponível é verdadeira, o preço é 20, a data de publicação é 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 em que o título não 'Foundation'é, a bandeira disponível não é falsa, o preço não é zero, a data de publicação 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 após 'A', a bandeira disponível é verdadeira, o preço é maior que 10 e a data de publicação é posterior a 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. Devolve registos em que o valor de um campo é superior ou igual ao literal fornecido.

Neste exemplo, estamos recebendo livros cujo título é 'A' ou posterior, a bandeira disponível é verdadeira, o preço é pelo menos 10 e a data de publicação é 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

Menos que. Devolve registos em que o valor de um campo é estritamente inferior ao literal fornecido.

Neste exemplo, estamos recebendo livros cujo título classifica antes 'Z', a bandeira disponível é falsa, o preço é inferior a 50 e a data de publicação é anterior a 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. Devolve registos em que o valor de um campo é inferior ou igual ao literal fornecido.

Neste exemplo, estamos recebendo livros cujo título classifica antes ou igual a 'Z', a bandeira disponível é verdadeira, o preço é 100 ou menos e a data de publicação é 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

Lógica E. Combina vários predicados que devem ser 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 de estoque ou com preços 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 substring. Retorna registros em que o campo contém a substring fornecida (a diferenciação de maiúsculas e minúsculas depende do agrupamento do banco de dados).

Neste exemplo, temos 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 substring 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, temos 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 sufixos. Retorna registros em que o campo termina com a cadeia de caracteres fornecida.

Neste exemplo, temos livros cujo título termina com "Crônicas".

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

SQL conceitual

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

in

Correspondência de membros. Retorna registros onde o valor do campo existe na lista fornecida.

Neste exemplo, temos livros cujo gênero é "SciFi" ou "Fantasy".

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 booleano.

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