Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Migre seu aplicativo Djogo

Neste guia, você pode aprender como modificar seu projeto Djogo para usar o Django MongoDB Backend. O Djongo é uma biblioteca de terceiros que traduz queries SQL em queries da linguagem de query do MongoDB (MQL), permitindo que você use o MongoDB como seu backend do Django para as versões 4.0 e anteriores do Django. No entanto, o Django MongoDB Backend é a integração oficialmente suportada e oferece suporte ao Django mais abrangente, acesso expandido aos recursos do MongoDB e compatibilidade com versões mais recentes do Django.

Este guia mostra como migrar um aplicativo Djongo para o Django MongoDB backend atualizando os seguintes componentes do aplicativo:

Para se conectar ao MongoDB usando o Django MongoDB Backend em vez do Djogo, modifique a configuração DATABASES no arquivo settings.py do seu aplicativo. Atualize o valor da chave ENGINE aninhada desta configuração de "djongo" para "django_mongodb_backend". Em seguida, especifique sua string de conexão na chave HOST aninhada em vez da chave CLIENT.

Dica

Para aprender mais sobre a configuração do DATABASES, consulte o guia Conectar ao MongoDB.

O exemplo a seguir mostra como modificar sua configuração DATABASES para usar o backend Django MongoDB . Selecione a aba Djongo para ver a configuração inicial e selecione a aba Django MongoDB Backend para ver a configuração atualizada:

DATABASES = { 'default': { 'ENGINE': 'djongo', 'CLIENT': { 'host': 'mongodb+srv://cluster0.example.mongodb.net', }, 'NAME': 'my_database' }}

O Djogo não requer nenhuma configuração adicional dos aplicativos contrib integrados do Django. No entanto, o Django MongoDB Backend exige que cada aplicativo contrib que inclua modelos use ObjectIdAutoField como seu tipo de campo de chave primária padrão. Isso afeta os seguintes aplicativos:

  • django.contrib.admin

  • django.contrib.auth

  • django.contrib.contenttypes

Dica

Modelo de projeto

O modelo django-mongodb-project inclui as AppConfig subclasses necessárias e a configuração MIGRATION_MODULES para os aplicativos anteriores. Para aprender como criar um projeto usando esse modelo, consulte o tutorial Introdução ao backend do MongoDB do Django.

Para configurar estes aplicativos, crie ou atualize o arquivo apps.py no seu diretório de projeto para definir uma subclasse AppConfig personalizada para cada um dos aplicativos anteriores. O exemplo a seguir mostra um arquivo apps.py de amostra que define estas subclasses AppConfig:

from django.contrib.admin.apps import AdminConfigfrom django.contrib.auth.apps import AuthConfigfrom django.contrib.contenttypes.apps import ContentTypesConfig class MongoAdminConfig(AdminConfig): default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" class MongoAuthConfig(AuthConfig): default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField" class MongoContentTypesConfig(ContentTypesConfig): default_auto_field = "django_mongodb_backend.fields.ObjectIdAutoField"

Em seguida, atualize a configuração INSTALLED_APPS em seu arquivo settings.py para usar suas classes AppConfig personalizadas em vez das classes padrão. O exemplo seguinte atualiza as configurações de um projeto denominado myproject para utilizar as classes AppConfig personalizadas. Selecione a aba Djongo para ver as configurações iniciais e selecione a aba Django MongoDB Backend para ver as configurações atualizadas:

