Puede controlar la forma y el contenido de los documentos de una colección definiendo un esquema. Los esquemas permiten requerir campos específicos, controlar el tipo de valor de un campo y validar los cambios antes de confirmar operaciones de escritura.
Esta guía le muestra cómo definir, configurar e implementar un esquema para una colección de MongoDB Atlas vinculada.
Nota
Las fuentes de datos federadas no admiten reglas ni esquemas. Solo se puede acceder a ellas desde una función del sistema.
Definir un esquema
Puede definir un esquema para una colección en la interfaz de usuario de App Services o con la CLI de App Services.
Al utilizar la interfaz de usuario de App Services, puede elegir:
Genere un esquema a partir de datos existentes en la colección y modifíquelo según sea necesario.
Defina un esquema manualmente agregando definiciones de esquema a nivel de campo.
Navegar a la pantalla de esquema
En el menú de navegación de la izquierda, haga clic en Schema debajo de Data Access para abrir el editor de esquemas. La pantalla de configuración de Colecciones se muestra en la pestaña Collections. Atlas App Services escanea el clúster vinculado en busca de colecciones existentes y las muestra en la parte izquierda del editor de esquemas.
Busque y seleccione su colección en el menú para mostrar la configuración de la colección en el lado derecho del editor de esquemas.
Generar un esquema a partir de datos existentes (opcional)
Si ya tiene datos en su colección, App Services puede muestrear un subconjunto de los documentos de la colección y generar un esquema basado en la muestra. Si ya tiene un esquema o prefiere definir uno manualmente, vaya al siguiente paso.
Puede configurar la cantidad de documentos a muestrear y usar el lenguaje de consulta de MongoDB para limitar el muestreo a documentos específicos. De forma predeterminada, App Services muestrea aleatoriamente hasta 500 documentos de toda la colección.
Para generar un esquema a partir de datos existentes:
Desde la configuración de la colección en el lado derecho del editor de esquemas, haga clic en Generate Schema para abrir la pantalla de configuración de muestra.
Especifique el tamaño de la muestra, hasta un máximo de 50,000 documentos.
Opcionalmente, haga clic en Advanced y especifique una consulta, proyección u ordenación para refinar la consulta de muestra. Utilice los filtros de consulta y ordenación para muestrear un subconjunto específico de documentos y el filtro de proyección para muestrear un subconjunto específico de campos de cada documento.
Haga clic en Generate para ejecutar la consulta de muestra y generar un esquema. El proceso puede tardar hasta un minuto, dependiendo de la cantidad y el contenido de los documentos muestreados.
Definir o modificar el esquema
Puede definir un esquema manualmente o modificar un esquema existente agregando definiciones de esquema a nivel de campo.
Puede definir un único esquema BSON para cada colección. El tipo de nivel raíz de cada esquema de colección es un object Esquema que representa un documento de la colección. Puede definir esquemas adicionales para los campos del documento dentro del campo properties del esquema raíz.
Los campos disponibles en un objeto de esquema JSON dependen del tipo de valor que define el esquema. Para obtener una lista de los tipos admitidos y detalles sobre cómo configurarlos, consulte Tipos de esquema.
Ejemplo
Un grupo usa App Services para ejecutar una aplicación de votación donde los usuarios de 13 o más pueden enviar una lista ordenada de sus colores favoritos. Almacenan los votos en una colección de MongoDB llamada votes, donde cada documento representa el voto de una persona. Cada voto debe incluir el nombre, la edad y una matriz de sus colores favoritos. Cada color tiene un rank, un name y un hexCode. El siguiente es un documento típico de la colección 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" }, ] }
El grupo puede utilizar el siguiente esquema para garantizar que se cumplan las restricciones enumeradas para cada documento de la colección 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})$" } } } } } }
Agregar expresiones de validación de cambios (opcional)
Además de configurar el contenido de cada campo, puede validar los cambios en los documentos definiendo una expresión de validación en el validate campo de un esquema. Las expresiones de validación pueden usar las %%prev expansiones y para acceder a los %%prevRoot valores de un campo o documento antes de la operación de inserción o actualización.
Ejemplo
Considere una colección donde el campo owner_id del documento representa al propietario de cada documento. Las reglas de negocio de esta colección especifican que, una vez que un documento tiene propietario, el valor de owner_id nunca debe cambiar. Podemos aplicar esta restricción con la siguiente expresión de validación, que garantiza que las operaciones de actualización no modifiquen el valor owner_id a menos que se trate de asignar un propietario donde no existía ninguno previamente:
"owner_id": { "validate": { "%or": [ { "%%prev": { "%exists": false } }, { "%%prev": "%%this" } ] } }
También podríamos usar la expansión para crear la siguiente expresión de validación %%prevRoot equivalente:
"owner_id": { "validate": { "%or": [ { "%%prevRoot.owner_id": { "%exists": false } }, { "%%prevRoot.owner_id": "%%root.owner_id" } ] } }
Guardar el esquema
Después de configurar el esquema, haga clic en Save. Tras guardar, App Services comenzará a aplicar el esquema inmediatamente para todas las consultas futuras.
Nota
Los documentos existentes que no coinciden con el esquema no se actualizan ni validan automáticamente, por lo que cambios futuros en estos documentos pueden causar fallas en la validación del esquema.
Validar documentos contra el esquema
Una vez que haya guardado el esquema de la colección, puede validar que los documentos existentes en la colección se ajusten al esquema.
App Services toma muestras de documentos para su validación, tal como lo hace para la generación automática de esquemas.
Para validar los datos de una colección:
Haga clic en el botón Run Validation para abrir la ventana de configuración de validación.
Especifique el tamaño de la muestra, hasta un máximo de 50,000 documentos.
Opcionalmente, haga clic en Advanced y especifique una consulta y/o clasificación para refinar la validación a un subconjunto específico de documentos.
Haz clic en Run Validation para extraer muestras de documentos de la colección y validar cada documento en comparación con el esquema.
Una vez completada la validación, App Services muestra los errores de validación de la muestra en la tabla JSON Validation Errors. Cada fila de la tabla representa un tipo específico de error de validación para un campo específico e indica el número de documentos que no se validaron de esa manera.
Para cada error de validación, puede utilizar el menú Actions para descargar los documentos sin procesar que fallaron o copiar una consulta MongoDB que encuentre los documentos fallidos.
Iniciar sesión en MongoDB Cloud
Para configurar su aplicación con servicios de aplicaciones, debe iniciar sesión en MongoDB Cloud mediante un Clave API limitada a la organización o proyecto que contiene la aplicación.
appservices login --api-key="<MongoDB Cloud Public API Key>" --private-api-key="<MongoDB Cloud Private API Key>"
Obtenga la última versión de su aplicación
Para definir un esquema de documento con appservices, necesitas una copia local de los archivos de configuración de tu aplicación.
Para extraer una copia local de la última versión de su aplicación, ejecute lo siguiente:
appservices pull --remote="<Your App ID>"
Tip
También puedes descargar una copia de los archivos de configuración de tu aplicación desde la pantalla Deploy > Import/Export App en la Interfaz de usuario Realm.
Definir el esquema
Para definir o modificar el esquema de una colección, abra el archivo de configuración schema.json dentro del directorio de configuración de la colección.
Tip
Andamiaje de la colección
Si aún no ha definido reglas o un esquema para la colección, debe crear manualmente su directorio de configuración y 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
El esquema raíz de cada documento debe ser de object tipo. Puede usar un esquema adicional para configurar campos específicos dentro de la properties matriz. Como mínimo, el esquema debería ser similar al siguiente:
{ "bsonType": "object", "properties": { "<Field Name>": <Schema Document>, ... } }
Definir validación de cambios (opcional)
Puede validar cambios en documentos definiendo una expresión de validación en el validate campo de un esquema. Las expresiones de validación pueden usar las %%prev expansiones y para acceder a los %%prevRoot valores de un campo o documento antes de la operación de inserción o actualización.
Ejemplo
Considere una colección donde el campo owner_id del documento representa al propietario de cada documento. Las reglas de negocio de esta colección especifican que, una vez que un documento tiene propietario, el valor de owner_id nunca debe cambiar. Podemos aplicar esta restricción con la siguiente expresión de validación, que garantiza que las operaciones de actualización no modifiquen el valor owner_id a menos que se trate de asignar un propietario donde no existía ninguno previamente:
"owner_id": { "validate": { "%or": [ { "%%prev": { "%exists": false } }, { "%%prev": "%%this" } ] } }
También podríamos usar la expansión para crear la siguiente expresión de validación %%prevRoot equivalente:
"owner_id": { "validate": { "%or": [ { "%%prevRoot.owner_id": { "%exists": false } }, { "%%prevRoot.owner_id": "%%root.owner_id" } ] } }
Validar tipos nulos
El comportamiento predeterminado de App Services es aceptar solo un tipo por campo. Los campos de esquema no admiten valores nulos de forma predeterminada,null ya que es un tipo BSON único.
Puedes configurar App Services para pasar la validación del esquema cuando utilices valores null con campos opcionales. Habilitar la validación de tipo nulo permite mantener el valor de un campo como el tipo en el esquema o el tipo BSON null. Si no habilitas la validación de esquema de tipo nulo, Servicios de aplicación rechaza los valores null que se pasen a campos opcionales. Incluso si activas la validación del tipo de nulo, los campos obligatorios nunca pueden ser nulos.
Para habilitar la validación del esquema de tipo nulo en la interfaz de usuario de App Services:
En el menú de navegación izquierdo debajo del encabezado Manage, seleccione App Settings.
En la pestaña General, navega a la sección Null Type Schema Validation. Cambia el interruptor a ON.
Haga clic en el botón Save.