/ /

Backend do Django MongoDB

Dados do modelo

Página inicial do Docs

Bibliotecas do cliente

Python

Backend do Django MongoDB

Dados do modelo

Crie modelos para representar coleções

Visão geral

Neste guia, você pode aprender como criar modelos Django que representam coleções MongoDB . Modelos são classes do Python que definem a estrutura dos seus dados. Ao usar o Django MongoDB Backend, você pode mapear cada modelo para uma coleção MongoDB e interagir com os documentos da coleção usando objetos de modelo.

Dica

Para saber mais sobre os modelos do Django, consulte Model na documentação do Django.

Campos suportados

Esta seção descreve o suporte do Django MongoDB Backend para os seguintes campos, que você pode incluir em seus modelos:

Campos do Django
Campos JSON do MongoDB

Campos do Django

A tabela a seguir descreve os campos de modelo do Django que o Django MongoDB Backend suporta:

tipo de campo	Descrição
`BinaryField`	Armazena dados binários brutos.
`BooleanField`	Armazena valores booleanos (`True` ou `False`).
`CharField`	Armazena valores de string. Para armazenar valores de texto mais longos, utilize `TextField`.
`DateField`	Armazena valores de data em instâncias do Python `datetime.date`.
`DateTimeField`	Armazena valores de data e hora em instâncias do Python `datetime.datetime`.
`DecimalField`	Armazena valores decimais.
`DurationField`	Armazena valores representando períodos de tempo em instâncias do Python `timedelta`.
`EmailField`	Armazena `CharField` valores e utiliza um para verificar se o valor é um endereço de `EmailValidator` e-mail.
`FileField`	Stores file values.
`FilePathField`	Armazena valores `CharField` que representam nomes de arquivos em seu sistema de arquivos.
`FloatField`	Stores float values.
`GenericIPAddressField`	Armazena um endereço IPv4 ou IPv6 no formato de string.
`ImageField`	Armazena um valor `FileField` e verifica se o objeto carregado é uma imagem válida.
`IntegerField` e a `BigIntegerField`	Armazena valores inteiros de até 64 bits de tamanho.
`JSONField`	Armazena dados JSON. Para saber mais sobre este campo, consulte a seção Armazenar Dados JSON neste guia.
`PositiveIntegerField` e a `PositiveBigIntegerField`	Armazena valores inteiros positivos com até 64 bits de tamanho.
`PositiveSmallIntegerField`	Armazena valores inteiros positivos com até 32 bits de tamanho.
`SlugField`	Armazena um rótulo de texto curto, geralmente para valores de URL .
`SmallIntegerField`	Armazena valores inteiros de até 32 bits de tamanho.
`TextField`	Armazena valores de texto grandes.
`URLField`	Armazena um valor `CharField` representando uma URL.
`UUIDField`	Armazena instâncias da classe `UUID` do Python.

Campos JSON do MongoDB

O MongoDB organiza e armazena documentos em uma representação binária chamada BSON que permite o processamento de dados flexível.

Dica

Para saber mais sobre como o MongoDB armazena dados BSON, consulte tipos de BSON no manual do MongoDB Server .

A tabela a seguir descreve os tipos de campo BSON compatíveis e seus equivalentes no Django MongoDB Backend que você pode usar em seus modelos do Django:

Tipo de campo BSON	Tipo de campo de backend do Django MongoDB	Descrição do JSON
`Array`	`ArrayField`	Armazena valores de array. Para saber mais sobre como usar esse campo com o Django MongoDB Backend, consulte a seção Armazenar dados de array neste guia.
`Object`	`EmbeddedModelField` ou `EmbeddedModelArrayField`	Armazena um ou vários documentos incorporados. Para saber mais sobre como usar esses campos com o Django MongoDB Backend, consulte as seções Armazenar dados de modelo incorporados e Armazenar dados de array de modelos incorporados .
`ObjectId`	`ObjectIdField`	Armazena identificadores exclusivos de 12bytes que o MongoDB usa como chaves primárias.
`Binary`	`BinaryField`	Armazena dados binários.
`Boolean`	`BooleanField`	Armazena valores `true` ou `false`.
`Date`	`DatetimeField`	Armazena datas e horas em milissegundos desde a época do Unix, ou janeiro de 1 de 1970.
`Decimal128`	`DecimalField`	Armazena valores decimais de 28bits.
`Double`	`FloatField`	Armazena valores de ponto flutuante.
`Int32`	`SmallIntegerField`	Armazena números inteiros assinados de 32bits.
`Int64`	`IntegerField` ou `BigIntegerField`	Armazena números inteiros assinados de 64bits.
`String`	`CharField` ou `TextField`	Armazena valores de string codificados em UTF-8.

