En Atlas Data Federation, se gestiona el esquema que utiliza la interfaz SQL mediante tres comandos: sqlGenerateSchema, sqlGetSchema y sqlSetSchema. Estos comandos se ejecutan desde mongosh en una instancia federada de base de datos, o se realizan las acciones equivalentes en la interfaz de usuario de Atlas. Esta página documenta esos comandos y sus equivalentes en la interfaz de usuario.
Atlas Data Federation muestra documentos de sus colecciones para generar el esquema inicial. Para obtener información de segundo plano sobre la gestión de esquemas y los otros tipos de implementación admitidos, consulte Gestión de esquemas.
Nota
Los comandos sqlGenerateSchema, sqlGetSchema y sqlSetSchema y sus equivalentes de la interfaz de usuario de Atlas solo se aplican al tipo de implementación de Atlas Data Federation. No se aplican a las implementaciones de Enterprise Advanced (EA) autogestionadas, que utilizan la CLI de MongoDB SQL esquema Builder, ni a las query en un clúster de Atlas estándar que no utilice Atlas Data Federation.
sqlGenerateSchema
El comando sqlGenerateSchema genera un esquema SQL para las colecciones o vistas especificadas. Atlas Data Federation muestra documentos de cada namespace para derivar el esquema.
Sintaxis
Cuando utilice el parámetro sampleNamespaces, debe ejecutar el comando en la base de datos admin.
use admin db.runCommand({ sqlGenerateSchema: 1, sampleNamespaces: [<namespace>], sampleSize: <int>, setSchemas: true|false })
Parámetros
Parameter | Tipo | Descripción | Necesidad |
|---|---|---|---|
| Arreglo de cadenas | Especifica la lista de namespace separados por comas para los que se van a generar esquemas. Un namespace incluye el nombre de la base de datos, un separador de punto ( | Opcional |
| entero | Especifica el número de documentos a utilizar como muestra para crear el esquema. Si se omite, el valor por defecto es | Opcional |
| booleano | Especifica si se debe almacenar el esquema generado para la colección o la vista. El valor puede ser uno de los siguientes:
Si se omite, es por defecto | Opcional |
Salida
El comando devuelve la siguiente salida si se tiene éxito:
{ "ok" : 1, "schemas" : [ { "databaseName" : "<database-name>", "namespaces" : [ { "name" : "<collection-name>", "schema" : { "version" : NumberLong(1), "jsonSchema" : { ... } } } ] }, ... ] }
El objeto schemas contiene los siguientes campos.
Parameter | Tipo | Descripción |
|---|---|---|
| string | Nombre de la base de datos. |
| Arreglo de objetos | Nombre y esquema generado de cada colección o vista. |
| string | Nombre de la colección o vista. |
| Documento | Esquema de la colección o vista. |
| entero | Versión del formato del esquema. El valor siempre es 1. |
| Documento | JSON esquema de la colección o vista. El JSON esquema puede contener los siguientes campos:
Para obtener más información sobre estos campos, consulta JSON Schema Keywords. |
Si establece el esquema para la colección o vista con la opción setSchemas, puede verificar que el comando se haya realizado correctamente ejecutando el comando sqlGetSchema. El campo metadata.description del comando sqlGetSchema contiene el siguiente valor:
"set using sqlGenerateSchema with setSchemas = true"
Errors
El comando devuelve el siguiente error si falla:
"failedNamespaces": [ { "namespace" : "<db.ns>", "error" : "no documents found in sample namespace" } ]
Atlas Data Federation devuelve este error si los namespace especificados no existen en la configuración de almacenamiento o están vacíos. Atlas Data Federation también devuelve este error si no pudo establecer el esquema para un namespace determinado.
sqlGetSchema
El comando sqlGetSchema recupera el esquema almacenado para la colección o vista especificada.
Sintaxis
db.getSiblingDB("<dbName>").runCommand({ sqlGetSchema: "<collection-name>|<view-name>" })
Parámetros
Parameter | Tipo | Descripción | Necesidad |
|---|---|---|---|
| string | Nombre de la colección para la que se desea recuperar el esquema. Proporcione el nombre de la colección o el nombre de la vista. | Condicional |
| string | Nombre de la vista para la que se va a recuperar el esquema. Proporcione el nombre de la vista o el nombre de la colección. | Condicional |
Salida
El comando devuelve la siguiente salida si la colección o vista no tiene un esquema:
{ "ok" : 1, "metadata" : { }, "schema" : { } }
El comando devuelve una salida similar a la siguiente si la colección o vista tiene un esquema:
{ "ok": 1, "metadata": { "description": "<description>" }, "schema": { "version": NumberLong(1), "jsonSchema": { ... } } }
El campo metadata.description es donde se describe cómo se estableció el esquema para la colección. El valor puede ser uno de los siguientes:
generated automatically by Atlas Data FederationIndica que el esquema fue generado automáticamente por Atlas Data Federation.
set using sqlGenerateSchema with setSchemas = trueIndica que el esquema fue establecido por el comando sqlGenerateSchema porque la opción
setSchemafue establecida atrue.
set using sqlSetSchemaIndica que el esquema se configuró usando el comando sqlSetSchema.
El documento schema contiene los siguientes campos:
Parameter | Tipo | Descripción |
|---|---|---|
| entero | Versión del formato del esquema. El valor siempre es 1. |
| Documento | JSON esquema de la colección o vista. El JSON esquema puede contener los siguientes campos:
Para obtener más información sobre estos campos, consulta JSON Schema Keywords. |
sqlSetSchema
El comando sqlSetSchema establece o remover el esquema de una colección o vista. El comando aplica directamente el esquema que proporcione. El comando no valida el esquema proporcionado con los datos de la colección.
Sintaxis
db.getSiblingDB("<dbName>").runCommand({ sqlSetSchema: "<collection-name>|<view-name>", schema: { "version": 1, "jsonSchema": <jsonSchema> } })
db.getSiblingDB("<dbName>").runCommand({ sqlSetSchema: "<collection-name>|<view-name>", schema: {} })
Parámetros
Parameter | Tipo | Descripción | Necesidad |
|---|---|---|---|
| string | Nombre de la colección para la que se va a establecer el esquema. Proporcione un nombre de colección o un nombre de vista. | Condicional |
| string | Nombre de la vista para la que se va a establecer el esquema. Proporcione un nombre de vista o un nombre de colección. | Condicional |
| Documento | La versión de formato del esquema y una de las siguientes:
Puede proporcionar un solo documento o un arreglo de documentos en el campo | Requerido |
Salida
El comando devuelve la siguiente salida si se tiene éxito:
{ "ok" : 1 }
Puedes verificar que el comando se ejecutó correctamente ejecutando el comando sqlGetSchema. El campo metadata.description en la respuesta contiene el siguiente valor:
"set using sqlSetSchema"
Ejemplos
Considera una colección llamada egData en una base de datos llamada sampleDB con los siguientes documentos:
{"a": {"b": {"c": [1, 2, 3]}}, "s": 1} {"a": {"b": {"c": [4, 5, 6]}}, "s": 2} {"a": {"b": [7, 8, 9]}, "s": 3} {"a": {"b": {"c": []}}, "s": 4} {"a": {"b": {"c": "hello"}}, "s": 5} {"a": {"b": {"c": {"d": 1}}}, "s": 6} {"a": {"b": {"c": null}}} {"s": 7}
Los siguientes ejemplos utilizan los comandos de esquema de Atlas Data Federation para generar, recuperar, establecer y remover el esquema de la colección anterior.
Generar un esquema
El siguiente comando genera un esquema para la colección denominada sampleDB.egData en la configuración de almacenamiento. El comando utiliza dos documentos seleccionados aleatoriamente de la colección para crear el esquema porque sampleSize es 2. El comando no establece el esquema para la colección porque la opción setSchemas no se especifica y por defecto es false.
use admin db.runCommand({ sqlGenerateSchema: 1, sampleNamespaces: ["sampleDB.egData"], sampleSize: 2 })
El comando anterior devuelve la siguiente salida. Para obtener más información sobre los campos en el resultado, consulte Resultado.
{ "ok" : 1, "schemas" : [ { "databaseName" : "sampleDB", "namespaces" : [ { "name" : "egData", "schema" : { "version" : NumberLong(1), "jsonSchema" : { "bsonType" : [ "object" ], "properties" : { "a" : { "bsonType" : [ "object" ], "properties" : { "b" : { "bsonType" : [ "object" ], "properties" : { "c" : { "bsonType" : [ "array" ], "items" : { "bsonType" : [ "int" ] } } } } } }, "s" : { "bsonType" : [ "int" ] } } } } } ] } ] }
Generar y establecer un esquema
El siguiente comando genera un esquema para la colección denominada sampleDB.egData en la configuración de almacenamiento. El comando utiliza hasta 1000 documentos en la colección para crear el esquema porque la opción sampleSize no se especifica y por defecto es 1000. El comando establece el esquema generado como el esquema que se utilizará para la colección porque setSchemas es true.
use admin db.runCommand({ sqlGenerateSchema: 1, sampleNamespaces: ["sampleDB.egData"], setSchemas: true })
Retrieve a Schema
El siguiente comando recupera el esquema almacenado para la colección egData:
db.getSiblingDB("sampleDB").runCommand({ sqlGetSchema: "egData" })
El comando anterior devuelve la siguiente salida. Para obtener más información sobre los campos en el resultado, consulte Resultado.
{ "ok" : 1, "metadata" : { "description" : "set using sqlGenerateSchema with setSchemas = true" }, "schema" : { "version" : NumberLong(1), "jsonSchema" : { "bsonType" : [ "object" ], "properties" : { "a" : { "bsonType" : [ "object" ], "properties" : { "b" : { "bsonType" : [ "object", "array" ], "properties" : { "c" : { "bsonType" : [ "array", "string", "object", "null" ], "properties" : { "d" : { "bsonType" : [ "int" ] } }, "items" : { "bsonType" : [ "int" ] } } }, "items" : { "bsonType" : [ "int" ] } } } }, "s" : { "bsonType" : [ "int", "object" ] } } } } }
Definir esquema
El siguiente comando sqlSetSchema establece el esquema para la colección egData:
db.getSiblingDB("sampleDB").runCommand({ sqlSetSchema : "egData", "schema" : { "version" : NumberLong(1), "jsonSchema" : { "bsonType" : [ "object" ], "properties" : { "a" : { "bsonType" : [ "object" ], "properties" : { "b" : { "bsonType" : [ "object", "array" ], "properties" : { "c" : { "bsonType" : [ "array", "string", "object", "null" ], "properties" : { "d" : { "bsonType" : [ "int" ] } }, "items" : { "bsonType" : [ "int" ] } } }, "items" : { "bsonType" : [ "int" ] } } } }, "s" : { "bsonType" : [ "int", "object" ] } } } } })
El comando anterior devuelve el siguiente resultado:
{ "ok" : 1 }
Remover un esquema
El siguiente comando sqlSetSchema remueve el esquema de la colección egData pasando un documento schema vacío:
db.getSiblingDB("sampleDB").runCommand({ sqlSetSchema: "egData", schema: {} })
El comando anterior devuelve el siguiente resultado:
{ "ok" : 1 }
Gestionar esquemas en la interfaz de usuario de Atlas
Puede realizar las mismas acciones de esquema en la interfaz de usuario de Atlas desde la página Manage SQL Schemas. La interfaz de usuario muestra documentos para generar esquemas, lo mismo que el comando sqlGenerateSchema.
Crea un esquema
Cuando crea una conexión de inicio rápido, Atlas Data Federation genera el esquema automáticamente. Para crear un esquema manualmente, utilice el siguiente procedimiento.
En Atlas, ve a tu instancia federada de base de datos para tu proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Data Federation en la sección Services.
Se muestra la página Data Federation.
Regenerar un esquema
Regenere un esquema cada vez que cambie la forma de los datos subyacentes, como cuando agrega campos o cambia los tipos de campo, para que sus queries SQL reflejen los datos actuales. Para mantener los esquemas actualizados automáticamente, consulte Cronograma para actualizar esquemas.
En Atlas, ve a tu instancia federada de base de datos para tu proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Data Federation en la sección Services.
Se muestra la página Data Federation.
Ver un esquema
En Atlas, ve a tu instancia federada de base de datos para tu proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Data Federation en la sección Services.
Se muestra la página Data Federation.
Navegue a la página Administrar esquemas SQL.
Desde la sección Federated Database Instances, haz clic en el icono a la derecha del esquema, y luego selecciona Manage SQL Schemas del menú desplegable.
En esta página, puede ver todos los esquemas existentes. Para ver un esquema específico en formato JSON, haga clic en el .
Editar un esquema
En Atlas, ve a tu instancia federada de base de datos para tu proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Data Federation en la sección Services.
Se muestra la página Data Federation.
Borrar un esquema
En Atlas, ve a tu instancia federada de base de datos para tu proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Data Federation en la sección Services.
Se muestra la página Data Federation.
Borrar todos los esquemas
En Atlas, ve a tu instancia federada de base de datos para tu proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Data Federation en la sección Services.
Se muestra la página Data Federation.
Programación de actualizaciones de esquema
Las actualizaciones de esquema programadas le ayudan a mantener la precisión del esquema a lo largo del tiempo. Las actualizaciones de esquema programadas muestran cada namespace y combinan el nuevo esquema con el existente. Por ejemplo, las actualizaciones de esquema programadas permiten que Atlas Data Federation detecte automáticamente los nuevos campos agregados a las colecciones.
En Atlas, ve a tu instancia federada de base de datos para tu proyecto.
Si aún no aparece, se debe seleccionar la organización que contiene el proyecto en el menú Organizations de la barra de navegación.
Si aún no se muestra, seleccione su proyecto en el menú Projects de la barra de navegación.
En la barra lateral, haz clic en Data Federation en la sección Services.
Se muestra la página Data Federation.