---
title: "Fazendo consultas"
version: 3.0
locale: pt-br
source: https://docs.djangoproject.com/pt-br/3.0/topics/db/queries/
canonical: https://djangodocs.dev/pt-br/3.0/topics/db/queries/
---
# Fazendo consultas

Uma vez que tenha criado seu [modelos de dados](/pt-br/3.0/topics/db/models/), o Django automaticamente lhe dá uma API de abstração do banco de dados que deixa que crie, retorne, edite e delete objetos. Este documento explica como usar essa API. Refira-se a [Referência de modelo de dados](/pt-br/3.0/ref/models/) para detalhes completos de todos os vários modelos de opções de filtros.

Ao longo deste guia ( e nas referências), nos referiremos sobre os seguintes modelos, os quais compreendem uma aplicação de blog web.

```python
from django.db import models

class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def __str__(self):
        return self.name

class Author(models.Model):
    name = models.CharField(max_length=200)
    email = models.EmailField()

    def __str__(self):
        return self.name

class Entry(models.Model):
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)
    headline = models.CharField(max_length=255)
    body_text = models.TextField()
    pub_date = models.DateField()
    mod_date = models.DateField()
    authors = models.ManyToManyField(Author)
    number_of_comments = models.IntegerField()
    number_of_pingbacks = models.IntegerField()
    rating = models.IntegerField()

    def __str__(self):
        return self.headline
```

## Criando objetos

Para representar uma tabela de banco de dados em objetos Python, o Django usa um sistema intuitivo: Uma classe de modelo que representa uma tabela de banco de dados, e uma intância desta classe representa um registro particular em uma tabela de banco de dados.

Para criar um objeto, instancie-o usando argumentos nomeados para a classe de modelo, então chame o [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save) para persistí-lo no banco de dados.

Assumindo que os modelos estão em um arquivo `mysite/blog/models.py`, aqui um exemplo:

```
>>> from blog.models import Blog
>>> b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.')
>>> b.save()
```

Este executa um comando SQL `INSERT` por detrás dos panos. O Django não acessa o banco de dados até que você chame explicitamente o [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save).

O método [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save) não retorna um valor .

> **See also**
>
> O [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save) recebe várias opções avançadas não descritas aqui. Veja a documentacão em [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save) para detalhes completos.
>
> Para criar e salvar um objeto em um único passo, use o método [`create()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.create).

## Salvando alterações para objetos

Para salvar as alerações para um objeto que já existe no banco de dados, use o [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save).

Dado uma instância `b5` de `Blog` que já tenha sido salva no banco de dados, este exemplo altera seu nome e atualiza seu registro no banco de dados:

```
>>> b5.name = 'New name'
>>> b5.save()
```

Isso executa um comando SQL `UPDATE` por detras dos panos. o Django não acessa o banco de dados até que você explicitamente chame o [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save).

### Salvando campos `ForeignKey` e `ManyToManyField`

Updating a [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey) field works exactly the same
way as saving a normal field – assign an object of the right type to the field
in question. This example updates the `blog` attribute of an `Entry`
instance `entry`, assuming appropriate instances of `Entry` and `Blog`
are already saved to the database (so we can retrieve them below):

```
>>> from blog.models import Blog, Entry
>>> entry = Entry.objects.get(pk=1)
>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")
>>> entry.blog = cheese_blog
>>> entry.save()
```

Atualizar uma classe do tipo [`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField) funciona um pouco diferente – use o método [`add()`](/pt-br/3.0/ref/models/relations/#django.db.models.fields.related.RelatedManager.add) no campo para adicionar um registro para a relação. Este exemplo adiciona a instância `joe` de `Author` ao objeto `entry`:

```
>>> from blog.models import Author
>>> joe = Author.objects.create(name="Joe")
>>> entry.authors.add(joe)
```

Para adicionar múltiplos registros para um [`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField) de uma só vez, inclua múltiplos argumentos na chamada do [`add()`](/pt-br/3.0/ref/models/relations/#django.db.models.fields.related.RelatedManager.add),  como aqui:

```
>>> john = Author.objects.create(name="John")
>>> paul = Author.objects.create(name="Paul")
>>> george = Author.objects.create(name="George")
>>> ringo = Author.objects.create(name="Ringo")
>>> entry.authors.add(john, paul, george, ringo)
```

O Django irá reclamar se você tentar assinalar ou adicionar um objeto do tipo errado.

## Recuperando objetos

Para recuperar objetos do seu banco de dados, construa uma  [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) através da [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) na sua classe de modelo.

A [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) representa uma coleção de objetos do seu banco de dados. Ele pode ter zero, um ou muitos \* filtros\*. Filtros  limitam os resultados baseado nos parâmetros dados. Em termos de SQL, um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)  equivale a um comando `SELECT`, e um filtro é um clásula limitante tal como `WHERE` or `LIMIT`.

Você chega a um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) usando o [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) do modelo. Cada mdoelo tem no mínimo um [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager), e é por padrão chamado [`objects`](/pt-br/3.0/ref/models/class/#django.db.models.Model.objects). Acesse ele diretamente através da classe do modelo, como aqui:

```
>>> Blog.objects
<django.db.models.manager.Manager object at ...>
>>> b = Blog(name='Foo', tagline='Bar')
>>> b.objects
Traceback:
    ...
AttributeError: "Manager isn't accessible via Blog instances."
```

> **Note**
>
> Os `Managers` são acessíveis somente através das classes de modelo, e não de instâncias de modelos, para reforçar a separação entre operações no “nível das tabelas” e operações no “nível dos registros”.

A [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) é a principal fonte de `QuerySets` para um modelo.  Por exemplo, `Blog.objects.all()` retorna uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)  que contém todos os objetos do tipo `Blog` do banco de dados.

### Recuperando todos os objetos

A maneira mais simples de recuperar objeto de uma tabela é pegar todos eles. Para fazer isso, use o método [`all()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.all) na [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager):

```
>>> all_entries = Entry.objects.all()
```

O método [`all()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.all) retorna uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) de todos os objetos do banco de dados.

### Recuperando objetos específicos com filtros.

A [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) retornada pelo [`all()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.all) descreve todos os objetos da tabela do banco de dados. Em geral, porém, você precisa selecionar somente um subconjunto de todo o conjunto de objetos.

Para criar o subconjunto, você refina o [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) inicial, adicionando filtros de condições. As duas maneiras mais comuns de refinar um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) são:

**`filter(**kwargs)`**

  Retorna uma nova [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) contendo objetos que combinem com os parâmetros de filtros dados.

**`exclude(**kwargs)`**

  Retornam uma nova [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)  contendo objetos que *não* combinem com os parâmetros de filtros dados.

Os parâmetros de filtros (`**kwargs` nas definições da função acima) devem estar no formato descrito em [Filtros de campo](#field-lookups) abaixo.

Prr exemplo, para ter um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) de entradas de blog do ano 2006, use o [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) como aqui:

```
Entry.objects.filter(pub_date__year=2006)
```

Com a classe “manager” padrão, é o mesmo que:

```
Entry.objects.all().filter(pub_date__year=2006)
```

#### Filtros encadeados

O resultado de um refinamento de uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)  é ela mesma uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet), tal que é possível encadear refinamentos. Por exemplo:

```
>>> Entry.objects.filter(
...     headline__startswith='What'
... ).exclude(
...     pub_date__gte=datetime.date.today()
... ).filter(
...     pub_date__gte=datetime.date(2005, 1, 30)
... )
```

Ele pega o [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) inicial com todas as entradas do banco de dados, adiciona um filtro, então adiciona uma exclusão, então outro filtro. O resultado final é um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) contendo todas as entradas com uma manchete que comece com “What”, que foi publicada entre 30 de janeiro de 2005 e o dia de hoje.

#### `QuerySet`s filtradas são únicas

Cada vez que refine um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet), você tem uma nova [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) que não está de forma alguma vinculada ao anterior [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet). Cada refinamento cria uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) separada e distinta que pode ser armazenada, usada e resusada.

Exemplo

```
>>> q1 = Entry.objects.filter(headline__startswith="What")
>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())
>>> q3 = q1.filter(pub_date__gte=datetime.date.today())
```

Estes três `QuerySets` são separados. O primeiro é um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) básico contendo todas as entradas que contenham uma manchete iniciando com “What”. O segundo é um subconjunto do primeiro, com um critério adicional que exclui aqueles cujo o `pub_date` é hoje ou está no futuro. O terceiro é também um subconjunto do primeiro, com um critério adicional que seleciona somente os registros cujo o `pub_date` é hoje ou está no futuro. A [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) (`q1`) inicial não é afetado pelo processo de refinamento.

#### `QuerySet`s são “lazy”

`QuerySets` são preguiçosos (“lazy”) – o ato de criar uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) não envolve nenhuma atividade no banco de dados. Você pode epilhar filtros o dia inteiro, e o Django não irá execuar a conssulta realmente até que a [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) seja *interpretada*. Dê uma olhada neste exemplo:

```
>>> q = Entry.objects.filter(headline__startswith="What")
>>> q = q.filter(pub_date__lte=datetime.date.today())
>>> q = q.exclude(body_text__icontains="food")
>>> print(q)
```

Apesar de parece que isso seja três acessos ao banco de dados, de fato ele acessa o banco de dados somente um vez, na última linha (`print(q)`). Em geral, os resultados de uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) não são buscados no banco de dados até que você “peça” por eles. Quando fizer, a [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) é *interpretada* acessando o banco de dados. Para mais detalhes de quando exatamente a interpretação ocorre, veja [When QuerySets are evaluated](/pt-br/3.0/ref/models/querysets/#when-querysets-are-evaluated).

### Recuperando um único objeto com `get()`

O [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) sempre lhe dará um [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet), mesmo se um único objeto combina com a consulta - neste caso, ele será uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) que contém um único elemento.

Se você sabe que somente um objeto combina com sua consulta, você pode usar o método [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get) em uma [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) o qual  retorna o objeto diretamente:

```
>>> one_entry = Entry.objects.get(pk=1)
```