INSTALLED_APPS = [ 'myapp.apps.MyAppConfig', 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.messages', 'django.contrib.staticfiles',]

Por fim, adicione a configuração MIGRATION_MODULES ao seu arquivo settings.py para instruir o Django MongoDB Backend a usar módulos de migração compatíveis com o MongoDB para os aplicativos contrib afetados:

MIGRATION_MODULES = { 'admin': 'mongo_migrations.admin', 'auth': 'mongo_migrations.auth', 'contenttypes': 'mongo_migrations.contenttypes',}

Dica

Executar migrações

Após concluir as etapas anteriores, execute os seguintes comandos para aplicar as migrações para os aplicativos do contrib:

python manage.py makemigrationspython manage.py migrate

Para atualizar seus modelos para usar o Backend do Django MongoDB , faça as seguintes alterações nas definições do seu modelo:

  1. Importe o módulo models de django.db em vez de djongo.

  2. Remova as definições explícitas de ObjectIdField, pois o Django MongoDB Backend cria automaticamente um campo _id do tipo ObjectIdField.

  3. Modifique a sintaxe do array específica do MongoDB e dos campos incorporados.

Importante

Tipos de campo

Djogo e Django MongoDB Backend provavelmente armazena campos Django no mesmo formato. No entanto, você pode enfrentar incompatibilidades devido a diferenças nos conversores de campo das integrações. Se encontrar algum problema, envie feedback usando a aba Rate this page no lado direito desta página.

Dica

Para aprender mais sobre modelos backend do MongoDB do Django, consulte o guia Criar modelos para representar coleções.

O exemplo a seguir mostra como atualizar uma classe de modelo denominada Recipe para compatibilidade com o Backend do Django MongoDB . Selecione a aba Djongo para ver o modelo inicial e selecione a aba Django MongoDB Backend para ver o modelo atualizado:

from djongo import models class Tag(models.Model): data = models.CharField(max_length=100) class Meta: abstract = True class Recipe(models.Model): _id = models.ObjectIdField() title = models.CharField(max_length=100) cuisine = models.CharField(max_length=100) cook_time = models.IntegerField(default=0) tags = models.ArrayField(model_container=Tag)

Para criar um objeto Recipe que armazena os campos anteriores, use o seguinte código:

Recipe.objects.create( title="Tiramisu", cuisine="Italian", cook_time=20, tags=[ {"data": "dessert"}, {"data": "classic"}, {"data": "espresso"}, {"data": "chocolate"} ])

Ao usar Djogo, você pode usar um EmbeddedField para representar um documento MongoDB incorporado. Para definir um campo que armazena vários documentos incorporados, você pode usar um ArrayField.

O Django MongoDB Backend fornece os seguintes campos que representam documentos incorporados:

  • EmbeddedModelField: Armazena um modelo aninhado

  • EmbeddedModelArrayField: Armazena uma array de modelos aninhados

Dica

Polimorfismo do modelo

Você não pode usar campos Djogo para armazenar uma array de vários tipos de modelo. No entanto, o Django MongoDB Backend fornece os campos PolymorphicEmbeddedModelField e PolymorphicEmbeddedModelArrayField para o suporte ao polimorfismo. Para aprender, consulte Usar campos avançados no guia Criar modelos.

O exemplo seguinte mostra como atualizar um arquivo models.py que define um modelo Recipe contendo os seguintes campos de modelo embarcados:

  • nutrition: Armazena um modelo Nutrition incorporado que representa informações nutricionais

  • reviews: Armazena vários modelos Review incorporados que representam revisar individuais de receitas

Selecione a aba Djongo para ver os modelos iniciais e selecione a aba Django MongoDB Backend para ver os modelos atualizados:

from djongo import models class Nutrition(models.Model): calories = models.IntegerField(default=0) carb_grams = models.IntegerField(default=0) protein_grams = models.IntegerField(default=0) class Meta: abstract = True class Review(models.Model): author = models.CharField(max_length=100) rating = models.IntegerField(default=0) class Meta: abstract = True class Recipe(models.Model): _id = models.ObjectIdField() title = models.CharField(max_length=100) cuisine = models.CharField(max_length=100) cook_time = models.IntegerField(default=0) nutrition = models.EmbeddedField(model_container=Nutrition) reviews = models.ArrayField(model_container=Review)

Para atualizar os índices em seu aplicativo Djogo para compatibilidade com o Django MongoDB Backend, você deve usar as classes de índice fornecidas pelo Django MongoDB Backend.

O Djogo fornece classes separadas para representar cada índice do MongoDB , incluindo classes para índices de campo único, índices compostos, índices de múltiplas chaves e muito mais.

O Django MongoDB Backend fornece as três classes a seguir para representar todos os tipos de índice:

  • Index classe: classe de índice do Django, que representa todos os tipos de índice que não são índices de pesquisa

  • SearchIndex classe: A classe específica do Django MongoDB Backend para representar índices de pesquisa do MongoDB

  • VectorSearchIndex classe: A Django MongoDB backend específica para representar índices de pesquisa do MongoDB Vector Search

Dica

Para saber mais sobre como usar o Django MongoDB backend para criar índices, consulte o guia Índices para otimização de query.

O exemplo seguinte mostra como atualizar um índice composto em um modelo do Recipe. A implementação do backend MongoDB do Django também adiciona um índice de pesquisa, que o Djongo não suporta. Selecione a aba Djongo para ver o índice inicial e selecione a aba Django MongoDB Backend para ver os índices atualizados:

from djongo import modelsfrom djongo.models.indexes import CompoundIndex class Recipe(models.Model): _id = models.ObjectIdField() title = models.CharField(max_length=100) cuisine = models.CharField(max_length=100) cook_time = models.IntegerField(default=0) class Meta: indexes = [ CompoundIndex(fields=["title", "cook_time"]) ]

Você pode usar a API do Django QuerySet para consultar os modelos backend do Djongo e do Django MongoDB. No entanto, a sintaxe é diferente para queries de modelo embarcado.

O Djogo trata modelos embarcados como dicionários Python, e você deve usar a sintaxe de dicionário Python para acessar ou modificar seus campos. O Django MongoDB backend trata os modelos incorporados como modelos Django, então você usa a mesma sintaxe para a interação com seus campos e com todos os outros modelos.

Importante

Regressões de desempenho

As queries do Djongo e do Django MongoDB backend geram diferentes queries MQL subjacentes, que podem ter implicações de desempenho. Ao migrar do Djongo para o Django MongoDB backend, recomendamos que você monitore as alterações de desempenho para identificar possíveis regressões e arquive um ticket JIRA se descobrir alguma.

Dica

Para saber mais sobre como usar o Django MongoDB Backend para consultar seus modelos, consulte o guia Especificar uma query.

O exemplo a seguir mostra a diferença entre uma query Djogo e uma query de backend do MongoDB no modelo Recipe e seu campo de modelo embarcado nutrition, definido na seção Exemplo de modelo embarcado. O código consulta o campo calories do modelo embarcado Nutrition. Selecione a aba Djongo para ver a query inicial e selecione a aba Django MongoDB Backend para ver a query atualizada:

Recipe.objects.filter(nutrition__lt={'calories': 500})

Tanto o Djogo quanto o Django MongoDB Backend oferecem suporte à funcionalidade de API de transação atômica do Django. No entanto, cada um deles fornece uma API personalizada para implementar essa funcionalidade. Você pode atualizar suas transações para compatibilidade com o Django MongoDB Backend modificando a declaração de importação do seu código.

Dica

Para aprender mais sobre como usar o Django MongoDB backend para executar transações, consulte o guia Transações e Sessões.

O exemplo a seguir mostra como atualizar seu código para importar a API de transação do Django MongoDB Backend. Selecione a aba Djongo para ver a declaração inicial e selecione a aba Django MongoDB Backend para ver a declaração atualizada:

from djongo import transaction

O Djongo não suporta migrações de banco de dados e não impõe validação de esquema por padrão. Se você definir a configuração ENFORCE_SCHEMA para True em seu arquivo settings.py, o Djongo forçará MigrationErrors quando os documentos recuperados tiverem valores de campo ausentes.

O Django MongoDB backend oferece suporte a migrações de banco de dados com algumas limitações. Para saber mais sobre essas limitações, consulte suporte à migração no guia Compatibilidade de recursos.

O Django MongoDB Backend não impõe validação de esquema. Como resultado, atualizar campos de modelo sem executar migrações para atualizar o esquema do banco de dados não gera erros.

Para aprender como configurar um novo aplicativo que usa o backend do Django MongoDB, consulte o tutorial Introdução ao backend do Django MongoDB.

Para saber mais sobre como executar operações de banco de dados usando o Django MongoDB Backend, consulte o guia Operações CRUD.

Para **aprender** mais sobre como criar modelos de **backend** do **MongoDB** Django, consulte o **guia** Criar modelos para representar **coleções**.