Definir e impor um esquema
Nesta página
Você pode controlar a forma e o conteúdo dos documentos em uma coleção definindo um esquema. Os esquemas permitem que você exija campos específicos, controle o tipo de valor de um campo e valide as alterações antes de confirmar as operações de gravação.
Este guia mostra como definir, configurar e implantar um esquema para uma coleção de Atlas MongoDB vinculada.
Observação
As fontes de dados federadas não suportam regras ou esquemas. Você só pode acessar uma fonte de dados federada a partir de uma função do sistema.
Definir um esquema
Você pode definir um esquema para uma collection na UI do Atlas App Services ou com a App Services CLI.
Ao utilizar a interface de usuário do Atlas App Services , você pode optar por:
Gere um esquema a partir dos dados existentes na collection e modifique conforme necessário.
Defina um esquema manualmente adicionando definições de esquema em nível de campo.
Navegue até a Tela de Esquema
No menu de navegação esquerdo, clique em Schema abaixo Data Access para abrir o editor de esquema. A tela de configuração Coleções é exibida na aba Collections . O Atlas App Services verifica o cluster vinculado em busca de collections existentes e as lista no lado esquerdo do editor de esquemas.
Encontre e selecione sua coleção no menu para mostrar a configuração da coleção no lado direito do editor de esquema.
Gerar um esquema a partir de dados existentes (opcional)
Se você já tiver dados em sua coleção, os Serviços de App poderão obter uma amostra de um subconjunto dos documentos na coleção e gerar um esquema para você com base no exemplo. Se você já tiver um esquema ou preferir definir um manualmente, pule para a próxima etapa.
Você pode configurar o número de documentos para amostragem e usar o idioma de consulta MongoDB para limitar a amostra a documentos específicos. Por padrão, os Serviços de App amostram aleatoriamente até 500 documentos de toda a coleção.
Para gerar um esquema a partir de dados existentes:
Na configuração da coleção no lado direito do editor de esquema, clique em Generate Schema para abrir a tela de configuração de amostra.
Especifique o tamanho da amostra, até no máximo 50.000 documentos.
Como opção, clique em Advanced e especifique uma query, projeção e/ou classificação para refinar a query de amostra. Use os filtros de query e classificação para obter amostras de um subconjunto específico de documentos e use o filtro de projeção para obter amostras de um subconjunto específico de campos de cada documento.
Clique em Generate para executar a consulta de amostra e gerar um esquema. O processo pode levar até um minuto, dependendo do número e do conteúdo dos documentos de amostra.
Definir ou modificar o esquema
Você pode definir um esquema manualmente ou modificar um esquema existente adicionando definições de esquema em nível de campo.
Você pode definir um único esquema BSON para cada coleção. O tipo de nível raiz de cada esquema de coleção é um esquema object que representa um documento na coleção. Você pode definir esquemas adicionais para campos de documento no campo properties do esquema raiz.
Os campos disponíveis em um objeto do JSON schema dependem do tipo de valor que o esquema define. Para uma lista de tipos suportados e detalhes sobre como configurá-los, consulte tipos de esquema.
Exemplo
Um grupo está usando o App Services para executar um aplicativo de votação em que os usuários têm 13 anos ou mais podem enviar uma lista classificada de suas cores favoritas. Eles armazenam os votos em uma coleção do MongoDB votes onde cada documento representa o voto de uma única pessoa. Cada voto deve incluir o nome da pessoa, a idade e um conjunto de suas cores favoritas. Cada cor tem um rank, name e um hexCode. A seguir está um documento típico da coleção votes:
{ "name": "Jane Doe", "age": 42, "favoriteColors": [ { "rank": 1, "name": "RebeccaPurple", "hexCode": "#663399" }, { "rank": 2, "name": "DodgerBlue", "hexCode": "#1E90FF" }, { "rank": 3, "name": "SeaGreen", "hexCode": "#2E8B57" }, ] }
O grupo pode utilizar o seguinte esquema para garantir que as restrições listadas estejam satisfeitas para cada documento na collection votes:
{ "bsonType": "object", "required": ["name", "age", "favoriteColors"], "properties": { "name": { "bsonType": "string" }, "age": { "bsonType": "int", "minimum": 13, "exclusiveMinimum": false }, "favoriteColors": { "bsonType": "array", "uniqueItems": true, "items": { "bsonType": "object", "properties": { "rank": { "bsonType": "int" }, "name": { "bsonType": "string" }, "hexCode": { "bsonType": "string", "pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$" } } } } } }
Adicionar expressões de validação de alteração (opcional)
Além de configurar o conteúdo de cada campo, você pode validar as alterações nos documentos definindo uma expressão de validação no campo validate de um esquema. As expressões de validação podem usar as expansões %%prev e %%prevRoot para acessar os valores de um campo ou documento antes da ocorrência da operação de inserção ou atualização.
Exemplo
Considere uma coleção onde o campo owner_id do documento representa o proprietário de cada documento. As regras de negócios para essa coleção especificam que, uma vez que um documento tenha um proprietário, o valor de owner_id nunca deve mudar. Podemos impor essa restrição com a seguinte expressão de validação que garante que as operações de atualização não alterem o valor owner_id, a menos que seja para atribuir um proprietário onde não havia nenhum anteriormente:
"owner_id": { "validate": { "%or": [ { "%%prev": { "%exists": false } }, { "%%prev": "%%this" } ] } }
Também podemos utilizar a expansão %%prevRoot para criar a seguinte expressão de validação equivalente:
"owner_id": { "validate": { "%or": [ { "%%prevRoot.owner_id": { "%exists": false } }, { "%%prevRoot.owner_id": "%%root.owner_id" } ] } }
Salvar o Esquema
Após configurar o esquema, clique em Save. Após salvar, os Serviços de App imediatamente começam a aplicar o esquema para todas as consultas futuras.
Observação
Os documentos existentes que não correspondem ao esquema não são atualizados ou validados automaticamente, portanto, alterações futuras nesses documentos podem causar falhas de validação de esquema.
Validação de Documentos em Relação ao Esquema
Depois de salvar o esquema da collection, você poderá validar os documentos existentes na collection em conformidade com o esquema.
O App Services coleta amostras de documentos para validação, assim como para a geração automática de esquemas.
Para validar os dados em uma coleção:
Clique no botão Run Validation para abrir a janela de configuração de validação.
Especifique o tamanho da amostra, até no máximo 50.000 documentos.
Opcionalmente, clique em Advanced e especifique uma consulta e/ou classifique para refinar a validação para um subconjunto específico de documentos.
Clique em Run Validation para obter amostras de documentos da coleção e validar cada documento em relação ao esquema.
Após a validação ser concluída, os App Services listam qualquer erro de validação da amostra na tabela JSON Validation Errors. Cada linha da tabela representa um tipo específico de erro de validação para um determinado campo e indica o número de documentos que não foram validados dessa forma.
Para cada erro de validação, você pode utilizar o menu Actions para baixar os documentos brutos que falharam ou copiar uma consulta MongoDB que localiza os documentos com falha.
Faça login no MongoDB Cloud
Para configurar seu aplicativo com appservices, você deve fazer login no MongoDB Cloud usando umachave de API com escopo para a organização ou projeto que contém o aplicativo.
appservices login --api-key="<MongoDB Cloud Public API Key>" --private-api-key="<MongoDB Cloud Private API Key>"
Obtenha a versão mais recente da sua aplicação
Para definir um esquema de documento com appservices, você precisa de uma cópia local dos arquivos de configuração do seu aplicativo.
Para extrair uma cópia local da versão mais recente do seu aplicativo, execute o seguinte:
appservices pull --remote="<Your App ID>"
Dica
Você também pode baixar uma cópia dos arquivos de configuração do seu aplicativo na tela Deploy > Import/Export App na interface do usuário do App Services.
Definir o esquema
Para definir ou modificar o esquema de uma collection, abra o arquivo de configuração schema.json no diretório de configuração da collection.
Dica
Organize a coleção
Se você ainda não tiver definido regras ou um esquema para a coleção, precisará criar manualmente seu diretório de configuração e schema.json:
# Create the collection's configuration directory mkdir -p data_sources/<service>/<db>/<collection> # Create the collection's schema file echo '{}' >> data_sources/<service>/<db>/<collection>/schema.json
O esquema de nível raiz para cada documento deve ser do tipo object. Você pode usar esquema adicional para configurar campos específicos dentro da array properties . No mínimo, o esquema deve ser semelhante ao seguinte:
{ "bsonType": "object", "properties": { "<Field Name>": <Schema Document>, ... } }
Definir validação de alteração (opcional)
Você pode validar alterações em documentos definindo uma expressão de validação no campo validate de um esquema. As expressões de validação podem usar as expansões %%prev e %%prevRoot para acessar os valores de um campo ou documento antes da ocorrência da operação de inserção ou atualização.
Exemplo
Considere uma coleção onde o campo owner_id do documento representa o proprietário de cada documento. As regras de negócios para essa coleção especificam que, uma vez que um documento tenha um proprietário, o valor de owner_id nunca deve mudar. Podemos impor essa restrição com a seguinte expressão de validação que garante que as operações de atualização não alterem o valor owner_id, a menos que seja para atribuir um proprietário onde não havia nenhum anteriormente:
"owner_id": { "validate": { "%or": [ { "%%prev": { "%exists": false } }, { "%%prev": "%%this" } ] } }
Também podemos utilizar a expansão %%prevRoot para criar a seguinte expressão de validação equivalente:
"owner_id": { "validate": { "%or": [ { "%%prevRoot.owner_id": { "%exists": false } }, { "%%prevRoot.owner_id": "%%root.owner_id" } ] } }
Validar tipos nulos
O comportamento padrão do App Services é aceitar somente um único tipo para cada campo. Os campos de esquema não são anuláveis por padrão, pois null é um tipo BSONúnico.
Você pode configurar os App Services para passar a validação de esquema quando você utilizar valores do null com campos opcionais. Habilitar a validação do tipo nulo permite que o valor de um campo seja mantido como o tipo no esquema ou o tipo nulo BSON . Se você não habilitar a validação de esquema de tipo nulo, o App Services rejeitará os valores null passados para campos opcionais. Mesmo que você habilite a validação de tipo nulo, os campos obrigatórios nunca serão anuláveis.
Para ativar a validação de esquema de tipo nulo na interface do usuário do Apps Services:
No menu de navegação esquerdo abaixo do cabeçalho Manage, selecione App Settings.
Na aba General, navegue até a seção Null Type Schema Validation. Alterne o interruptor para ON.
Clique no botão Save.