Você pode usar qualquer expressão de consulta com [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get), tal como com [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) \- denovo, veja o [Campos de consulta](#field-lookups) abaixo.

Note que existe uma diferença entre usar o [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get), e usar o [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) com uma fatia de `[0]`. Se não houver resultados que combinem com a consulta, o  [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get) irá emitir uma exceção `DoesNotExist`. Esta exceção é um atributo da classe de modelo na qual a consulta está sendo realizada - no código acima, se não houver objeto `Entry` com a chave-primária de 1, o Django irá emitir um `Entry.DoesNotExist`.

De maneira similar, o Django irá reclamar se mais de um item combinar com a consulta [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get). Neste caso, ele emitirá um [`MultipleObjectsReturned`](/pt-br/3.0/ref/exceptions/#django.core.exceptions.MultipleObjectsReturned), o qual denovo é ele próprio um atributo da classe de modelo.

### Outros `QuerySet` métodos

Na maioria das vezes você usará o [`all()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.all), [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get), [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) e o [`exclude()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude) quando precisar buscar objetos no banco de dados. Porém, está longe do todo que existe; veja the a [Refrêcia da API de QuerySet](/pt-br/3.0/ref/models/querysets/#queryset-api) para uma lista completa das vários métodos da [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet).

### Limitando `QuerySet`s

Use um subconjunto da syntax de fatias de array Python para limitar seu [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) para um certo número de resultados. Este é o equivalente às cláusulas SQL `Limit` e `OFFSET`.

Por exemplo, isso retorna os 5 primeiros objetos (`LIMIT 5`):

```
>>> Entry.objects.all()[:5]
```

Este retorna o sexto até o décimo objeto (`OFFSET 5 LIMIT 5`):

```
>>> Entry.objects.all()[5:10]
```

Índice negativo (isto é `Entry.objects.all()[-1]`) não é suportado.

Em geral, fatiar uma [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) retorna uma nova [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)  – isso não interpreta a query. Uma exceção é se você usar o parâmetro “step” da syntax de fatias do Python. Por exemplo, isso deve realmente executar a consulta para que retorne uma lista de cada *segundo* objeto dos primeiros 10:

```
>>> Entry.objects.all()[:10:2]
```

Further filtering or ordering of a sliced queryset is prohibited due to the
ambiguous nature of how that might work.

To retrieve a *single* object rather than a list
(e.g. `SELECT foo FROM bar LIMIT 1`), use an index instead of a slice. For
example, this returns the first `Entry` in the database, after ordering
entries alphabetically by headline:

```
>>> Entry.objects.order_by('headline')[0]
```

Isso é, de maneira rudementar,  equivalente a:

```
>>> Entry.objects.order_by('headline')[0:1].get()
```

Note, porém, que o primeiro irá emitir um `IndexError` enquanto o segundo emitirá um `DoesNotExist` se nenhum objeto combinar com o critério dado. Veja o [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get) para mais detalhes.

### Filtros de campo

Filtros de campo é o que você usa para especiíicar os parâmetros da cláusula `WHERE`. Eles são especificados como argumentos nomeados para os métodos da  [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet):  [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter), [`exclude()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude) e [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get).

Argumentos nomeados para filtros básicos estão no formato `field__lookuptype=value`. (aquilo é um “underscore” duplo). Por exemplo:

```
>>> Entry.objects.filter(pub_date__lte='2006-01-01')
```

Traduzido (groseiramente) no seguinte SQL:

```sql
SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';
```

> **Como isso é possível**
>
> Python has the ability to define functions that accept arbitrary name-value
> arguments whose names and values are evaluated at runtime. For more
> information, see [Keyword Arguments](https://docs.python.org/3/tutorial/controlflow.html#tut-keywordargs) in the official Python tutorial.

O campo especificado em um filtro tem que ser um nome de campoo do modelo. Existe uma exceção porém, no caso de uma [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey) você pode especificar o nome do campo com um sufixo `_id`. Neste caso, é esperado que o valor do parâmetro contenha literalmente o valor da chave-primária do modelo estrageiro. Por exemplo:

```
>>> Entry.objects.filter(blog_id=4)
```

Se você passar um argumento nomeado inválido, a funçao do filtro irá emitir um `TypeError`.

The database API supports about two dozen lookup types; a complete reference
can be found in the [field lookup reference](/pt-br/3.0/ref/models/querysets/#field-lookups). To give you
a taste of what’s available, here’s some of the more common lookups you’ll
probably use:

**[`exact`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-exact)**

  Combinação exata. Por exemplo:

  ```
  >>> Entry.objects.get(headline__exact="Cat bites dog")
  ```

  Geraria SQL ao longo destas linhas:

  ```sql
  SELECT ... WHERE headline = 'Cat bites dog';
  ```

  Se você não fornecer um tipo de filtro – isto é, se o seu argumento nomeado não contiver um “underscore” duplo – o tipo de filtro é assumido como sendo `exact`

  Por exemplo, os dois seguintes argumentos são equivalentes:

  ```
  >>> Blog.objects.get(id__exact=14)  # Explicit form
  >>> Blog.objects.get(id=14)         # __exact is implied
  ```

  Isso se dá por conveniência, porque os filtros `exact` são casos comuns.

**[`iexact`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-iexact)**

  Uma combinação que ignora a diferença entre caixa-alta e caixa-baixa. Então a consulta:

  ```
  >>> Blog.objects.get(name__iexact="beatles blog")
  ```

  Deveria encontrar um `Blog` entitulado `"Beatles Blog"`, `"beatles blog"`, ou mesmo `"BeAtlES blOG"`.

**[`contains`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-contains)**

  Teste de contenção sensíveis ao tipo de caixa. Por exemplo:

  ```
  Entry.objects.get(headline__contains='Lennon')
  ```

  Mais ou menos traduzido para este SQL:

  ```sql
  SELECT ... WHERE headline LIKE '%Lennon%';
  ```

  Note que este irá encontrar o “headline” `'Today Lennon honored'` mas não o `'today lennon honored'`.

  Existe também uma versão que ignora o tipo de caixa, [`icontains`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-icontains).

**[`startswith`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-startswith), [`endswith`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-endswith)**

  Busca começa-com e termina-com, respectivamente. Existe também a versão que ignora o tipo de caixa chamada [`istartswith`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-istartswith) e [`iendswith`](/pt-br/3.0/ref/models/querysets/#std-fieldlookup-iendswith).

Denovo, isso aqui somente arranha a superfície. Uma refrência completa pode ser achada na [Referência de filtros de campo](/pt-br/3.0/ref/models/querysets/#field-lookups).

### Filtros que abrangem os relacionamentos

Django offers a powerful and intuitive way to “follow” relationships in
lookups, taking care of the SQL `JOIN`s for you automatically, behind the
scenes. To span a relationship, use the field name of related fields
across models, separated by double underscores, until you get to the field you
want.

Este exemplo devolve todos os objetos `Entry` com um `Blog` o qual o `name` é `'Beatles Blog'`:

```
>>> Entry.objects.filter(blog__name='Beatles Blog')
```

A abrangância pode ser tão profunda quanto queira.

It works backwards, too. To refer to a “reverse” relationship, use the
lowercase name of the model.

Este exemplo retorna todos os objetos ```Blog``os quais tem pelo menos uma ``Entry``` a qual o `headline` contém `'Lennon'`:

```
>>> Blog.objects.filter(entry__headline__contains='Lennon')
```

Se você estiver filtrando através de múltiplos relacionamentos e um dos modelos intermediários não tiver um valor que vá de encontro com a condição do filtro, o Django irá tratá-lo como se houvesse um objeto vazio (todos os valores são `NULL`), mas válido. Tudo isso significa que nenhum erro será emitido. Por exemplo, neste filtro:

```
Blog.objects.filter(entry__authors__name='Lennon')
```

(se houvesse um modelo `Author` relacionado), se não houvesse  `author` associado com uma “entry”, seria tratado como se também não houvesse um `name` anexo, ao invés de emitir um erro por causa do `author` faltante.

```
Blog.objects.filter(entry__authors__name__isnull=True)
```

irá retornar objeto do tipo `Blog` que tenham um `name` vazio no `author` a também aqueles os quais tem um `author` vazio no `entry`.  Se você não que estes últimos objetos, você poderia escrever:

```
Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)
```

#### Abrangendo relacionamentos multi-interpretados

Quando se está filtrando um objeto baseado em uma [`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField)  ou em uma [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey) reversa, existem dois tipos diferentes de filtros que talvez lhe interesse. Considere o relacionamento `Blog`/`Entry`  (`Blog` para `Entry` é uma relação um-para-muitos). Talvez estejamos interessados em encontrar blogs que tenham uma “entry” a qual tenha *“Lennon”* no “headline” e foi publicado em 2008. Ou talvez queiramos achar blogs que tenham um “entry” com *“Lennon”* na “headline” como também uma “entry” que foi publicada em 2008. Uma vez que tenhamos múltiplos “entry”s associados com um único `Blog`, ambas destas consultas são possíveis e fazem sentido em algumas situações.

O mesmo tipo de situação vêem a tona com uma [`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField). Por exemplo, se um `Entry` tem um [`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField) chamado `tags`, talvez queiramos encontrar “entry”s conectados com “tags” chamada *“music”* e *“bands”* ou talvez queiramos uma “entry”que contém uma “tag” com o nome de *“music”* e status de *“public”*.

Para lidar com ambas as situações, o Django tem uma maneira conveniente de processar as chamadas do [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter). Tudo que está dentro de uma única chamada [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) é aplicado simultâneamente para filtrar item de combinem com todos os requerimentos. Chamadas sucessivas de [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) restrigem os conjunto de objetos, mas para relacionamentos com vários valores, eles se aplicam para qualquer objeto conectaco a chamada do primeiro modelo, não necessariamente aqueles objetos que foram selecionada por uma chamada anterior de [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter).

Isso pode parecer um pouco confuso, então talvez um exemplo irá carificar. Para selecionar todas as “entries” de blogs que contém *“Lennon”* na manchete e que foram publicadas em 2008 (a mesma entrada satisfaz ambas as condições), nós poderíamos escrever:

```
Blog.objects.filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)
```

Para selecionar todos os blogs que contenham uma “entry” com *“Lennon”*  na manchete **assim como** uma “entry” que foi publicada em 2008, podeíamos escrever:

```
Blog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)
```

Suponha que exista somente um blog que tenha ambas as “entries” contendo *“Lennon”*  e “entries” de 2008, mas nenhuma das “entries” de 2008 contém *“Lennon”*. A primeira consulta não irá retornar qualquer blog, mas a segunda consulta irá retornar aquele blog.

No segundo exemplo, o primeiro filtro restringe a consulta a todos aqueles blogs ligados a “entries” com *“Lennon”*  na manchete. O Segundo filtro restringe o conjunto de blogs *e ainda* aqueles que também são ligados a entradas que foram publicadas em 2008. As “entries” selecionadas por um segundo filtro talvez tehha ou não tenha as mesmas “entries” do primeiro filtro. Estamos filtrando os items `Blog` com cada comando de filtro, não os items `Entry`.

> **Note**
>
> O comportamento do [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) para consultas que abrangem relacionamentos com valores múltiplos, como descrito acima, não é implementado de maneira equivalente no [`exclude()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude). Ao invés, as condições em uma única chamada [`exclude()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude) não necessariamente irão se referenciar ao mesmo item.
>
> Por exemplo, a seguinte consulta excluiria blogs que contém *ambas* “entries” com *“Lennon”*  na manchete *e* “entries” publicadas em 2008:
>
> ```
> Blog.objects.exclude(
>     entry__headline__contains='Lennon',
>     entry__pub_date__year=2008,
> )
> ```
>
> Contudo, diferente do comportamento quando usado o [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter), este não limitará blogs baseados em “entries” que satisfaçam ambas as condições. Para tal, isto é, para selecionar todos os blogs que não contenham “entries” publicadas com *“Lennon”* que foram publicadas em 2008, você precisa fazer duas consultas:
>
> ```
> Blog.objects.exclude(
>     entry__in=Entry.objects.filter(
>         headline__contains='Lennon',
>         pub_date__year=2008,
>     ),
> )
> ```

### Filtros podem referenciar campos do modelo

Nos exemplos dados até agora, construímos filtros que comparam o valor de um campo de modelo com uma constante. Mas e se você quiser comparar o valor de um modelo com outro campo no mesmo modelo?

O Django fornece a [`F expressions`](/pt-br/3.0/ref/models/expressions/#django.db.models.F) para permitir tais comparações. Instâncias de `F()` atuam como uma referência a um campo de modelo dentro de uma consulta. Essas referências podem então ser comparadas a valores de dois diferentes campos na mesma instância de modelo.

Por exemplo, para encontrar uma lista de todas “entries” que tenham mais comentários que “pingbacks”, construimos um objeto `F()` para referenciar o contados de “pingback”, e usar o objeto `F()` na consulta:

```
>>> from django.db.models import F
>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks'))
```

O Django suporta o uso de adição, subtração, multiplicação, divisão, módulo, e aritmética poderosa com objetos `F()`, ambos com constantes e com outros objetos `F()`. Para encontrar todos os “entries” de blogs com *das vezes* mais comentários do que “pingbacks”, modificamos a consulta:

```
>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks') * 2)
```

Para encontrar as “entries” onde a taxa de “entry” é menor que a soma da contagem de “pingback” e contagem de comentários, poderíamos fazer a consulta:

```
>>> Entry.objects.filter(rating__lt=F('number_of_comments') + F('number_of_pingbacks'))
```

Podemos também usar a anotação do duplo “underscore” para abranger relacionamento em um objeto `F()`. Um objeto `F()` com duplo “underscore” introduzirá qualquer “join” necessária para acessar objetos relacionados. Por exemplo, para receber todas as “entries” onde o nome do autor é o mesmo que o nome do blog, nós poderíamos fazer a consulta:

```
>>> Entry.objects.filter(authors__name=F('blog__name'))
```

Para data e campos “date/time”, você pode adicionar ou subtrair um objeto do tipo [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) object. A consulta seguinte retornaria todas as entradas que foram modificadas mais de 3 dias depois que foram publicadas:

```
>>> from datetime import timedelta
>>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))
```

The `F()` objects support bitwise operations by `.bitand()`, `.bitor()`,
`.bitrightshift()`, and `.bitleftshift()`. For example:

```
>>> F('somefield').bitand(16)
```

### O atalho de filtro `pk`

Por conveniência, o Django fornece um atalho para o filtro `pk`, o que representa a “chave-primária”.

No modelo `Blog` de exemplo model, a chave-primária é o campo `id`, de modo que estes três exemplos são equivalentes:

```
>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied
>>> Blog.objects.get(pk=14) # pk implies id__exact
```

O uso da `pk` não está limitado a consultas `__exact` – qualquer termo de consulta pode ser combinado com `pk` para realizar uma consulta com a chave-primária de um modelo:

```
# Get blogs entries with id 1, 4 and 7
>>> Blog.objects.filter(pk__in=[1,4,7])

# Get all blog entries with id > 14
>>> Blog.objects.filter(pk__gt=14)
```

O filtro `pk` também funciona através de “joins”. Por exemplo, estes três comandos são equivalentes:

```
>>> Entry.objects.filter(blog__id__exact=3) # Explicit form
>>> Entry.objects.filter(blog__id=3)        # __exact is implied
>>> Entry.objects.filter(blog__pk=3)        # __pk implies __id__exact
```

### Substituição de sinais de porcentagem e “underscores” nos comandos `Like`

Os campos filtros que equivalem ao comando SQL `LIKE` (`iexact`, `contains`, `icontains`, `startswith`, `istartswith`, `endswith` and `iendswith`) irão automaticamente substituir os dois caracteres especiais usados em comandos `LIKE` – o sinal de porcentagem e o “underscore”.  (Em um comando `LIKE`, o sinal de porcentagem significa múltiplos-caracteres curingas e o “underscore” siginifica um único caracter curinga.)

This means things should work intuitively, so the abstraction doesn’t leak.
For example, to retrieve all the entries that contain a percent sign, use the
percent sign as any other character:

```
>>> Entry.objects.filter(headline__contains='%')
```

O Django irá cuidar da citação por você; o SQL resultante se parecerá com algo como:

```sql
SELECT ... WHERE headline LIKE '%\%%';
```

O mesmo vale para os “underscores”. Ambos os sinais, porcentagem e “underscores”, são manipulados para você de maneira transparente.

### “Cache”  e `QuerySets`s

Cada [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) contém um “cache” para minimizar o acesso ao banco de dados. Entendendo como isso funciona lhe permitirá escrever código mais eficiente.

Em uma classe [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) que acaba de ser criada, o “cache” está vazio. A primeira vez que a [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) é interpretada – e portanto, uma consulta ao banco acontece – o Django salva o resultado da consulta no  “cache” da [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)’s e retorna o resultado que foi requerido explicitamente (exemplo, o próximo elemento, se o [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) está sendo iterado). Execuçãoes subsequentes do [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) reusam os resultados que estão no “cache”.

Mantenha este comportamento do cache em mente, porque ele pode te pegar se você não usar seu [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)s de maneira correta. Por exemplo irá criar dois [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)s, interpretá-los, e jogá-los fora.

```
>>> print([e.headline for e in Entry.objects.all()])
>>> print([e.pub_date for e in Entry.objects.all()])
```

Isso significa que a mesma consulta de banco de dados será executada duas vezes, efetivamente dobrando a carga no banco de dados. Também existe a posibilidade das duas listas não incluírem os mesmos registros de banco de dados, porque uma `Entry` talvez tenha sido adicionada ou deletada durante a fração de segundo entre as duas requisições.

To avoid this problem, save the [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) and
reuse it:

```
>>> queryset = Entry.objects.all()
>>> print([p.headline for p in queryset]) # Evaluate the query set.
>>> print([p.pub_date for p in queryset]) # Re-use the cache from the evaluation.
```

#### Quando `QuerySet`s não são armazenados no “cache”

Resultados de consultas nem sempre são salvas no “cache”. Quando interpretar somente *parte*  da consulta, o “cache” é veririficado, mas se ele não estiver populado então os itens retornados pela consulta subsequente não vão para o “cache”. Especificamente, isso significa que [limitar consultas](#limiting-querysets) usando o fatiamento de “array” ou um índice não irá popular o cache.

Por exemplo, pegar um certo índice em um objeto “queryset” repetidamente irá consultar o banco de dados todas as vezes:

```
>>> queryset = Entry.objects.all()
>>> print(queryset[5]) # Queries the database
>>> print(queryset[5]) # Queries the database again
```

Porém, se todo o queryset foi interpretado, então o “cache” será verificado:

```
>>> queryset = Entry.objects.all()
>>> [entry for entry in queryset] # Queries the database
>>> print(queryset[5]) # Uses cache
>>> print(queryset[5]) # Uses cache
```

Aqui estão alguns exemplos de outras ações que irão resultar na interpretação de toda  a consulta e portanto populam o “cache”:

```
>>> [entry for entry in queryset]
>>> bool(queryset)
>>> entry in queryset
>>> list(queryset)
```

> **Note**
>
> Simplesmente dar um “print” no “queryset” não popula o “cache”. Isso é porque a chamada do \_\_repr\_\_()\`\`somente retorna uma fatia de todo o “queryset”.

## Consultas complexas com objetos `Q`

Consultas com argumentos nomeados – no [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter), etc. – compõem uma “E”. Se você precisa executar consultas mais complexas (por exemplo, consultas com comandos `OR`), você pode usar [`Q objects`](/pt-br/3.0/ref/models/querysets/#django.db.models.Q).

Um [`objeto Q`](/pt-br/3.0/ref/models/querysets/#django.db.models.Q) (`django.db.models.Q`) é um objeto usado para encapsular uma coleção de argumentos nomeados. Estes argumentos são especificados como um “campo de filtro” acima.

Por exemplo, este objeto `Q` encapsula uma única consulta `LIKE`:

```
from django.db.models import Q
Q(question__startswith='What')
```

Objetos `Q` podem ser combinados usando os operadores `&` e `|`. Quando um operador é usado com dois objetos `Q`, ele produz um novo objeto Q\`.

Por exemplo, este comando produz um único objeto `Q` que representa o `OR` de duas consultas `"question__startswith"`:

```
Q(question__startswith='Who') | Q(question__startswith='What')
```

Isso é o equivalente as seguintes cláusulas SQL `WHERE`:

```
WHERE question LIKE 'Who%' OR question LIKE 'What%'
```

Você pode compor comandos de uma complexidade arbitrária combinando objeto `Q` com os operadores `&` e `|` e usar o agrupamento entre parêntesis. Os objetos `Q` podem também ser negados usando o operador `~`, possbilitando combinar filtros que combinem uma consulta normal e um consulta de negação (`NOT`):

```
Q(question__startswith='Who') | ~Q(pub_date__year=2005)
```

Para cada função de filtro que recebe argumentos nominados (ex.: [`filter()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.filter), [`exclude()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude), [`get()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.get)) pode também se passado um ou mais objetos Q\`\`como argumentos posicionais (not-named). Se você prover múltiplos objetos Q\`\`para uma função filtro, os argumentos serão interpolados com lógicas “E”. Por exemplo:

```
Poll.objects.get(
    Q(question__startswith='Who'),
    Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))
)
```

… roughly translates into the SQL:

```sql
SELECT * from polls WHERE question LIKE 'Who%'
    AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')
