QuerySet API - Django

No Django, o QuerySet é o núcleo do trabalho com modelos e bancos de dados. Ele representa uma coleção de consultas que podem ser executadas no banco e fornece métodos para criar e modificar essas consultas. O Django traduz as chamadas desses métodos em instruções SQL equivalentes, facilitando a interação com o banco de dados de forma intuitiva.

Principais Métodos de QuerySet

Entre os métodos mais utilizados para consultar e manipular dados, destacam-se:

• filter(): Retorna um QuerySet contendo os objetos que atendem aos critérios especificados.

• exclude(): Retorna um QuerySet contendo os objetos que não atendem aos critérios especificados.

• order_by(): Ordena o conjunto de dados com base nos campos definidos.

• distinct(): Garante que o QuerySet retornado contenha apenas objetos únicos.

• values(): Retorna os dados dos objetos no formato de dicionário.

• values_list(): Retorna os dados dos objetos no formato de lista.

• none(): Cria um QuerySet vazio sem resultados.

• all(): Retorna todos os objetos da tabela no formato de QuerySet.

• get(): Recupera um único objeto que atende aos critérios especificados, lançando uma exceção se nenhum ou mais de um objeto for encontrado.

• create(): Cria e salva um novo objeto no banco de dados.

• get_or_create(): Retorna um objeto existente que atende aos critérios ou cria um novo, caso ele não exista.

• update_or_create(): Atualiza um objeto existente ou cria um novo, caso ele não seja encontrado.

• bulk_create(): Cria vários objetos de uma única vez.

• bulk_update(): Atualiza múltiplos objetos simultaneamente.

• aggregate(): Executa funções de agregação, como soma, média, mínimo e máximo, retornando os resultados como valores individuais.

• exists(): Verifica se o QuerySet contém ao menos um objeto, retornando True ou False.

• update(): Atualiza os campos de objetos no banco de dados.

• delete(): Remove objetos do banco de dados.

Executando Métodos no Banco de Dados

Os métodos de QuerySet são avaliados de forma preguiçosa (lazy), ou seja, não executam consultas no banco de dados imediatamente. Eles criam uma consulta que só será avaliada quando o resultado for explicitamente solicitado. Isso ocorre, por exemplo, ao iterar sobre o QuerySet ou ao acessá-lo diretamente.

Exemplo Prático

Considere o seguinte modelo definido em models.py:

from django.db import models
 
class Person(models.Model):
    name = models.CharField(max_length=20)
    age = models.IntegerField()

No arquivo views.py, o seguinte código demonstra o comportamento de QuerySets:

from .models import Person

# Obtém todos os objetos
people = Person.objects.all()
print(people.query)

# Filtra os objetos com o nome "Tom"
people = people.filter(name="Tom")
print(people.query)

# Filtra os objetos com idade igual a 31
people = people.filter(age=31)
print(people.query)

# Executa a consulta ao iterar no QuerySet
for person in people:
    print(f"{person.id}.{person.name} - {person.age}")

Inicialmente, a consulta Person.objects.all() retorna um QuerySet contendo todos os objetos da tabela associada ao modelo Person. A propriedade query permite visualizar a consulta SQL gerada pelo Django:

print(people.query)

Critérios adicionais podem ser aplicados ao QuerySet com métodos como filter(), que filtra os objetos com base nos critérios especificados. Por exemplo, o comando:

people = people.filter(name="Tom")

gera um novo QuerySet contendo apenas os objetos cujo campo name seja igual a "Tom". De forma semelhante, outros critérios podem ser adicionados, como no exemplo:

people = people.filter(age=31)

Mesmo após aplicar vários métodos consecutivos, o Django não realiza consultas ao banco até que o QuerySet seja avaliado diretamente, como ao iterar sobre ele:

for person in people:
    print(f"{person.id}.{person.name} - {person.age}")

Neste momento, o SQL final é gerado e executado, recuperando os resultados diretamente do banco de dados.