Aplicando Filtros no Django

O Django oferece uma ampla gama de ferramentas para aplicar filtros em QuerySets, permitindo a seleção de objetos com base em critérios específicos. Os métodos mais comuns para essa finalidade são get(), filter() e exclude(). Esses métodos recebem como parâmetro uma condição que define o critério do filtro.

Considere o modelo Person como base para os exemplos:

from django.db import models

class Person(models.Model):
    name = models.CharField(max_length=20)
    age = models.IntegerField()

get()

O método get() retorna um único objeto que atende ao critério especificado:

tom = Person.objects.get(name="Tom")
print(f"{tom.name} - {tom.age}")

Se nenhum objeto atender ao critério, será lançada a exceção DoesNotExist. Se mais de um objeto corresponder, será lançada a exceção MultipleObjectsReturned.

filter()

O método filter() retorna um QuerySet com todos os objetos que atendem ao critério:

people_by_age = Person.objects.filter(age=32)
for person in people_by_age:
    print(f"{person.name} - {person.age}")

exclude()

O método exclude() retorna um QuerySet com objetos que não atendem ao critério:

people_by_age = Person.objects.exclude(age=32)
for person in people_by_age:
    print(f"{person.name} - {person.age}")

Lookups

Além de filtros básicos, o Django permite condições mais avançadas usando Lookups, que são definidos após o nome do campo, separados por dois sublinhados (__).

exact e iexact

O lookup exact filtra objetos cujo campo corresponde exatamente ao valor fornecido. Sua versão iexact ignora diferenças entre maiúsculas e minúsculas:

tom = Person.objects.get(name__exact="Tom")
people = Person.objects.filter(name__iexact="tom")

O lookup contains filtra objetos cujos campos contêm uma substring específica, enquanto icontains ignora diferenças entre maiúsculas e minúsculas:

people = Person.objects.filter(name__contains="o")
people = Person.objects.filter(name__icontains="T")

contains e icontains

O lookup contains filtra objetos cujos campos contêm uma substring específica, enquanto icontains ignora diferenças entre maiúsculas e minúsculas:

people = Person.objects.filter(name__contains="o")
people = Person.objects.filter(name__icontains="T")

gt, gte, lte, lt

Lookups como gt (maior que), gte (maior ou igual), lt (menor que) e lte (menor ou igual) permitem filtrar objetos com base em valores numéricos:

people = Person.objects.filter(age__lte=32)
people = Person.objects.filter(age__gt=40)

range

O lookup range filtra objetos com valores dentro de um intervalo:

people = Person.objects.filter(age__range=(28, 38))

in

O lookup in retorna objetos cujos campos correspondem a um conjunto de valores:

# Retorna pessoas com 28, 32 ou 38 anos
people = Person.objects.filter(age__in=[28, 32, 38])

isnull

O lookup isnull filtra objetos com campos nulos ou não nulos, dependendo do valor fornecido:

people = Person.objects.filter(name__isnull=True)
people = Person.objects.filter(age__isnull=False)

startswith e istartswith

O lookup startswith filtra objetos cujos campos começam com uma substring específica, enquanto istartswith ignora diferenças entre maiúsculas e minúsculas:

people = Person.objects.filter(name__startswith="T")
people = Person.objects.filter(name__istartswith="t")

regex e iregex

O lookup regex filtra objetos com base em expressões regulares, enquanto iregex ignora diferenças entre maiúsculas e minúsculas:

people = Person.objects.filter(name__regex=r"(am|om)$")

Filtros de Data

Filtros para campos de data e hora incluem lookups como year, month, day, hour, entre outros. Considere o modelo Order com um campo de data e hora:

from django.db import models

class Order(models.Model):
    datetime = models.DateTimeField()

Exemplo de filtro por mês:

from datetime import datetime

orders = Order.objects.filter(datetime__month=5)
for order in orders:
    print(order.datetime)

Filtros mais complexos também podem ser combinados, como datetime__month__gt=5, para retornar objetos após o quinto mês.

Operadores Lógicos

Os operadores lógicos permitem combinar filtros. Os principais são:

AND (&): Retorna objetos que atendem a ambos os critérios.
OR (|): Retorna objetos que atendem a pelo menos um dos critérios.
XOR (^): Retorna objetos que atendem a apenas um dos critérios, mas não ambos.

Exemplo com AND:

people = Person.objects.filter(name="Tom") & Person.objects.filter(age=22)

No nível do banco de dados, isso corresponde a:

SELECT * FROM person WHERE name = 'Tom' AND age = 22;

Exemplo com OR:

people = Person.objects.filter(name="Tom") | Person.objects.filter(age=22)

E com XOR:

people = Person.objects.filter(name="Tom") ^ Person.objects.filter(age=22)

Documentação oficial:

Making queries