---
title: "Models"
version: 4.2
locale: pt-br
source: https://docs.djangoproject.com/pt-br/4.2/topics/db/models/
canonical: https://djangodocs.dev/pt-br/4.2/topics/db/models/
---
# Models
Um modelo é um único e definitiva fonte de dados sobre os seus dados, Ele contém os campos e comportamentos essenciais dos dados que você está armazenando. Em geral, cada modelo mapeia para uam única tabela no seu banco de dados.
O básico
- Cada modelo é uma classe Python que herda [`django.db.models.Model`](/pt-br/4.2/ref/models/instances/#django.db.models.Model).
- Cada atributo de um modelo representa um campo no banco de dados.
- Com tudo isso, Django lhe dá uma API de acesso ao banco de dados gerada automaticamente; veja [Fazendo consultas](/pt-br/4.2/topics/db/queries/).
## Exemplo rápido
Neste exemplo o modelo define um `Person`, o qual tem um ```first_name``e ``last_name```:
```
from django.db import models
class Person(models.Model):
first_name = models.CharField(max_length=30)
last_name = models.CharField(max_length=30)
```
`first_name` e `last_name` são “[fields](#fields)” do modelo. Cada campo é especificado como um atributo de classe, e cada atributo mapeia uma coluna do banco de dados.
O modelo `Person` criaria uma tabela de banco de dados como esta:
```sql
CREATE TABLE myapp_person (
"id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY,
"first_name" varchar(30) NOT NULL,
"last_name" varchar(30) NOT NULL
);
```
Algumas notas técnicas:
- O nome da tabela, `myapp_person`, é automaticamente derivado de alguns metadados do modelo mas pode ser sibrescrito. Veja [Table names](/pt-br/4.2/ref/models/options/#table-names) para mais detalhes.
- Um campo `id` é adicionado automaticamente, mas este comportamento pode ser sobrescrito. Veja [Campos chave-primária automáticos.](#automatic-primary-key-fields).
- O SQL `CREATE TABLE` neste exemplo está formatado usando a syntax do PostgreSQL, mas vale a pena notar que o Django usa SQL de acordo com o “backend” do banco de dados especificado no seu [arquivo de definições](/pt-br/4.2/topics/settings/).
## Usando Modelos
Uma vez que tenha definido seus modelos, você precisa dizer ao Django que irá *usar* aqueles modelos. Faça isso editando seu arquivo de definições e alterando a definição do [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS) para adicionar o nome do módulo que contém seu `models.py`.
Por exemplo, se o modelo para sua aplicação está em um módulo `myapp.models` (a estrutura de pacote que foi criada para uma aplicação pelo script [`manage.py startapp`](/pt-br/4.2/ref/django-admin/#django-admin-startapp)), [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS) deve ser lido, em parte:
```
INSTALLED_APPS = [
# ...
"myapp",
# ...
]
```
Quando adicionar novas aplicações ao [`INSTALLED_APPS`](/pt-br/4.2/ref/settings/#std-setting-INSTALLED_APPS), tenha certeza de rodar [`manage.py migrate`](/pt-br/4.2/ref/django-admin/#django-admin-migrate), opcionalmente antes fazendo migrações para eles antes com [`manage.py makemigrations`](/pt-br/4.2/ref/django-admin/#django-admin-makemigrations).
## Campos
A parte mais importante de um modelo – e a única parte requerida de um modelo – é a lista de campos de banco de dados que ele define. Campos são especificados através de atributos de classe. Cuidado para não escolher nomes de campos que conflitem com a [API dos modelos](/pt-br/4.2/ref/models/instances/) like `clean`, `save`, ou `delete`.
Exemplo
```
from django.db import models
class Musician(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
instrument = models.CharField(max_length=100)
class Album(models.Model):
artist = models.ForeignKey(Musician, on_delete=models.CASCADE)
name = models.CharField(max_length=100)
release_date = models.DateField()
num_stars = models.IntegerField()
```
### Tipos de campos
Cada campo no seu modelo deve ser instanciado da classe [`Field`](/pt-br/4.2/ref/models/fields/#django.db.models.Field) apropriada. O Django usa o tipo de classe do campo para determinar algumas coisas:
- O tipo da coluna, o qual diz ao banco de dados que tipo de dado irá armazenar (e.g. `INTEGER`, `VARCHAR`, `TEXT`).
- O [widget](/pt-br/4.2/ref/forms/widgets/) HTML padrão para usar quando renderizar o campo de um form (ex. ``).
- The minimal validation requirements, used in Django’s admin and in
automatically-generated forms.
Django vem com dúzias de tipos de campos; você pode achar uma lista nas [refrências de campos de modelo](/pt-br/4.2/ref/models/fields/#model-field-types). Você pode facilmente escrever seus próprios campos se os que vêm definidos no Django não resolverem; veja [Como criar campos de modelo customizado](/pt-br/4.2/howto/custom-model-fields/).
### Opções de campos
Cada campo recebe um certo conjunto de argumentos específicos (documentados na [referência de campos de modelo](/pt-br/4.2/ref/models/fields/#model-field-types)). Por exemplo, a [`CharField`](/pt-br/4.2/ref/models/fields/#django.db.models.CharField) (e suas subclasses) requerem um argumento [`max_length`](/pt-br/4.2/ref/models/fields/#django.db.models.CharField.max_length) o qual especifica o comprimento usado para armazenar dados do campo `VARCHAR` do banco de dados.
Também há um conjunto de argumentos comuns disponíveis para todos os tipos de campos. Todos opcionais. Estes argumentos são explicados na [referência](/pt-br/4.2/ref/models/fields/#common-model-field-options), mas aqui um sumário dos argumentos mais usados:
**[`null`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.null)**
Se `True`, o Django irá usar valores “vazios” como `NULL` no banco de dados. Padrão is `False`.
**[`blank`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.blank)**
Se `True`, é permitido o campo estar em “branco”. O padrão é `False`.
Note que isso é diferente de [`null`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.null). [`null`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.null) é puramente relacionado ao banco de dados, enquanto que o [`blank`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.blank) é relacionado a validação. Se um campo tiver [`blank=True`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.blank), a validação do “form” permitirá entrada de ym valor vazio. Se o campo tiver [`blank=False`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.blank), o campo será requerido.
**[`choices`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.choices)**
A [sequence](https://docs.python.org/3/glossary.html#term-sequence) of 2-tuples to use as choices for this field. If this
is given, the default form widget will be a select box instead of the
standard text field and will limit choices to the choices given.
Uma lista de opções se parece com isso:
```
YEAR_IN_SCHOOL_CHOICES = [
("FR", "Freshman"),
("SO", "Sophomore"),
("JR", "Junior"),
("SR", "Senior"),
("GR", "Graduate"),
]
```
> **Note**
>
> A new migration is created each time the order of `choices` changes.
The first element in each tuple is the value that will be stored in the
database. The second element is displayed by the field’s form widget.
Given a model instance, the display value for a field with `choices` can
be accessed using the [`get_FOO_display()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.get_FOO_display)
method. For example:
```
from django.db import models
class Person(models.Model):
SHIRT_SIZES = [
("S", "Small"),
("M", "Medium"),
("L", "Large"),
]
name = models.CharField(max_length=60)
shirt_size = models.CharField(max_length=1, choices=SHIRT_SIZES)
```
```pycon
>>> p = Person(name="Fred Flintstone", shirt_size="L")
>>> p.save()
>>> p.shirt_size
'L'
>>> p.get_shirt_size_display()
'Large'
```
You can also use enumeration classes to define `choices` in a concise
way:
```
from django.db import models
class Runner(models.Model):
MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
name = models.CharField(max_length=60)
medal = models.CharField(blank=True, choices=MedalType.choices, max_length=10)
```
Further examples are available in the [model field reference](/pt-br/4.2/ref/models/fields/#field-choices).
**[`default`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.default)**
O valor padrão para o campo. Este pode ser um valor ou um objeto “callable”. Se “callable” ele será chamado cada vez que um novo objeto for criado.
**[`help_text`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.help_text)**
Texto extra de ajuda para ser mostrado com o “widget” do formulário. É útil para documentar mesmo que seu campo não seja usado em um formulário.
**[`primary_key`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.primary_key)**
Se `True`, este campo será a chave-primária do seu modelo.
Se você não especificar o [`primary_key=True`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.primary_key) para qualquer campo no seu modelo, o Django irá automaticamente adicionar uma [`IntegerField`](/pt-br/4.2/ref/models/fields/#django.db.models.IntegerField) para ser a chave-primária, e você não precisa definir [`primary_key=True`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.primary_key) em nenhum dos seus campos a menos que queria sobrescrever o comportamento padrão da chave-primária. Para mais, veja [Campos chave-primária automáticos.](#automatic-primary-key-fields).
O campo chave-primária é somente para leitura. Se você alterar o valor de uma chave-primária em um objeto existente e salvá-lo, um novo objeto será criado além do antigo. Por exemplo:
```
from django.db import models
class Fruit(models.Model):
name = models.CharField(max_length=100, primary_key=True)
```
```pycon
>>> fruit = Fruit.objects.create(name="Apple")
>>> fruit.name = "Pear"
>>> fruit.save()
>>> Fruit.objects.values_list("name", flat=True)
```
**[`unique`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.unique)**
Se `True`, este campo deve ser único dentro da tabela
Novamente, estas são apenas descrições curtas das opções mais comuns dos campos. Detalhes completos podem ser encontrados na ref:referência de opções de campos de modelos comuns \.
### Campos chave-primária automáticos.
By default, Django gives each model an auto-incrementing primary key with the
type specified per app in [`AppConfig.default_auto_field`](/pt-br/4.2/ref/applications/#django.apps.AppConfig.default_auto_field) or globally in the
[`DEFAULT_AUTO_FIELD`](/pt-br/4.2/ref/settings/#std-setting-DEFAULT_AUTO_FIELD) setting. For example:
```
id = models.BigAutoField(primary_key=True)
```
If you’d like to specify a custom primary key, specify
[`primary_key=True`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.primary_key) on one of your fields. If Django
sees you’ve explicitly set [`Field.primary_key`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.primary_key), it won’t add the automatic
`id` column.
Cada modelo requere exatamente um campo que tenha [`primary_key=True`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.primary_key) (declarado explicitamente ou adicionado automaticamente).
### Nomes de campo detalhados
Cada tipo de campo, exceto para [`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey), [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) e [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField), recebe um argumento opcional como primeiro argumento – um nome detalhado. Se o nome detalhado não for informado, o Django irá automaticamente criar ele usando o atributo nome do campos, convertendo “underscores” para espaços.
Neste exemplo, o nome detalhada é `"person's first name"`:
```
first_name = models.CharField("person's first name", max_length=30)
```
Neste exemplo, o nome detalhado é `"first name"`:
```
first_name = models.CharField(max_length=30)
```
[`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey), [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) and [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) requerem que o primeiro argumento seja uma classe de modelo, então use o argumento nomeado [`verbose_name`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.verbose_name):
```
poll = models.ForeignKey(
Poll,
on_delete=models.CASCADE,
verbose_name="the related poll",
)
sites = models.ManyToManyField(Site, verbose_name="list of sites")
place = models.OneToOneField(
Place,
on_delete=models.CASCADE,
verbose_name="related place",
)
```
A convenção é não usar caixa-alta na primeira letra do [`verbose_name`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.verbose_name). O Django irá automaticamente captalizar a primeira letra quando for necessário.
### Relacionamentos
Claramente, o poder dos bancos de dados relacionais está em relacionar as tabelas entre elas. O Django oferece maneiras de definir os três tipos de relacionamentos mais comuns: muitos-para-muitos, muitos-para-um e um-para-um.
#### Many-to-one relationships
Para definir um relacionamento de muitos-para-um, use [`django.db.models.ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey). Você o usar como qualquer outro tipo de [`Field`](/pt-br/4.2/ref/models/fields/#django.db.models.Field): incluindo-o como um atributo do seu modelo.
A [`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey) requer um argumento posicional: a classe com a qual o modelo está relacionado.
Por exemplo, se um modelo `Car` tem um fabricante `Manufacturer` – quer dizer, um `Manufacturer` faz múltiplos carros mas cada `Car` somente tem um `Manufacturer` – use as seguintes definições:
```
from django.db import models
class Manufacturer(models.Model):
# ...
pass
class Car(models.Model):
manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)
# ...
```
Você também pode criar [relacionamentos recursivos](/pt-br/4.2/ref/models/fields/#recursive-relationships) (um objeto com relacionamento muitos-para-um comsigo mesmo) e [relacionamentos para modelos que ainda não foram definidos](/pt-br/4.2/ref/models/fields/#lazy-relationships); veja [a referência para campos de modelo](/pt-br/4.2/ref/models/fields/#ref-foreignkey) para detalhes.
It’s suggested, but not required, that the name of a
[`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey) field (`manufacturer` in the example
above) be the name of the model, lowercase. You can call the field whatever you
want. For example:
```
class Car(models.Model):
company_that_makes_it = models.ForeignKey(
Manufacturer,
on_delete=models.CASCADE,
)
# ...
```
> **See also**
>
> Campos [`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey) aceitam um número extra de argumentos os quais são explicados na [referência de campos de modelo](/pt-br/4.2/ref/models/fields/#foreign-key-arguments). Estas opções ajudam a definir como o relacionamento deve funcionar; todos são opcionais.
>
> Para detalhes sobre como acessar de meneira inversa os objetos relacionados, veja o ref:Exemplo de como seguir relacionamentos ao inverso \.
>
> Para um ódigo de exemplo, veja o [modelo exemplo de relacionamentos muitos-para-um](/pt-br/4.2/topics/db/examples/many_to_one/).
#### Many-to-many relationships
Para definir relacionamentos muitos-para-muitos, use [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField). Você o usa tal como qualquer outro tipo de [`Field`](/pt-br/4.2/ref/models/fields/#django.db.models.Field): incluindo-o como um atributo de classe no seu modelo
O [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) requer um argumento posicional: a classe com a qual o modelo está relacionado.
Por exemplo, se a `Pizza` tem muitos objetos `Topping` – quer dizer, um `Topping` pode ter em multiplas pizzas e cada `Pizza` tem muitos recheios – aqui está como você deveria representá-los:
```
from django.db import models
class Topping(models.Model):
# ...
pass
class Pizza(models.Model):
# ...
toppings = models.ManyToManyField(Topping)
```
Tal como [`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey), você também pode criar [relacionamentos recursivos](/pt-br/4.2/ref/models/fields/#recursive-relationships) (um objeto com relacionamento muitos-para-muitos com ele mesmo) e [relacionamentos com modelos ainda não definidos](/pt-br/4.2/ref/models/fields/#lazy-relationships).
É sugerido, mas não requerido que o nome de um [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) (`toppings` no nosso exemplo acima) seja um plural descrevendo o conjunto dos objetos relacionados do modelo.
Não importa quais dos modelos tem a [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField), mas você deve colocá-la somente em um dos modelos – não em ambos.
Geralmente, instancias de [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) devem ir no objeto que serão editados em um formulário. No exemplo acima, `toppings` está na `Pizza` (ao invés de `Topping` ter `pizzas` como [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) ) porque é mais natural pensar sobre pizza tendo recheio do que recheios estando em múltiplas pizzas. A maneira com está definido acima, o formulário de `Pizza` deveria deixar usuários selecionar os recheios.
> **See also**
>
> Veja o [Exemplo de relacionamento de modelo muitos-para-muitos](/pt-br/4.2/topics/db/examples/many_to_many/) par um exemplo completo.
[`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) os campos também aceitam vários argumentos extras como explicado na [referência de campos de modelo](/pt-br/4.2/ref/models/fields/#manytomany-arguments). Estas opções ajudam a definir como o relacionamento deve funcionar; todos são opcionais.
#### Campos extras no relacionamento muitos-para-muitos
When you’re only dealing with many-to-many relationships such as mixing and
matching pizzas and toppings, a standard
[`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) is all you need. However, sometimes
you may need to associate data with the relationship between two models.
Por exemplo, considere o caso de uma aplicação que rastreia grupos musicais aos quais pertencem músicos. Existe um relacionamento muitos-para-muitos entre pessoas e grupos aos quais eles são membros, então você poderia usar uma [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) para representar este relacionamento. Porém, existem váriios detalhes sobre este relacionamento que você talvez queria coletar, tal como a data na qual a pessoa se juntou ao grupo.
Para estas situações, o Django permite que você especifique o modelo que será usado para “governar” o relacionamento muitos-para-muitos. Você pode então colocar campos extras no modelo intermediário. O modelo intermediário está associado a [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) usando o argumento [`through`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField.through) para apontar para o modelo que atuará como um intermediário. Para nosso exemplo de músicos, o código poderia parecer como algo como:
```
from django.db import models
class Person(models.Model):
name = models.CharField(max_length=128)
def __str__(self):
return self.name
class Group(models.Model):
name = models.CharField(max_length=128)
members = models.ManyToManyField(Person, through="Membership")
def __str__(self):
return self.name
class Membership(models.Model):
person = models.ForeignKey(Person, on_delete=models.CASCADE)
group = models.ForeignKey(Group, on_delete=models.CASCADE)
date_joined = models.DateField()
invite_reason = models.CharField(max_length=64)
```
Quando você define um modelo intermediário, você especifica explicitamente chaves-estrangeiras para os modelos que estão envolvidos no relacionamento muitos-para-muitos. Esta declaração explícita define como os dois modelos estão relacionados.
Existem algumas poucas restrições sobre os modelos intermediários.
- Seu modelo intermediário deve ter uma - e \* somente\* uma - chave estrangeira para o modelo fonte (no nosso exemplo, este deve ser o `Group`), ou você deverá especificar explicitamente as chaves-estrangeiras que o Django deve usar para o relacionamento usando o [`ManyToManyField.through_fields`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField.through_fields). Se você tiver mais de uma chave-estrangeira e `through_fields` não estiver especificado, um erro de validação será emitido. Uma restrição similar se aplica para a chave-estrangeira para o modelo alvo (no nosso exemplo, este deve ser o `Person`).
- Para um modelo que tenha um relacionamento muitos-para-muitos para ele mesmo através de um modelo intermediário, é permitido duas chaves-estrangeiras para o mesmo modelo, mas elas serão tratadas como os dois lados (diferentes) do relacionamento muitos-para-muitos. Se houver *mais* de duas chaves-estrangeiras, você também deve especificar o `through_fields` como acima, ou um erro de validação será emitido.
Now that you have set up your [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField) to use
your intermediary model (`Membership`, in this case), you’re ready to start
creating some many-to-many relationships. You do this by creating instances of
the intermediate model:
```pycon
>>> ringo = Person.objects.create(name="Ringo Starr")
>>> paul = Person.objects.create(name="Paul McCartney")
>>> beatles = Group.objects.create(name="The Beatles")
>>> m1 = Membership(
... person=ringo,
... group=beatles,
... date_joined=date(1962, 8, 16),
... invite_reason="Needed a new drummer.",
... )
>>> m1.save()
>>> beatles.members.all()
]>
>>> ringo.group_set.all()
]>
>>> m2 = Membership.objects.create(
... person=paul,
... group=beatles,
... date_joined=date(1960, 8, 1),
... invite_reason="Wanted to form a band.",
... )
>>> beatles.members.all()
, ]>
```
You can also use [`add()`](/pt-br/4.2/ref/models/relations/#django.db.models.fields.related.RelatedManager.add),
[`create()`](/pt-br/4.2/ref/models/relations/#django.db.models.fields.related.RelatedManager.create), or
[`set()`](/pt-br/4.2/ref/models/relations/#django.db.models.fields.related.RelatedManager.set) to create
relationships, as long as you specify `through_defaults` for any required
fields:
```pycon
>>> beatles.members.add(john, through_defaults={"date_joined": date(1960, 8, 1)})
>>> beatles.members.create(
... name="George Harrison", through_defaults={"date_joined": date(1960, 8, 1)}
... )
>>> beatles.members.set(
... [john, paul, ringo, george], through_defaults={"date_joined": date(1960, 8, 1)}
... )
```
You may prefer to create instances of the intermediate model directly.
If the custom through table defined by the intermediate model does not enforce
uniqueness on the `(model1, model2)` pair, allowing multiple values, the
[`remove()`](/pt-br/4.2/ref/models/relations/#django.db.models.fields.related.RelatedManager.remove) call will
remove all intermediate model instances:
```pycon
>>> Membership.objects.create(
... person=ringo,
... group=beatles,
... date_joined=date(1968, 9, 4),
... invite_reason="You've been gone for a month and we miss you.",
... )
>>> beatles.members.all()
, , ]>
>>> # This deletes both of the intermediate model instances for Ringo Starr
>>> beatles.members.remove(ringo)
>>> beatles.members.all()
]>
```
The [`clear()`](/pt-br/4.2/ref/models/relations/#django.db.models.fields.related.RelatedManager.clear)
method can be used to remove all many-to-many relationships for an instance:
```pycon
>>> # Beatles have broken up
>>> beatles.members.clear()
>>> # Note that this deletes the intermediate model instances
>>> Membership.objects.all()
```
Once you have established the many-to-many relationships, you can issue
queries. Just as with normal many-to-many relationships, you can query using
the attributes of the many-to-many-related model:
```pycon
# Find all the groups with a member whose name starts with 'Paul'
>>> Group.objects.filter(members__name__startswith="Paul")
]>
```
As you are using an intermediate model, you can also query on its attributes:
```pycon
# Find all the members of the Beatles that joined after 1 Jan 1961
>>> Person.objects.filter(
... group__name="The Beatles", membership__date_joined__gt=date(1961, 1, 1)
... )
```
If you need to access a membership’s information you may do so by directly
querying the `Membership` model:
```pycon
>>> ringos_membership = Membership.objects.get(group=beatles, person=ringo)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'
```
Another way to access the same information is by querying the
[many-to-many reverse relationship](/pt-br/4.2/topics/db/queries/#m2m-reverse-relationships) from a
`Person` object:
```pycon
>>> ringos_membership = ringo.membership_set.get(group=beatles)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'
```
#### One-to-one relationships
Para definir um relacionamento um-para-um, use a [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField). Você pode usar como qualquer outro tipo `Field`: incluindo-o como um atributo de classe do seu modelo.
Isso é mais útil na chave-primária de um objeto quando este objeto “estende” um outro objeto de alguma maneira.
A [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) requer um argumento posicional: a classe com a qual o modelo é relacionado.
Por exemplo, se você estiver construindo um banco de dados de “places”, você pode construir coisas bem padrão tal como endereços, número de telefone, etc. no banco de dados. Então se quiser construir um banco de dados de restaurantes baseado nos lugares, ao invés de repetir a si mesmo e replicar aqueles campos no modelo `Restaurant`, você pode fazer `Restaurant` ter um [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) para `Place` ( porque um restaurante “é um” lugar; de fato, para lidar com isso você poderia tipicamente usar [herança](#model-inheritance), a qual envolve uma relação um-para-um implícita).
Assim como a [`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey), um [relacionamento recursivo](/pt-br/4.2/ref/models/fields/#recursive-relationships) pode ser definido e [referencia a modelos ainda não definidos](/pt-br/4.2/ref/models/fields/#lazy-relationships) pode ser feita.
> **See also**
>
> Veja [exemplo de modelo com relacionamento um-para-um](/pt-br/4.2/topics/db/examples/one_to_one/) para um exemplo completo.
Os campos [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) também aceitam um argumento opcional [`parent_link`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField.parent_link).
Classes [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) usados para automaticamente se tornar a chave-primária de um modelo. Isso não e mais verdade (embora você possa passar manualmente no argumento attr:~django.db.models.Field.primary\_key se quiser). Então, agora é possível ter múltiplos campos de tipos [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) em um único modelo.
### Modelos através de arquivos
It’s perfectly OK to relate a model to one from another app. To do this, import
the related model at the top of the file where your model is defined. Then,
refer to the other model class wherever needed. For example:
```
from django.db import models
from geography.models import ZipCode
class Restaurant(models.Model):
# ...
zip_code = models.ForeignKey(
ZipCode,
on_delete=models.SET_NULL,
blank=True,
null=True,
)
```
### Restrições de nomes de campos
Django places some restrictions on model field names:
1. A field name cannot be a Python reserved word, because that would result
in a Python syntax error. For example:
```text
class Example(models.Model):
pass = models.IntegerField() # 'pass' is a reserved word!
```
2. Um nome de campo não pode conter mais de um “underscore” em uma linha, devido a maneira como a sintaxe dos filtros de pesquisa do Django funcionam.
```
class Example(models.Model):
foo__bar = models.IntegerField() # 'foo__bar' has two underscores!
```
3. A field name cannot end with an underscore, for similar reasons.
Essas limitações podem ser contornadas, embora, porque seu nome de campo não tem que combinar necessariamente com os nomes de colunas dos banco de dados. Veja a opção [`db_column`](/pt-br/4.2/ref/models/fields/#django.db.models.Field.db_column).
Palavras-reservadas SQL, tal como `join`, `where` ou `select`, *são* permitidas como um nome de campos de modelo, porque o Django escapa todos os nomes de colunas e tabelas do banco de dados em cada consulta SQL. Ele usa a sintaxe citada do “engine” do seu banco de dados em particular.
### Tipos de campo personalizados
Se um dos campos de modelo existentes não pode ser usado para atender seus propósitos, ou se você deseja tirar vantagem de algum tipo de coluna de banco de dados menos comum, você pode criar sua própria classe de campo. Uma cobertura completa de criar seus próprios campos é fornecido em [Como criar campos de modelo customizado](/pt-br/4.2/howto/custom-model-fields/).
## Opções `Meta`
Dê ao seu modelo meta-dados usando uma `class Meta` interna, como segue:
```
from django.db import models
class Ox(models.Model):
horn_length = models.IntegerField()
class Meta:
ordering = ["horn_length"]
verbose_name_plural = "oxen"
```
Meta-dado de modelo é “qualquer coisa que não é um campo”, assim como opções de ordenamento ([`ordering`](/pt-br/4.2/ref/models/options/#django.db.models.Options.ordering)), nome da tabela do banco de dados ([`db_table`](/pt-br/4.2/ref/models/options/#django.db.models.Options.db_table)), ou nomes legíveis plural e singular ([`verbose_name`](/pt-br/4.2/ref/models/options/#django.db.models.Options.verbose_name) and [`verbose_name_plural`](/pt-br/4.2/ref/models/options/#django.db.models.Options.verbose_name_plural)). Nenhum é requierido, e adicionar `class Meta` ao seu modelo é completamente opcional.
Uma lista completa de todos as opções `Meta` possíveis pode ser encontrada na [referência de opções de modelo](/pt-br/4.2/ref/models/options/).
## Atributos de modelo
**`objetos`**
O atributo mais importante de uma classe de modelo é o [`Manager`](/pt-br/4.2/topics/db/managers/#django.db.models.Manager). Ele é a interface através da qual o operações de consultas no banco de dados são fornecidas aos modelos do Django e usadas para [retornar instâncias de modelos](/pt-br/4.2/topics/db/queries/#retrieving-objects) do banco de dados. Se nenhum `Manager` personalizado é definido, o nome padrão é [`objects`](/pt-br/4.2/ref/models/class/#django.db.models.Model.objects). Os “managers” somente são acessíveis através de classes de modelos, não por instâncias de de modelos.
## Métodos de Modelos
Defina métodos personalizados em um modelo para adicionar funcionalidade de “nível de linha” personalizado a seus objetos. Enquanto que os métodos [`Manager`](/pt-br/4.2/topics/db/managers/#django.db.models.Manager) são para coisas para “toda a tabela”, métodos de modelos devem agir sobre uma intância de modelo em particular.
Esta é uma técnica valiosa para manter a lógica de negócios em um único lugar – o modelo.
Por exemplo, este modelo tem alguns poucos métodos personalizados:
```
from django.db import models
class Person(models.Model):
first_name = models.CharField(max_length=50)
last_name = models.CharField(max_length=50)
birth_date = models.DateField()
def baby_boomer_status(self):
"Returns the person's baby-boomer status."
import datetime
if self.birth_date < datetime.date(1945, 8, 1):
return "Pre-boomer"
elif self.birth_date < datetime.date(1965, 1, 1):
return "Baby boomer"
else:
return "Post-boomer"
@property
def full_name(self):
"Returns the person's full name."
return f"{self.first_name} {self.last_name}"
```
O último métodos neste exemplo é uma [propriedade](/pt-br/4.2/glossary/#term-property).
A [refrência de instância de modelo](/pt-br/4.2/ref/models/instances/) tem um lista completa de [métodos automaticamente dados a cada modelos](/pt-br/4.2/ref/models/instances/#model-instance-methods). Você pode sobrescrever a maioria deles – veja [sobrescrevendo métodos pré-definidos de modelo](#overriding-predefined-model-methods), abaixo – mas existem alguns que você irá quase sempre querer definir:
**[`__str__()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.__str__)**
A Python “magic method” that returns a string representation of any
object. This is what Python and Django will use whenever a model
instance needs to be coerced and displayed as a plain string. Most
notably, this happens when you display an object in an interactive
console or in the admin.
Você sempre irá querer definir este método; o padrão em geral não ajuda muito.
**[`get_absolute_url()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.get_absolute_url)**
Este dia ao Django como calcular a URL de um objeto. O Django usa isso na sua interface do “admin” e a qualquer momento que ele precisa descobrir a URL de um objeto.
Qualquer objeto que tem um URL que o identifica unicamente deve definir este método.
### Sobrescrevendo métodos pré-definidos de modelo.
Existe um outro conjunto de [métodos de modelos](/pt-br/4.2/ref/models/instances/#model-instance-methods) que encapsulam vários comportamentos ligados ao banco de dados que você irá querer personalizar. EM particu;ar você irá querer muitas vezes alterar a maneira que o [`save()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.save) e [`delete()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.delete) funcionam.
Você é livre para sobrescrever estes métodos (e qualquer outro método de modelo) para alterar o comportamento.
Um caso de uso clássico para sobrescrever métodos embutidos é se você quiser que algo aconteça quando salvar um objeto. Por exemplo (veja [`save()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.save) para a documentaçao dos parâmetros que ele aceita):
```
from django.db import models
class Blog(models.Model):
name = models.CharField(max_length=100)
tagline = models.TextField()
def save(self, *args, **kwargs):
do_something()
super().save(*args, **kwargs) # Call the "real" save() method.
do_something_else()
```
Você pode também evitar salvar:
```
from django.db import models
class Blog(models.Model):
name = models.CharField(max_length=100)
tagline = models.TextField()
def save(self, *args, **kwargs):
if self.name == "Yoko Ono's blog":
return # Yoko shall never have her own blog!
else:
super().save(*args, **kwargs) # Call the "real" save() method.
```
It’s important to remember to call the superclass method – that’s
that `super().save(*args, **kwargs)` business – to ensure
that the object still gets saved into the database. If you forget to
call the superclass method, the default behavior won’t happen and the
database won’t get touched.
É importante também que você passe os argumentos que podem ser passados para o método do modelo que é o que as partes \*args, \*\*kwargs fazem. O Django irá, de vez enquando, estender as capacidades dos métodos embutidos de modelo, adicionando novos argumento. Se você usar `*args, **kwargs` nas definições de seus métodos, você está garantido que seu código ira automaticamente da suporte a estes argumentos quando forem adicionados.
If you wish to update a field value in the [`save()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.save) method, you may
also want to have this field added to the `update_fields` keyword argument.
This will ensure the field is saved when `update_fields` is specified. For
example:
```
from django.db import models
from django.utils.text import slugify
class Blog(models.Model):
name = models.CharField(max_length=100)
slug = models.TextField()
def save(
self, force_insert=False, force_update=False, using=None, update_fields=None
):
self.slug = slugify(self.name)
if update_fields is not None and "name" in update_fields:
update_fields = {"slug"}.union(update_fields)
super().save(
force_insert=force_insert,
force_update=force_update,
using=using,
update_fields=update_fields,
)
```
See [Specifying which fields to save](/pt-br/4.2/ref/models/instances/#ref-models-update-fields) for more details.
> **Métodos de modelos sobrescritos não são chamados em operações em massa.**
>
> Note que o métodos [`delete()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.delete) não é necessariamente chamado quando [deletar objetos em massa usando QUerySet](/pt-br/4.2/topics/db/queries/#topics-db-queries-delete) ou como resultado de uma [`deleção em cascata`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.on_delete). Para se assegurar que a lógica de um “delete” personalizado será executada, você pode usar os sinais [`pre_delete`](/pt-br/4.2/ref/signals/#django.db.models.signals.pre_delete) e/ou [`post_delete`](/pt-br/4.2/ref/signals/#django.db.models.signals.post_delete) signals.
>
> Infelizmente não tem uma solução alternativa quando o [`creating`](/pt-br/4.2/ref/models/querysets/#django.db.models.query.QuerySet.bulk_create) ou [`updating`](/pt-br/4.2/ref/models/querysets/#django.db.models.query.QuerySet.update) objetos em massa, já que nenhum dos [`save()`](/pt-br/4.2/ref/models/instances/#django.db.models.Model.save), [`pre_save`](/pt-br/4.2/ref/signals/#django.db.models.signals.pre_save), e [`post_save`](/pt-br/4.2/ref/signals/#django.db.models.signals.post_save) são chamados.
### Executando SQL personalizado
Um outro padrão comum é escrever comandos SQL personalizados em métodos de modelos e métodos no nível do módulo. Para mais detalhes sobre usar SQL puro, veja a documentação no [usando SQL puro](/pt-br/4.2/topics/db/sql/).
## Herança de modelo
A herança de modelo no Django funciona quase idêntico a maneira que herança de classes normais no Python, mas o básico do início da página ainda deve ser seguido. Isso significa que c classe base deve ser uma subclasse de [`django.db.models.Model`](/pt-br/4.2/ref/models/instances/#django.db.models.Model).
A única decisão que você tem tomar é se você quer que os modelos pais sejam modelos por eles mesmos (com suas próprias tabelas de banco de dados), ou se os modelos parentes são somente para manter informações comuns que somente serão vistas através de seus modelos filhos.
Existem três estilos de herança que possíveis em Django.
1. Muitas vezes, você quer somente usar uma classe pai para manter informação que você não quer ter que escrever para cada modelo filho. Essa classe nunca será usada isoladamente, então o que você quer é uma [Classes abstratas base](#abstract-base-classes)
2. Se você estiver herdando um modelo existente (talvez algo de uma outra aplicação inteira) e quer que cada modelo tenha sua própria tabela de banco de dados, o [Herança de múltiplas tabelas](#multi-table-inheritance) é o caminho.
3. Finalmente, se você quer modificar o comportamento no nível do Python de um modelo, sem mudar os campos do modelo de nenhuma maneira, você pode usar os [Modelos Proxy](#proxy-models).
### Classes abstratas base
Abstract base classes are useful when you want to put some common
information into a number of other models. You write your base class
and put `abstract=True` in the [Meta](#meta-options)
class. This model will then not be used to create any database
table. Instead, when it is used as a base class for other models, its
fields will be added to those of the child class.
Um exemplo:
```
from django.db import models
class CommonInfo(models.Model):
name = models.CharField(max_length=100)
age = models.PositiveIntegerField()
class Meta:
abstract = True
class Student(CommonInfo):
home_group = models.CharField(max_length=5)
```
O modelo `Student` terá três campos: `name`, `age` e `home_group`. O modelo `CommonInfo` não pode ser usado como um modelo normal do Django, já que é uma classe abstrata base. Ele não gera uma tabela de banco de dados nem tem um “manager”, e não pode ser instânciado ou salvo diretamente.
Fields inherited from abstract base classes can be overridden with another
field or value, or be removed with `None`.
Em muitos casos, este tipo de herança de modelo será exatamente o que quer. Isso lhe fornece uma maneira de fatorar informações comuns ao nível do Python, enquanto cainda cria somente uma tabela de banco de dados para cada modelo filho no nível banco de dados.
#### Herança `Meta`
QUando um modelo abstrato básico é criado, o Django com que qualquer classe [Meta](#meta-options) interna que você declare na classe base fique disponível como um atributo. Se a classe filha não declare sua própria classe [Meta](#meta-options) , ela irá herdar as [Meta](#meta-options) da pai. Se a filho quer estender a classe [Meta](#meta-options) da pai, ele pode herdá-la. Por exemplo:
```
from django.db import models
class CommonInfo(models.Model):
# ...
class Meta:
abstract = True
ordering = ["name"]
class Student(CommonInfo):
# ...
class Meta(CommonInfo.Meta):
db_table = "student_info"
```
Django does make one adjustment to the [Meta](#meta-options) class of an
abstract base class: before installing the [Meta](#meta-options)
attribute, it sets `abstract=False`. This means that children of abstract
base classes don’t automatically become abstract classes themselves. To make
an abstract base class that inherits from another abstract base class, you need
to explicitly set `abstract=True` on the child.
Alguns atributos não farão sentido incluir na classe [Meta](#meta-options) de uma classe abstrata base. Por exemplo, incluir `db_table` poderia siginificar que todas as classes filhos (aquelas que não especificarem seus próprios [Meta](#meta-options)) poderiam usar a mesma tabela, o que é quase certo que não é o que você quer.
Due to the way Python inheritance works, if a child class inherits from
multiple abstract base classes, only the [Meta](#meta-options) options
from the first listed class will be inherited by default. To inherit [Meta](#meta-options) options from multiple abstract base classes, you must
explicitly declare the [Meta](#meta-options) inheritance. For example:
```
from django.db import models
class CommonInfo(models.Model):
name = models.CharField(max_length=100)
age = models.PositiveIntegerField()
class Meta:
abstract = True
ordering = ["name"]
class Unmanaged(models.Model):
class Meta:
abstract = True
managed = False
class Student(CommonInfo, Unmanaged):
home_group = models.CharField(max_length=5)
class Meta(CommonInfo.Meta, Unmanaged.Meta):
pass
```
#### Tenha cuidado com o `related_name` e o `related_query_name`
Se você está usando um [`related_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_name) ou [`related_query_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_query_name) em uma `ForeignKey` ou `ManyToManyField`, você deve sempre especificar um nome reverso e nome de consulta *único* para o campo. Isso deve normalmente causar um problema na classe abstrata base, já que os campos desta classe são inc;uídos em cada um das classes filhas, com exatamente os mesmos valores de atributos (incluindo o [`related_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_name) e [`related_query_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_query_name)) toda vez.
Para contornar o problema, quando usar o [`related_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_name) ou [`related_query_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_query_name) em uma classe abstrata (somente), parte do valor deve conter `'%(app_label)s'` e `'%(class)s'`.
- `'%(class)s'` is replaced by the lowercased name of the child class that
the field is used in.
- `'%(app_label)s'` is replaced by the lowercased name of the app the child
class is contained within. Each installed application name must be unique and
the model class names within each app must also be unique, therefore the
resulting name will end up being different.
Por exemplo, dado uma aplicação `common/models.py`:
```
from django.db import models
class Base(models.Model):
m2m = models.ManyToManyField(
OtherModel,
related_name="%(app_label)s_%(class)s_related",
related_query_name="%(app_label)s_%(class)ss",
)
class Meta:
abstract = True
class ChildA(Base):
pass
class ChildB(Base):
pass
```
Junta com uma outra aplicação `rare/models.py`:
```
from common.models import Base
class ChildB(Base):
pass
```
The reverse name of the `common.ChildA.m2m` field will be
`common_childa_related` and the reverse query name will be `common_childas`.
The reverse name of the `common.ChildB.m2m` field will be
`common_childb_related` and the reverse query name will be
`common_childbs`. Finally, the reverse name of the `rare.ChildB.m2m` field
will be `rare_childb_related` and the reverse query name will be
`rare_childbs`. It’s up to you how you use the `'%(class)s'` and
`'%(app_label)s'` portion to construct your related name or related query name
but if you forget to use it, Django will raise errors when you perform system
checks (or run [`migrate`](/pt-br/4.2/ref/django-admin/#django-admin-migrate)).
Se você não especificar um atributo [`related_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_name) para um campo campo na classe abstrata, o nome reverso padrão será o nomde da classe filha seguido por `'_set'`, tal como seria normalmente se o campo fosse declarado diratamente na classe filha. Por exemplo, no código acima, se o atributo [`related_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_name) fosse omitido, o nome reverso para o campo `m2m` seriaa `childa_set` no caso `ChildA` e `childb_set` para o campo `ChildB`.
### Herança de múltiplas tabelas
O segundo tipo de heraná de modelo que o Django suporta é quando cada modelo na hierarquia é um modelo completo. Cada modelo corresponder a sua própria tabele de banco de dados e pode ser consultado e criado individualmente. A herança de relacionamento introduz conexões entre a classe filho e cada um de seus parentes (através de um [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) criado automaticamente). Por exemplo:
```
from django.db import models
class Place(models.Model):
name = models.CharField(max_length=50)
address = models.CharField(max_length=80)
class Restaurant(Place):
serves_hot_dogs = models.BooleanField(default=False)
serves_pizza = models.BooleanField(default=False)
```
All of the fields of `Place` will also be available in `Restaurant`,
although the data will reside in a different database table. So these are both
possible:
```pycon
>>> Place.objects.filter(name="Bob's Cafe")
>>> Restaurant.objects.filter(name="Bob's Cafe")
```
If you have a `Place` that is also a `Restaurant`, you can get from the
`Place` object to the `Restaurant` object by using the lowercase version of
the model name:
```pycon
>>> p = Place.objects.get(id=12)
# If p is a Restaurant object, this will give the child class:
>>> p.restaurant
```
Todavia, se `p` no exemplo acima *não* é um `Restaurant` (ele foi criado diretamente como um objeto `Place` ou era um pai de uma alguma outra classe), referenciar `p.restaurant` poderia emitir uma exceção `Restaurante.DoeNotExist`.
The automatically-created [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) on
`Restaurant` that links it to `Place` looks like this:
```
place_ptr = models.OneToOneField(
Place,
on_delete=models.CASCADE,
parent_link=True,
primary_key=True,
)
```
You can override that field by declaring your own
[`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) with [`parent_link=True`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField.parent_link) on `Restaurant`.
#### `Meta` e herança de tabelas múltiplas
Na situação de herança de multi-tabelas , faz sentido para uma classe filho herdar de seu pai a classe [Meta](#meta-options). Todas as opções [Meta](#meta-options) já foram aplicadas a classe pai aplicar novamente poderia normalmente levar a um comprtamento contraditório (isso em contrate com o caso da classe abstrata base, onde a classe base não existe por sí só).
Então um modelo filho não tem acesso a classe [Meta](#meta-options) do seu pai. Porém, existem alguns poucos casos onde o filho herda comportamento do pai: se o filho não especifica um atributo [`ordering`](/pt-br/4.2/ref/models/options/#django.db.models.Options.ordering) ou um atributo [`get_latest_by`](/pt-br/4.2/ref/models/options/#django.db.models.Options.get_latest_by), ele herdará isso dos seu pai.
Se o pai tem um ordenação e você não quer que o filho tenha qualquer ordem natural, você pode explicitamente desabilitar isso:
```
class ChildModel(ParentModel):
# ...
class Meta:
# Remove parent's ordering effect
ordering = []
```
#### Herança e relações reversas
Porque herança de multi-tabelas usa um [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) implícita para relacionar o filho com o pai, é possível mover do pai para o filho, como no exemplo acima. Porém, usa-se o nome que é padrão value do [`related_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_name) para [`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey) e relções [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField). Se você está colocando estes tipos de relações em uma subclasse do modelo pai, você **deve** especificar o atributo [`related_name`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey.related_name) em cada campo deste. Se você esquecer, o Django irá emitir um erro de validação.
Por exemplo, usando novamente a classe `Place` acima, vamos criar outra subclasse com um [`ManyToManyField`](/pt-br/4.2/ref/models/fields/#django.db.models.ManyToManyField):
```
class Supplier(Place):
customers = models.ManyToManyField(Place)
```
This results in the error:
```pytb
Reverse query name for 'Supplier.customers' clashes with reverse query
name for 'Supplier.place_ptr'.
HINT: Add or change a related_name argument to the definition for
'Supplier.customers' or 'Supplier.place_ptr'.
```
Adicionando `related_name` ao campo `customers` como segue poderia resolver o erro: `models.ManyToManyField(Place, related_name='provider')`.
#### Especificando o campo de relacão do pai
Como mencionado, o Django criará automaicamente uma relação [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) para sua classe filho devolta para quaisquer modelos não abstratos. Se quiser controlar o nome do atributo de relacionamento devolta para o pai, você pode criar seu próprio [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) e definir [`parent_link=True`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField.parent_link) para indicar que seu campo é a conexão de reotorno com a classe pai.
### Modelos Proxy
Quando se usa [herança de tabelas multiplas](#multi-table-inheritance), uma nova tabela de banco de dados é criada para cada subclasse do modelo. Este é o comportamento desejável, já que a subclasse precisa de um lugar para armazenar qualquer campo de dado adicional que não esteja presente na classe base. As vezes, entretanto, você quer somente mudar o comportamento Python do modelo – talvez para alterar o “manager” padrão do modelo, ou adicionar um método novo.
É para isso que serve o modelo “proxy”: criar um *proxy* para o modelo original. Você pode criar, deletar e editar instâncias do modelo “proxy” e todas os dados serão salvos como se você estivesse usando o modelo original (não “proxy”). A diferença, é que você pode alterar coisas como a ordenação padrão do modelo ou o “manager” padrão no “proxy”, sem ter que alterar o original.
Modelos “Proxy” são declarados como os modelos normais. Você diz ao Django que este é um modelo “proxy” definindo o atributo [`proxy`](/pt-br/4.2/ref/models/options/#django.db.models.Options.proxy) na classe `Meta` como `True`.
Por exemplo, suponha que queira adicionar um método ao modelo `Person`. Você pode fazê-lo assim:
```
from django.db import models
class Person(models.Model):
first_name = models.CharField(max_length=30)
last_name = models.CharField(max_length=30)
class MyPerson(Person):
class Meta:
proxy = True
def do_something(self):
# ...
pass
```
The `MyPerson` class operates on the same database table as its parent
`Person` class. In particular, any new instances of `Person` will also be
accessible through `MyPerson`, and vice-versa:
```pycon
>>> p = Person.objects.create(first_name="foobar")
>>> MyPerson.objects.get(first_name="foobar")
```
You could also use a proxy model to define a different default ordering on
a model. You might not always want to order the `Person` model, but regularly
order by the `last_name` attribute when you use the proxy:
```
class OrderedPerson(Person):
class Meta:
ordering = ["last_name"]
proxy = True
```
Agora consultas normais ao `Person` serão não ordenadas e consultas ao `OrderedPerson` serão ordenadas pelo `last_name`.
Proxy models inherit `Meta` attributes [in the same way as regular
models](#meta-and-multi-table-inheritance).
#### `QuerySet`s ainda retornam o modelo que foi requisitado
Não te uma maneira do Django retornar, vamos dizer, um objeto `MyPerson` quando consultar por objetos `Person`. Uma consulta em objetos `Person` irá retornar aquele tipo de objetos. O ponto de objetos “proxy” é que o código que está no `Person` original irá usar este código e seu próprio código pode usar as estensões que foram incluídas (que nenhum outro código depende de nenhuma forma). Esta não é uma maneira de substituir o modelo `Person` (ou nenhum outro) em nenhum lugar com alguma coisa criada por você mesmo.
#### Restições de classes base
Um modelo “proxy” deve herdar de exatamente uma classe de modelo não abstrato. Você não pode herdar de múltiplos modelos não abstratos já que o modelo “proxy” não ofrnece qualquer conexão entre as linhas nas diferentes tabelas do banco de dados. Um modelo proxy pode herdar de qualquer número de modelo de classe abstrata, desde que *não* definam campos de modelo. Um modelo proxy também pode herdar qualquer número de modelos proxy que compartilhem uma classe pai não abstrata em comum.
#### “Managers” de modelos “proxy”
Se você não especificar um “manager” do modelo no modelo “proxy”, ele herda o “manager” de seu modelo pai. Se você definir um “manager” no modelo “proxy”, este será o padrão, embora qualquer “manager” definido nas classes pai ainda estarão disponíveis.
Continuando nosso exemplo acima, você pode mudar o “manager” padrão usado quando você fizer uma consulta ao modelo `Person` assim:
```
from django.db import models
class NewManager(models.Manager):
# ...
pass
class MyPerson(Person):
objects = NewManager()
class Meta:
proxy = True
```
Se você quiser adicionar um novo “manager” ao “Proxy”, sem substituir o padrão existente, você pode usar as técnicas descritas na documentação [“manager” personalizado](/pt-br/4.2/topics/db/managers/#custom-managers-and-inheritance) : crie uma classe base contendo os novos “managers” e herde esta depois da classe base primária:
```
# Create an abstract class for the new manager.
class ExtraManagers(models.Model):
secondary = NewManager()
class Meta:
abstract = True
class MyPerson(Person, ExtraManagers):
class Meta:
proxy = True
```
Você provavelmente não precisa fazer isso muitas vezes, mas, quando precisar, é possível.
#### Differences between proxy inheritance and unmanaged models
Proxy model inheritance might look fairly similar to creating an unmanaged
model, using the [`managed`](/pt-br/4.2/ref/models/options/#django.db.models.Options.managed) attribute on a
model’s `Meta` class.
With careful setting of [`Meta.db_table`](/pt-br/4.2/ref/models/options/#django.db.models.Options.db_table) you could create an unmanaged model that
shadows an existing model and adds Python methods to it. However, that would be
very repetitive and fragile as you need to keep both copies synchronized if you
make any changes.
On the other hand, proxy models are intended to behave exactly like the model
they are proxying for. They are always in sync with the parent model since they
directly inherit its fields and managers.
The general rules are:
1. Se você esta espelhando um modelo existente ou uma tabela de banco de dados e nao quer todas as colunas originarias do banco de dados, use `Meta.managed=False`. Esta opção é normalmente útil para modelos “views” e tabelas de bancos de dados que não estão sob o controle do Django.
2. Se voc^está querendo alterar o modelo somente quanto seu comportamento Python, más manter todos os mesmos campos como no original, use `Meta.proxy=True`. Estas defini as coisas tal que o modelo “proxy” é uma cópia exata da estrutura de armazenamento do modelo original quando o dado são salvos.
### Herança Múltimpla
Tal como é fazer uma subclasse em Python, é possível para um modelo Django herdar múltiplos modelos pai. Tenha em mente que as regras de resolução de nomes Python se aplicam. A primeira classe base que um nome em particular (e.x. [Meta](#meta-options)) aparece será a classe usada; por exemplo, isso significa que se múltiplos pais contém uma classe [Meta](#meta-options), somente a primeira é que será usada, e todas as outras ignoradas.
Geralmente, você não vai precisar herdar de múltiplos pais. O principal caso onde isso é útil é para classes “mix-in”: adicionar um campo extra em particular ou método para ada classe que herda o “mix-in”. Tente manter sua hierarquia de herança tão simples e direta quanto possível, assim você não tem que lutar para descobrir de onde está vindo uma parte particuar da informação.
Perceba que herdar de múltiplos modelos que tem em comum um campo `id` como chave-primária irá emitir um erro. Para usar herança múltipla de maneira correta, você pode usar explicitamente a [`AutoField`](/pt-br/4.2/ref/models/fields/#django.db.models.AutoField) no modelo base:
```
class Article(models.Model):
article_id = models.AutoField(primary_key=True)
...
class Book(models.Model):
book_id = models.AutoField(primary_key=True)
...
class BookReview(Book, Article):
pass
```
Or use a common ancestor to hold the [`AutoField`](/pt-br/4.2/ref/models/fields/#django.db.models.AutoField). This
requires using an explicit [`OneToOneField`](/pt-br/4.2/ref/models/fields/#django.db.models.OneToOneField) from each
parent model to the common ancestor to avoid a clash between the fields that
are automatically generated and inherited by the child:
```
class Piece(models.Model):
pass
class Article(Piece):
article_piece = models.OneToOneField(
Piece, on_delete=models.CASCADE, parent_link=True
)
...
class Book(Piece):
book_piece = models.OneToOneField(Piece, on_delete=models.CASCADE, parent_link=True)
...
class BookReview(Book, Article):
pass
```
### O nome de campo “hiding” não é permitido.
In normal Python class inheritance, it is permissible for a child class to
override any attribute from the parent class. In Django, this isn’t usually
permitted for model fields. If a non-abstract model base class has a field
called `author`, you can’t create another model field or define
an attribute called `author` in any class that inherits from that base class.
This restriction doesn’t apply to model fields inherited from an abstract
model. Such fields may be overridden with another field or value, or be removed
by setting `field_name = None`.
> **Warning**
>
> Model managers are inherited from abstract base classes. Overriding an
> inherited field which is referenced by an inherited
> [`Manager`](/pt-br/4.2/topics/db/managers/#django.db.models.Manager) may cause subtle bugs. See [custom
> managers and model inheritance](/pt-br/4.2/topics/db/managers/#custom-managers-and-inheritance).
> **Note**
>
> Some fields define extra attributes on the model, e.g. a
> [`ForeignKey`](/pt-br/4.2/ref/models/fields/#django.db.models.ForeignKey) defines an extra attribute with
> `_id` appended to the field name, as well as `related_name` and
> `related_query_name` on the foreign model.
>
> These extra attributes cannot be overridden unless the field that defines
> it is changed or removed so that it no longer defines the extra attribute.
Sobrescrever campos em um modelo pai leva a dificuldades em áreas como a inicialização de novas instâncias (especificar qual campo está sendo inicializado no `Model.__init__`) e serialização. Estas são características que classes Python normais não tem que lidar do mesmo modo, isso quer dizer que a diferença entre herança de modelos Django e herança de classes Python não são arbitrárias.
A restrição somente se aplica a atributos os quais são instâncias de [`Field`](/pt-br/4.2/ref/models/fields/#django.db.models.Field). Atributos normais de Python podem ser sobrescritos se quiser. Isos também só se aplica para os nomes de atributos com o Python os vê. Se você está manualmente especificando o nome da coluna do banco de dados, você pode ter o mesmo nome de coluna aparecendo em ambos, um filho e em um modelo ancestral para heraná de múltiplas tabelas (elas são solunas em duas diferentes tabelas de banco de dados).
O Django irá emitir uma [`FieldError`](/pt-br/4.2/ref/exceptions/#django.core.exceptions.FieldError) se você sobrescrever qualquer campo de modelo de qualquer modelo ancestral.
Note that because of the way fields are resolved during class definition, model
fields inherited from multiple abstract parent models are resolved in a strict
depth-first order. This contrasts with standard Python MRO, which is resolved
breadth-first in cases of diamond shaped inheritance. This difference only
affects complex model hierarchies, which (as per the advice above) you should
try to avoid.
## Organizing models in a package
The [`manage.py startapp`](/pt-br/4.2/ref/django-admin/#django-admin-startapp) command creates an application
structure that includes a `models.py` file. If you have many models,
organizing them in separate files may be useful.
To do so, create a `models` package. Remove `models.py` and create a
`myapp/models/` directory with an `__init__.py` file and the files to
store your models. You must import the models in the `__init__.py` file.
For example, if you had `organic.py` and `synthetic.py` in the `models`
directory:
*`myapp/models/__init__.py`*
```python
from .organic import Person
from .synthetic import Robot
```
Explicitly importing each model rather than using `from .models import *`
has the advantages of not cluttering the namespace, making code more readable,
and keeping code analysis tools useful.
> **See also**
>
> **[Referência sobre Modelos](/pt-br/4.2/ref/models/)**
>
> Cobre toda a API relacionada com modelo incluindo campos de modelo, objetos relacionais, e `QuerySet`.