Filtrando dados em REST ($filter)

A filtragem restringe grandes conjuntos de dados apenas aos registros necessários. No REST, o Data API builder (DAB) oferece suporte a um parâmetro de consulta inspirado em $filter OData. 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 null.

Neste exemplo, estamos recebendo livros em que o título é igual '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.

GET /api/books?$filter=
  title eq 'Dune' and
  available eq true and
  price eq 20 and
  published_on eq 2024-01-01T00:00:00Z and
  rating eq null

SQL conceitual

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

ne

Não é igual a. Retorna registros em que o valor de um campo não corresponde ao literal fornecido ou não é nulo.

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.

GET /api/books?$filter=
  title ne 'Foundation' and
  available ne false and
  price ne 0 and
  published_on ne 2023-12-31T00:00:00Z and
  rating ne null

SQL conceitual

SELECT * FROM Books
WHERE title <> 'Foundation'
  AND available <> 0
  AND price <> 0
  AND published_on <> '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.

GET /api/books?$filter=
  title gt 'A' and
  available gt false and
  price gt 10 and
  published_on gt 2020-01-01T00:00:00Z

SQL conceitual

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

ge

Maior ou igual. 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.

GET /api/books?$filter=
  title ge 'A' and
  available ge false and
  price ge 10 and
  published_on ge 2020-01-01T00:00:00Z

SQL conceitual

SELECT * FROM Books
WHERE title >= 'A'
  AND available >= 0
  AND price >= 10
  AND published_on >= '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.

GET /api/books?$filter=
  title lt 'Z' and
  available lt true and
  price lt 50 and
  published_on lt 2030-01-01T00:00:00Z

SQL conceitual

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

le

Menor ou igual. 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.

GET /api/books?$filter=
  title le 'Z' and
  available le true and
  price le 100 and
  published_on le 2030-01-01T00:00:00Z

SQL conceitual

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

and

Lógica E. Combina várias condições que devem ser verdadeiras para que um registro corresponda.

Neste exemplo, estamos recebendo livros onde o título é 'Dune', a bandeira disponível é verdadeira, o preço é inferior a 50, a data de publicação é posterior a 1º de janeiro de 2020 e a classificação é nula.

GET /api/books?$filter=
  title eq 'Dune' and
  available eq true and
  price lt 50 and
  published_on ge 2020-01-01T00:00:00Z and
  rating eq null

SQL conceitual

SELECT * FROM Books
WHERE title = 'Dune'
  AND available = 1
  AND price < 50
  AND published_on >= '2020-01-01T00:00:00Z'
  AND rating IS NULL;

or

OR lógico. Combina condições em que pelo menos uma deve ser verdadeira para que um registro corresponda.

Neste exemplo, estamos recebendo livros em que o título é 'Dune', ou a bandeira disponível é verdadeira, ou o preço é maior que 20, ou a data de publicação é anterior a 1º de janeiro de 2025, ou a classificação é nula.

GET /api/books?$filter=
  title eq 'Dune' or
  available eq true or
  price gt 20 or
  published_on lt 2025-01-01T00:00:00Z or
  rating eq null

SQL conceitual

SELECT * FROM Books
WHERE title = 'Dune'
  OR available = 1
  OR price > 20
  OR published_on < '2025-01-01T00:00:00Z'
  OR rating IS NULL;

not

Lógico NÃO. Nega uma condição para que os registros sejam retornados somente se a condição for falsa.

Neste exemplo, estamos recebendo todos os livros que não têm o título 'Romance', não estão indisponíveis, não custam menos de US $ 10, não foram publicados antes de 1º de janeiro de 2020 e não têm uma classificação nula.

GET /api/books?$filter=
  not (
    title eq 'Romance' and
    available eq false and
    price lt 10 and
    published_on lt 2020-01-01T00:00:00Z and
    rating eq null
  )

SQL conceitual

SELECT * FROM Books
WHERE NOT (
  title = 'Romance'
  AND available = 0
  AND price < 10
  AND published_on < '2020-01-01T00:00:00Z'
  AND rating IS NULL
);

( ) agrupamento

Agrupa subexpressões para que você possa controlar a ordem de avaliação em filtros complexos.

Neste exemplo, estamos recebendo livros em que o título é ou 'Fiction''SciFi', e o livro está disponível ou tem preço abaixo de US$ 25, e a data de publicação é posterior a 1º de janeiro de 2020 e a classificação é nula.

GET /api/books?$filter=
  (title eq 'Fiction' or title eq 'SciFi') and
  (available eq true or price lt 25) and
  published_on ge 2020-01-01T00:00:00Z and
  rating eq null

SQL conceitual

SELECT * FROM Books
WHERE (title = 'Fiction' OR title = 'SciFi')
  AND (available = 1 OR price < 25)
  AND published_on >= '2020-01-01T00:00:00Z'
  AND 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