Definir um modelo

Para criar um modelo que represente uma collection do MongoDB , adicione as definições da classe do modelo ao arquivo models.py do aplicativo. Em sua classe de modelo, especifique os campos que você deseja armazenar e inclua quaisquer metadados de modelo em uma classe Meta interna. Você também pode usar o método __str__() para definir a representação de string do seu modelo. Use a seguinte sintaxe para definir um modelo:

 class <Model name>(models.Model):
     <field name> = <data type>
     # Include additional fields here
     class Meta:
         # Include metadata here
     def __str__(self):
         # Include logic for displaying your model as a string here

Dica

Para saber mais sobre as opções de metadados que você pode especificar na classe Meta, consulte Opções de metadados do modelo na documentação do Django.

Para utilizar seus modelos, você deve adicioná-los ao arquivo settings.py do seu projeto. Edite o valor INSTALLED_APPS para incluir o nome do módulo que armazena seu arquivo models.py, conforme mostrado no código a seguir:

 INSTALLED_APPS = [
     '<application module>',
     # Include other app modules here
 ]

Por fim, execute os seguintes comandos de migração de banco de dados a partir do diretório raiz do seu projeto para criar coleções MongoDB para seus modelos ou utilize coleções existentes para armazenar dados do modelo:

python manage.py makemigrations <application name>
python manage.py migrate

Exemplo

Este arquivo models.py de amostra define uma classe de modelo Movie que inclui as seguintes informações:

Lista de campos que representam dados de filme.
Meta classe que define a opção db_table como movies. Isto instrui o Backend do Django MongoDB a utilizar este modelo para representar a sample_mflix.movies coleção do a partir dos conjuntos de dados de amostra do Atlas .

A classe Meta também define a opção managed como False, instruindo o Django MongoDB Backend a não criar uma nova collection para o modelo.
__str__() que define a representação de string do modelo como seu valor de campo title.

from django.db import models
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

Dica

Para saber mais sobre os campos usados na definição da classe de modelo, consulte a seção Campos compatíveis deste guia.

Usar campos avançados

Esta seção mostra como usar os seguintes campos em seus modelos Django:

JSONField
ArrayField
EmbeddedModelField
EmbeddedModelArrayField
Campo PolimórficoEmbeddedModel
PolimórficoEmbeddedModelArrayField

Store JSON Data

Você pode utilizar um JSONField em seu modelo para armazenar objetos JSON. O JSON é um formato legível por humanos para troca de dados, e os objetos JSON são contêineres de dados que mapeiam chaves de string para valores. O MongoDB fornece o tipo de campo Object para armazenar dados JSON em documentos e armazena internamente esses dados no formato BSON ou Binary JSON.

Observação

Você também pode utilizar modelos embarcados e modelos embarcados polimórficos para representar um MongoDB Object.

Exemplo

O exemplo a seguir adiciona um JSONField valor ao modelo criado no exemplo Definir um modelo neste guia. O novo campo, chamado imdb, armazena dados JSON que representam classificações de usuários para cada objeto Movie:

from django.db import models
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    imdb = models.JSONField(null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

Dica

Para aprender como consultar dados armazenados em um JSONField, consulte Consultar Valores JSON no guia Especificar uma query.

Limitações

O suporte do Django MongoDB Backend para JSONField tem as seguintes limitações:

Se você definir o valor do campo como None, o Backend do Django MongoDB armazenará seu valor como um valor SQL NULL. Como alternativa, você pode definir o valor JSONField como Value(None, JSONField()), que representa o null escalar JSON. No entanto, não há como distinguir entre o SQL NULL e o JSON null ao fazer query.
Algumas queries que utilizam objetos Q podem não retornar os resultados esperados, especialmente ao utilizar o método QuerySet.exclude().
Ao executar query de campos que têm um valor de None, o Django MongoDB Backend retorna incorretamente documentos nos quais o campo não existe.

Armazenar dados de array

Você pode utilizar um ArrayField em seu modelo para armazenar uma lista de dados. Para criar um ArrayField, utilize o construtor de classe ArrayField() e passe os seguintes argumentos:

base_field: especifica o tipo de dados subjacente de cada valor armazenado na array. Você não pode especificar EmbeddedModelField ou FileField como o tipo de campo base.
size: (Opcional) Especifica o tamanho máximo da array.
options: (Opcional) Especifica as opções de campo do Django. Para visualizar uma lista de opções disponíveis, consulte Opções de campo na documentação do Django.

Dica

Você pode armazenar uma array de valores de array em um ArrayField usando a seguinte sintaxe:

my_array = ArrayField(
      ArrayField(
          base_field,
          # ... Additional arguments
      ),
)

Exemplo

O exemplo a seguir adiciona um ArrayField valor de ao modelo criado no exemplo Definir um modelo neste guia. O novo campo, chamado genres, armazena uma lista de CharField valores que representam gêneros de filmes e podem armazenar um máximo de 5 valores:

from django.db import models
from django_mongodb_backend.fields import ArrayField
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    genres = ArrayField(
             models.CharField(max_length=100),
             size=5,
             null=True,
             blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

Dica

Para aprender como consultar dados armazenados em um ArrayField, consulte Valores de Matriz de Query no guia Especificar uma query.

Armazenar dados de modelo incorporados

Você pode usar um EmbeddedModelField para representar um MongoDB Object, que armazena um valor de documento aninhado. Este tipo permite que um modelo armazene um modelo separado em um de seus campos. Para criar um EmbeddedModelField, defina uma classe de modelo embarcado como uma subclasse do modelo abstrato EmbeddedModel. Em seguida, crie um campo na classe do modelo base usando o construtor EmbeddedModelField() e passe os seguintes argumentos:

embedded_model: especifica a classe de modelo a ser armazenada.
options: (Opcional) Especifica as opções de campo do Django. Para visualizar uma lista de opções disponíveis, consulte Opções de campo na documentação do Django.

Importante

O comando makemigrations Django não detecta alterações em modelos incorporados. Se você fizer alterações na classe do modelo embarcado, o modelo armazenado no EmbeddedModelField não refletirá as alterações.

Exemplo

Este exemplo adiciona um EmbeddedModelField valor ao modelo criado no exemplo Definir um modelo neste guia. O novo campo, chamado awards, armazena um modelo Award incorporado como seu valor. O seguinte código define o modelo Award e modifica o modelo Movie para incluir o EmbeddedModelField:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import EmbeddedModelField
class Award(EmbeddedModel):
    wins = models.IntegerField(default=0)
    nominations = models.IntegerField(default=0)
    text = models.CharField(max_length=100)
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    awards = EmbeddedModelField(Award, null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

Dica

Para aprender como consultar dados armazenados em um EmbeddedModelField, consulte Consultar Valores de Modelo Incorporados no guia Especificar uma Query.

Armazenar dados de array do modelo incorporado

Você pode usar um EmbeddedModelArrayField para representar um campo de documento do MongoDB que armazena uma array de documentos em um relacionamento de um para muitos. Cada documento na array corresponde a um valor Django MongoDB Backend EmbeddedModelField. Para criar um EmbeddedModelArrayField, utilize o construtor de classe EmbeddedModelArrayField() e passe os seguintes argumentos:

embedded_model: Especifica o modelo armazenado em cada item da array.
max_size: (Opcional) Especifica o tamanho máximo da array.

Exemplo

Este exemplo adiciona um valor EmbeddedModelArrayField ao modelo criado no exemplo Definir um modelo neste guia. Este campo cast armazena uma array de modelos Actor incorporados. O seguinte código define o modelo Actor e modifica o modelo Movie para incluir o EmbeddedModelArrayField:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import EmbeddedModelArrayField
class Actor(EmbeddedModel):
    first_name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)
    role = models.CharField(max_length=100)
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    cast = EmbeddedModelArrayField(Actor, null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

Armazenar dados de modelo incorporado polimórfico

Você pode usar um PolymorphicEmbeddedModelField para representar um campo de documento MongoDB que pode armazenar vários tipos de documentos incorporados. Cada documento incorporado é representado por uma classe de modelo do Django MongoDB Backend .

Para criar um PolymorphicEmbeddedModelField, passe o argumento embedded_models para o construtor da classe PolymorphicEmbeddedModelField() . Este argumento especifica uma lista de classes de modelo que o campo pode armazenar.

Exemplo

Este exemplo adiciona um valor PolymorphicEmbeddedModelField ao modelo criado no exemplo Definir um modelo neste guia. Este campo do awards pode armazenar um modelo embarcado do tipo Oscars ou GoldenGlobes. Cada modelo incorporado contém informações sobre todos os prêmios Oscar ou Globo de Dourado que um filme ganha.

O seguinte código define os modelos embarcados Oscars e GoldenGlobes e, em seguida, modifica o modelo Movie para incluir o PolymorphicEmbeddedModelField:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import PolymorphicEmbeddedModelField
class Oscars(EmbeddedModel):
    wins = models.IntegerField(default=0)
    nominations = models.IntegerField(default=0)
    best_picture = models.BooleanField(default=False)
class GoldenGlobes(EmbeddedModel):
    wins = models.IntegerField(default=0)
    nominations = models.IntegerField(default=0)
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    awards = PolymorphicEmbeddedModelField(["Oscars", "GoldenGlobes"], null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

Dica

Para aprender como executar queries de dados armazenados em um PolymorphicEmbeddedModelField, consulte Consultar valores de modelo incorporados polimórficos no guia Especificar uma query.

Armazenar dados de array de modelo polimórfico incorporado

Você pode usar um PolymorphicEmbeddedModelArrayField para representar um campo de documento MongoDB que pode armazenar vários tipos de documentos incorporados. Este campo é semelhante ao PolymorphicEmbeddedModelField, mas armazena uma array de documentos incorporados em vez de um único documento. Cada documento incorporado na array é representado por uma classe de modelo Django MongoDB Backend .

Para criar um PolymorphicEmbeddedModelArrayField, passe os seguintes argumentos para o construtor da classe PolymorphicEmbeddedModelArrayField():

embedded_models: Especifica as classes de modelo que o campo pode armazenar
max_size: (Opcional) Especifica o tamanho máximo da array

Exemplo

Este exemplo adiciona um valor PolymorphicEmbeddedModelArrayField ao modelo criado no exemplo Definir um modelo neste guia. Este campo do awards pode armazenar uma lista de modelos embarcados do tipo Oscar ou GoldenGlobe. Cada modelo incorporado contém informações sobre um dos prêmios Oscar ou Globo de Dourado que um filme lhe rendeu.

O seguinte código define os modelos embarcados Oscar e GoldenGlobe e, em seguida, modifica o modelo Movie para incluir o PolymorphicEmbeddedModelArrayField:

from django.db import models
from django_mongodb_backend.models import EmbeddedModel
from django_mongodb_backend.fields import PolymorphicEmbeddedModelArrayField
class Oscar(EmbeddedModel):
    category = models.CharField(max_length=200)
    year = models.IntegerField(default=0)
class GoldenGlobe(EmbeddedModel):
    category = models.CharField(max_length=200)
    year = models.IntegerField(default=0)
class Movie(models.Model):
    title = models.CharField(max_length=200)
    plot = models.TextField(blank=True)
    runtime = models.IntegerField(default=0)
    released = models.DateTimeField("release date", null=True, blank=True)
    awards = PolymorphicEmbeddedModelArrayField(["Oscar", "GoldenGlobe"], null=True, blank=True)
    class Meta:
        db_table = "movies"
        managed = False
    
    def __str__(self):
        return self.title

Dica

Para saber como executar queries de dados armazenados em um PolymorphicEmbeddedModelArrayField, consulte Consultar valores de array de modelo polimórfico incorporado no guia Especificar uma query.

Informações adicionais

Para saber como usar seus modelos para executar operações de banco de dados , consulte os guias Interagir com dados.

Para saber mais sobre os campos do Django, consulte a referência de campo do Modelo na documentação do Django.

Voltar

Dados do modelo

Indexes