```

Funções de filtro podem misturar o uso de objetos `Q` e argumentos nomeados. Todos os argumentos fornecidos para uma função filtro (sejam eles argumentos nomeados ou objetos `Q`)  são interpolados com “E”. Porém, se um objeto `Q` é fornecido, é necessário que este preceda qualquer argumento nomeado. Por exemplo:

```
Poll.objects.get(
    Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),
    question__startswith='Who',
)
```

… seria uma consulta válida, equivalente ao exemplo anterior; mas:

```
# INVALID QUERY
Poll.objects.get(
    question__startswith='Who',
    Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))
)
```

… não seria válido.

> **See also**
>
> The [OR lookups examples](https://github.com/django/django/blob/stable/3.0.x/tests/or_lookups/tests.py) in Django’s
> unit tests show some possible uses of `Q`.

## Comparando objetos

To compare two model instances, use the standard Python comparison operator,
the double equals sign: `==`. Behind the scenes, that compares the primary
key values of two models.

Usando o exemplo `Entry` acima, os comandos seguintes são equivalentes:

```
>>> some_entry == other_entry
>>> some_entry.id == other_entry.id
```

Se a chave-primária de um modelo não é chamada `id`, não tem problema. Comparações sempre irão usar a chave-primária, não importa como é chamada. Por exemplo, se a chave-primária de um modelo é chamada `name`, estes dois comandos são equivalentes:

```
>>> some_obj == other_obj
>>> some_obj.name == other_obj.name
```

## Deletando objetos

O método de deleção, é convenientemente chamado [`delete()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.delete). Este método deleta imediatamente os objetos e retorna o número de objetos deletados e um dicionário com o número de deleções por tipo de objeto. Exemplo:

```
>>> e.delete()
(1, {'weblog.Entry': 1})
```

Você também pode deletar objetos em massa. Cada [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) tem um método [`delete()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.delete), o qual deleta todos os membros daquele [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet).

Por exemplo, esse deleta todas os objetos `Entry` com o ano do `pub_date` igual 2005:

```
>>> Entry.objects.filter(pub_date__year=2005).delete()
(5, {'webapp.Entry': 5})
```

Keep in mind that this will, whenever possible, be executed purely in SQL, and
so the `delete()` methods of individual object instances will not necessarily
be called during the process. If you’ve provided a custom `delete()` method
on a model class and want to ensure that it is called, you will need to
“manually” delete instances of that model (e.g., by iterating over a
[`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) and calling `delete()` on each
object individually) rather than using the bulk
[`delete()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.delete) method of a
[`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet).

When Django deletes an object, by default it emulates the behavior of the SQL
constraint `ON DELETE CASCADE` – in other words, any objects which had
foreign keys pointing at the object to be deleted will be deleted along with
it. For example:

```
b = Blog.objects.get(pk=1)
# This will delete the Blog and all of its Entry objects.
b.delete()
```

This cascade behavior is customizable via the
[`on_delete`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey.on_delete) argument to the
[`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey).

Note that [`delete()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.delete) is the only
[`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) method that is not exposed on a
[`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) itself. This is a safety mechanism to
prevent you from accidentally requesting `Entry.objects.delete()`, and
deleting *all* the entries. If you *do* want to delete all the objects, then
you have to explicitly request a complete query set:

```
Entry.objects.all().delete()
```

## Copiando as instâncias de modelo

Although there is no built-in method for copying model instances, it is
possible to easily create new instance with all fields’ values copied. In the
simplest case, you can set `pk` to `None`. Using our blog example:

```
blog = Blog(name='My blog', tagline='Blogging is easy')
blog.save() # blog.pk == 1

blog.pk = None
blog.save() # blog.pk == 2
```

Things get more complicated if you use inheritance. Consider a subclass of
`Blog`:

```
class ThemeBlog(Blog):
    theme = models.CharField(max_length=200)

django_blog = ThemeBlog(name='Django', tagline='Django is easy', theme='python')
django_blog.save() # django_blog.pk == 3
```

Due to how inheritance works, you have to set both `pk` and `id` to None:

```
django_blog.pk = None
django_blog.id = None
django_blog.save() # django_blog.pk == 4
```

This process doesn’t copy relations that aren’t part of the model’s database
table. For example, `Entry` has a `ManyToManyField` to `Author`. After
duplicating an entry, you must set the many-to-many relations for the new
entry:

```
entry = Entry.objects.all()[0] # some previous entry
old_authors = entry.authors.all()
entry.pk = None
entry.save()
entry.authors.set(old_authors)
```

For a `OneToOneField`, you must duplicate the related object and assign it
to the new object’s field to avoid violating the one-to-one unique constraint.
For example, assuming `entry` is already duplicated as above:

```
detail = EntryDetail.objects.all()[0]
detail.pk = None
detail.entry = entry
detail.save()
```

## Alterando múltiplos objetos de uma só vez.

Algumas vezes você querer definir um campo para um particular valor para todos os objetos em uma . Você pode fazer isto com o  método. Por exemplo:

```
# Update all the headlines with pub_date in 2007.
Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same')
```

You can only set non-relation fields and [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey)
fields using this method. To update a non-relation field, provide the new value
as a constant. To update [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey) fields, set the
new value to be the new model instance you want to point to. For example:

```
>>> b = Blog.objects.get(pk=1)

# Change every Entry so that it belongs to this Blog.
>>> Entry.objects.all().update(blog=b)
```

The `update()` method is applied instantly and returns the number of rows
matched by the query (which may not be equal to the number of rows updated if
some rows already have the new value). The only restriction on the
[`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) being updated is that it can only
access one database table: the model’s main table. You can filter based on
related fields, but you can only update columns in the model’s main
table. Example:

```
>>> b = Blog.objects.get(pk=1)

# Update all the headlines belonging to this Blog.
>>> Entry.objects.select_related().filter(blog=b).update(headline='Everything is the same')
```

Be aware that the `update()` method is converted directly to an SQL
statement. It is a bulk operation for direct updates. It doesn’t run any
[`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save) methods on your models, or emit the
`pre_save` or `post_save` signals (which are a consequence of calling
[`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save)), or honor the
[`auto_now`](/pt-br/3.0/ref/models/fields/#django.db.models.DateField.auto_now) field option.
If you want to save every item in a [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet)
and make sure that the [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save) method is called on
each instance, you don’t need any special function to handle that. Loop over
them and call [`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save):

```
for item in my_queryset:
    item.save()
```

Calls to update can also use [`F expressions`](/pt-br/3.0/ref/models/expressions/#django.db.models.F) to
update one field based on the value of another field in the model. This is
especially useful for incrementing counters based upon their current value. For
example, to increment the pingback count for every entry in the blog:

```
>>> Entry.objects.all().update(number_of_pingbacks=F('number_of_pingbacks') + 1)
```

However, unlike `F()` objects in filter and exclude clauses, you can’t
introduce joins when you use `F()` objects in an update – you can only
reference fields local to the model being updated. If you attempt to introduce
a join with an `F()` object, a `FieldError` will be raised:

```
# This will raise a FieldError
>>> Entry.objects.update(headline=F('blog__name'))
```

## Objetos relacionados

When you define a relationship in a model (i.e., a
[`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey),
[`OneToOneField`](/pt-br/3.0/ref/models/fields/#django.db.models.OneToOneField), or
[`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField)), instances of that model will have
a convenient API to access the related object(s).

Using the models at the top of this page, for example, an `Entry` object `e`
can get its associated `Blog` object by accessing the `blog` attribute:
`e.blog`.

(Behind the scenes, this functionality is implemented by Python
[descriptors](https://docs.python.org/3/howto/descriptor.html). This shouldn’t really matter to
you, but we point it out here for the curious.)

Django also creates API accessors for the “other” side of the relationship –
the link from the related model to the model that defines the relationship.
For example, a `Blog` object `b` has access to a list of all related
`Entry` objects via the `entry_set` attribute: `b.entry_set.all()`.

All examples in this section use the sample `Blog`, `Author` and `Entry`
models defined at the top of this page.

### Relações One-to-many

#### Adiante

If a model has a [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey), instances of that model
will have access to the related (foreign) object via an attribute of the model.

Exemplo

```
>>> e = Entry.objects.get(id=2)
>>> e.blog # Returns the related Blog object.
```

You can get and set via a foreign-key attribute. As you may expect, changes to
the foreign key aren’t saved to the database until you call
[`save()`](/pt-br/3.0/ref/models/instances/#django.db.models.Model.save). Example:

```
>>> e = Entry.objects.get(id=2)
>>> e.blog = some_blog
>>> e.save()
```

If a [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey) field has `null=True` set (i.e.,
it allows `NULL` values), you can assign `None` to remove the relation.
Example:

```
>>> e = Entry.objects.get(id=2)
>>> e.blog = None
>>> e.save() # "UPDATE blog_entry SET blog_id = NULL ...;"
```

Forward access to one-to-many relationships is cached the first time the
related object is accessed. Subsequent accesses to the foreign key on the same
object instance are cached. Example:

```
>>> e = Entry.objects.get(id=2)
>>> print(e.blog)  # Hits the database to retrieve the associated Blog.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.
```

Note that the [`select_related()`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet.select_related)
[`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) method recursively prepopulates the
cache of all one-to-many relationships ahead of time. Example:

```
>>> e = Entry.objects.select_related().get(id=2)
>>> print(e.blog)  # Doesn't hit the database; uses cached version.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.
```

#### Following relationships “backward”

If a model has a [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey), instances of the
foreign-key model will have access to a [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) that
returns all instances of the first model. By default, this
[`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) is named `FOO_set`, where `FOO` is the
source model name, lowercased. This [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) returns
`QuerySets`, which can be filtered and manipulated as described in the
“Retrieving objects” section above.

Exemplo

```
>>> b = Blog.objects.get(id=1)
>>> b.entry_set.all() # Returns all Entry objects related to Blog.

# b.entry_set is a Manager that returns QuerySets.
>>> b.entry_set.filter(headline__contains='Lennon')
>>> b.entry_set.count()
```

You can override the `FOO_set` name by setting the
[`related_name`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey.related_name) parameter in the
[`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey) definition. For example, if the `Entry`
model was altered to `blog = ForeignKey(Blog, on_delete=models.CASCADE,
related_name='entries')`, the above example code would look like this:

```
>>> b = Blog.objects.get(id=1)
>>> b.entries.all() # Returns all Entry objects related to Blog.

# b.entries is a Manager that returns QuerySets.
>>> b.entries.filter(headline__contains='Lennon')
>>> b.entries.count()
```

#### Using a custom reverse manager

By default the [`RelatedManager`](/pt-br/3.0/ref/models/relations/#django.db.models.fields.related.RelatedManager) used
for reverse relations is a subclass of the [default manager](/pt-br/3.0/topics/db/managers/#manager-names)
for that model. If you would like to specify a different manager for a given
query you can use the following syntax:

```
from django.db import models

class Entry(models.Model):
    #...
    objects = models.Manager()  # Default Manager
    entries = EntryManager()    # Custom Manager

b = Blog.objects.get(id=1)
b.entry_set(manager='entries').all()
```

If `EntryManager` performed default filtering in its `get_queryset()`
method, that filtering would apply to the `all()` call.

Of course, specifying a custom reverse manager also enables you to call its
custom methods:

```
b.entry_set(manager='entries').is_published()
```

#### Additional methods to handle related objects

In addition to the [`QuerySet`](/pt-br/3.0/ref/models/querysets/#django.db.models.query.QuerySet) methods defined in
“Retrieving objects” above, the [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey)
[`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) has additional methods used to handle the
set of related objects. A synopsis of each is below, and complete details can
be found in the [related objects reference](/pt-br/3.0/ref/models/relations/).

**`add(obj1, obj2, ...)`**

  Adds the specified model objects to the related object set.

**`create(**kwargs)`**

  Creates a new object, saves it and puts it in the related object set.
  Returns the newly created object.

**`remove(obj1, obj2, ...)`**

  Removes the specified model objects from the related object set.

**`clear()`**

  Removes all objects from the related object set.

**`set(objs)`**

  Replace the set of related objects.

To assign the members of a related set, use the `set()` method with an
iterable of object instances. For example, if `e1` and `e2` are `Entry`
instances:

```
b = Blog.objects.get(id=1)
b.entry_set.set([e1, e2])
```

If the `clear()` method is available, any pre-existing objects will be
removed from the `entry_set` before all objects in the iterable (in this
case, a list) are added to the set. If the `clear()` method is *not*
available, all objects in the iterable will be added without removing any
existing elements.

Each “reverse” operation described in this section has an immediate effect on
the database. Every addition, creation and deletion is immediately and
automatically saved to the database.

### Many-to-many relationships

Both ends of a many-to-many relationship get automatic API access to the other
end. The API works similar to a “backward” one-to-many relationship, above.

One difference is in the attribute naming: The model that defines the
[`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField) uses the attribute name of that
field itself, whereas the “reverse” model uses the lowercased model name of the
original model, plus `'_set'` (just like reverse one-to-many relationships).

An example makes this easier to understand:

```
e = Entry.objects.get(id=3)
e.authors.all() # Returns all Author objects for this Entry.
e.authors.count()
e.authors.filter(name__contains='John')

a = Author.objects.get(id=5)
a.entry_set.all() # Returns all Entry objects for this Author.
```

Like [`ForeignKey`](/pt-br/3.0/ref/models/fields/#django.db.models.ForeignKey),
[`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField) can specify
[`related_name`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField.related_name). In the above example,
if the [`ManyToManyField`](/pt-br/3.0/ref/models/fields/#django.db.models.ManyToManyField) in `Entry` had specified
`related_name='entries'`, then each `Author` instance would have an
`entries` attribute instead of `entry_set`.

Another difference from one-to-many relationships is that in addition to model
instances,  the `add()`, `set()`, and `remove()` methods on many-to-many
relationships accept primary key values. For example, if `e1` and `e2` are
`Entry` instances, then these `set()` calls work identically:

```
a = Author.objects.get(id=5)
a.entry_set.set([e1, e2])
a.entry_set.set([e1.pk, e2.pk])
```

### One-to-one relationships

One-to-one relationships are very similar to many-to-one relationships. If you
define a [`OneToOneField`](/pt-br/3.0/ref/models/fields/#django.db.models.OneToOneField) on your model, instances of
that model will have access to the related object via an attribute of the
model.

Por exemplo:

```
class EntryDetail(models.Model):
    entry = models.OneToOneField(Entry, on_delete=models.CASCADE)
    details = models.TextField()

ed = EntryDetail.objects.get(id=2)
ed.entry # Returns the related Entry object.
```

The difference comes in “reverse” queries. The related model in a one-to-one
relationship also has access to a [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) object, but
that [`Manager`](/pt-br/3.0/topics/db/managers/#django.db.models.Manager) represents a single object, rather than
a collection of objects:

```
e = Entry.objects.get(id=2)
e.entrydetail # returns the related EntryDetail object
```

If no object has been assigned to this relationship, Django will raise
a `DoesNotExist` exception.

Instances can be assigned to the reverse relationship in the same way as
you would assign the forward relationship:

```
e.entrydetail = ed
```

### How are the backward relationships possible?

Other object-relational mappers require you to define relationships on both
sides. The Django developers believe this is a violation of the DRY (Don’t
Repeat Yourself) principle, so Django only requires you to define the
relationship on one end.

But how is this possible, given that a model class doesn’t know which other
model classes are related to it until those other model classes are loaded?

The answer lies in the [`app registry`](/pt-br/3.0/ref/applications/#django.apps.apps). When Django
starts, it imports each application listed in [`INSTALLED_APPS`](/pt-br/3.0/ref/settings/#std-setting-INSTALLED_APPS), and
then the `models` module inside each application. Whenever a new model class
is created, Django adds backward-relationships to any related models. If the
related models haven’t been imported yet, Django keeps tracks of the
relationships and adds them when the related models eventually are imported.

For this reason, it’s particularly important that all the models you’re using
be defined in applications listed in [`INSTALLED_APPS`](/pt-br/3.0/ref/settings/#std-setting-INSTALLED_APPS). Otherwise,
backwards relations may not work properly.

### Queries over related objects

Queries involving related objects follow the same rules as queries involving
normal value fields. When specifying the value for a query to match, you may
use either an object instance itself, or the primary key value for the object.

For example, if you have a Blog object `b` with `id=5`, the following
three queries would be identical:

```
Entry.objects.filter(blog=b) # Query using object instance
Entry.objects.filter(blog=b.id) # Query using id from instance
Entry.objects.filter(blog=5) # Query using id directly
```

## Falling back to raw SQL

If you find yourself needing to write an SQL query that is too complex for
Django’s database-mapper to handle, you can fall back on writing SQL by hand.
Django has a couple of options for writing raw SQL queries; see
[Performing raw SQL queries](/pt-br/3.0/topics/db/sql/).

Finally, it’s important to note that the Django database layer is merely an
interface to your database. You can access your database via other tools,
programming languages or database frameworks; there’s nothing Django-specific
about your database.