/ /

Comandos de esquema do Atlas Data Federation

No Atlas Data Federation, você gerencia o esquema que a interface SQL usa por meio de três comandos: sqlGenerateSchema, sqlGetSchema e sqlSetSchema. Você executa esses comandos do mongosh em uma instância do banco de dados federado ou executa as ações equivalentes na IU do Atlas. Esta página documenta esses comandos e seus equivalentes de IU.

O Atlas Data Federation amostra documentos de suas coleções para gerar o esquema inicial. Para obter informações de segundo plano sobre o gerenciamento de esquemas e os outros tipos de implantação compatíveis, consulte Gerenciamento de esquemas.

Observação

The sqlGenerateSchema, sqlGetSchema, and sqlSetSchema commands and their Atlas UI equivalents apply only to the Atlas Data Federation deployment type. They don't apply to self-managed Enterprise Advanced (EA) deployments, which use the MongoDB SQL Schema Builder CLI, or to queries against a standard Atlas cluster that doesn't use Atlas Data Federation.

sqlGenerateSchema

O comando sqlGenerateSchema gera um esquema de interface SQL para as coleções ou visualizações especificadas. O Atlas Data Federation amostra documentos de cada namespace para derivar o esquema.

Sintaxe

Ao usar o parâmetro sampleNamespaces, você deve executar o comando no banco de dados admin.

use admin
db.runCommand({
   sqlGenerateSchema: 1,
   sampleNamespaces: [<namespace>],
   sampleSize: <int>,
   setSchemas: true|false
})

Parâmetros

Parâmetro	Tipo	Descrição	necessidade
`sampleNamespaces`	array de strings	Specifies the comma-separated list of namespaces for which to generate schemas. A namespace includes the database name, a dot (`.`) separator, and the collection or view name (that is, `<database>.<collection>\|<view>`). To generate schemas for all the collections in a database, specify `` instead of the collection or view name (that is, `<database>.`). If omitted, Atlas Data Federation generates schemas for all collections and views in the current database.	Opcional
`sampleSize`	inteiro	Especifica o número de documentos a serem usados como amostra para criar o esquema. Se omitido, o padrão é `1000`.	Opcional
`setSchemas`	booleano	Especifica se o esquema gerado para a coleção ou visualização deve ser armazenar. O valor pode ser um dos seguintes: `true` para armazenar o esquema. Se um esquema já existir para a coleção ou visualização, o Atlas Data Federation substituirá o esquema existente. `false` para não armazenar o esquema. Se omitido, o padrão é `false`.	Opcional

Saída

O comando retorna a seguinte saída se for bem-sucedido:

{
  "ok" : 1,
  "schemas" : [
    {
      "databaseName" : "<database-name>",
      "namespaces" : [
        {
          "name" : "<collection-name>",
          "schema" : {
            "version" : NumberLong(1),
            "jsonSchema" : { ... }
          }
        }
      ]
    },
    ...
  ]
}

O objeto schemas contém os seguintes campos.

Parâmetro	Tipo	Descrição
`databaseName`	string	Nome do banco de dados.
`namespaces`	Array de objetos	Nome e esquema gerado de cada coleção ou visualização.
`namespaces.name`	string	Nome da coleção ou visualização.
`namespaces[n].schema`	documento	Esquema da coleção ou visualização.
`namespaces[n].schema.version`	inteiro	Formatar versão do esquema. O valor é sempre 1.
`namespaces[n].schema.jsonSchema`	documento	JSON schema of the collection or view. The JSON schema can contain the following fields: `bsonType` `properties` `items` `additionalProperties` `required` To learn more about these fields, see JSON Schema Keywords.

Se você definir o esquema para a coleção ou visualização com a opção setSchemas, poderá verificar se o comando foi bem-sucedido executando o comando sqlGetSchema. O campo metadata.description do comando sqlGetSchema contém o seguinte valor:

"set using sqlGenerateSchema with setSchemas = true"

Errors

O comando retorna o seguinte erro se falhar:

"failedNamespaces": [
  {
    "namespace" : "<db.ns>",
    "error" : "no documents found in sample namespace"
  }
]

O Atlas Data Federation retorna esse erro se os namespaces especificados não existirem na configuração de armazenamento ou estiverem vazios. O Atlas Data Federation também retorna esse erro se não conseguir definir o esquema para um determinado namespace.

sqlGetSchema

O comando sqlGetSchema recupera o esquema armazenado para a coleção ou visualização especificada.

Sintaxe

db.getSiblingDB("<dbName>").runCommand({
   sqlGetSchema: "<collection-name>|<view-name>"
})

Parâmetros

Parâmetro	Tipo	Descrição	necessidade
`<collection-name>`	string	Nome da coleção para a qual recuperar o esquema. Forneça o nome da coleção ou o nome da exibição.	Condicional
`<view-name>`	string	Nome da visualização para a qual recuperar o esquema. Forneça o nome da visualização ou o nome da coleção.	Condicional

Saída

O comando retorna a seguinte saída se a coleção ou visualização não tiver um esquema:

{ "ok" : 1, "metadata" : { }, "schema" : { } }

O comando retorna uma saída semelhante à seguinte se a coleção ou visualização tiver um esquema:

{
  "ok": 1,
  "metadata": {
    "description": "<description>"
  },
  "schema": {
    "version": NumberLong(1),
    "jsonSchema": { ... }
  }
}

O campo metadata.description descreve como o esquema foi definido para a coleção. O valor pode ser um dos seguintes:

generated automatically by Atlas Data Federation: Indica que o esquema foi gerado automaticamente pelo Atlas Data Federation.

set using sqlGenerateSchema with setSchemas = true: Indicates that the schema was set by the sqlGenerateSchema command because the setSchema option was set to true.

set using sqlSetSchema: Indicates that the schema was set using the sqlSetSchema command.

O documento schema contém os seguintes campos:

Parâmetro	Tipo	Descrição
`schema.version`	inteiro	Formatar versão do esquema. O valor é sempre 1.
`schema.jsonSchema`	documento	JSON schema of the collection or view. The JSON schema can contain the following fields: `bsonType` `properties` `items` To learn more about these fields, see JSON Schema Keywords.

sqlSetSchema

O comando sqlSetSchema define ou remove o esquema para uma coleção ou visualização. O comando aplica o esquema que você fornece diretamente. O comando não valida o esquema fornecido em relação aos dados na coleção.

Sintaxe

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

Parâmetro	Tipo	Descrição	necessidade
`<collection-name>`	string	Nome da coleção para a qual definir o esquema. Forneça um nome de coleção ou um nome de exibição.	Condicional
`<view-name>`	string	Nome da exibição para a qual definir o esquema. Forneça um nome de exibição ou um nome de coleção.	Condicional
`schema`	documento	A versão do formato do esquema e: o JSON schema para a collection ou visualização um documento vazio para remover o esquema da coleção ou visualização Você pode fornecer um único documento ou uma array de documentos no campo `items` . Ao recuperar o esquema, `items` mostra o formulário que você usou para definir o esquema.	Obrigatório

Saída

O comando retorna a seguinte saída se for bem-sucedido:

{ "ok" : 1 }

Você pode verificar se o comando foi bem-sucedido executando o comando sqlGetSchema . O campo metadata.description na resposta contém o seguinte valor:

"set using sqlSetSchema"

Exemplos

Considere uma coleção denominada egData em um banco de dados denominada sampleDB com os seguintes 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}

Os exemplos a seguir usam os comandos de esquema do Atlas Data Federation para gerar, recuperar, definir e remover o esquema da coleção anterior.

Gerar um esquema

O comando a seguir gera um esquema para a coleção denominada sampleDB.egData na configuração de armazenamento. O comando utiliza dois documentos selecionados aleatoriamente da coleção para criar o esquema, pois o sampleSize é 2. O comando não define o esquema para a coleção porque a opção setSchemas não é especificada e o padrão é false.

use admin
db.runCommand({
   sqlGenerateSchema: 1,
   sampleNamespaces: ["sampleDB.egData"],
   sampleSize: 2
})

O comando anterior retorna a seguinte saída. Para saber mais sobre os campos na saída, consulte Saída.

{
  "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" ]
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Gerar e definir um esquema

O comando a seguir gera um esquema para a coleção denominada sampleDB.egData na configuração de armazenamento. O comando utiliza até 1000 documentos na coleção para criar o esquema, pois a opção sampleSize não é especificada e padrão para 1000. O comando define o esquema gerado como o esquema a ser usado para a coleção porque setSchemas é true.

use admin
db.runCommand({
   sqlGenerateSchema: 1,
   sampleNamespaces: ["sampleDB.egData"],
   setSchemas: true
})

Retrieve a Schema

O comando a seguir recupera o esquema armazenado para a coleção egData:

db.getSiblingDB("sampleDB").runCommand({
   sqlGetSchema: "egData"
})

O comando anterior retorna a seguinte saída. Para saber mais sobre os campos na saída, consulte Saída.

{
  "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 um esquema

O seguinte comando sqlSetSchema define o esquema para a coleção 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" ]
            }
         }
      }
   }
})

O comando anterior retorna a seguinte saída:

{ "ok" : 1 }

Remover um esquema

O comando sqlSetSchema a seguir remove o esquema da coleção egData passando um documento schema vazio:

db.getSiblingDB("sampleDB").runCommand({
   sqlSetSchema: "egData",
   schema: {}
})

O comando anterior retorna a seguinte saída:

{ "ok" : 1 }

Gerenciar esquemas na IU do Atlas

Você pode executar as mesmas ações de esquema na IU do Atlas na página Manage SQL Schemas. A IU amostra documentos para gerar esquemas, o mesmo que o comando sqlGenerateSchema.

Criar um esquema

Quando você cria uma conexão de início rápido, o Atlas Data Federation gera o esquema automaticamente. Para criar um esquema manualmente, use o seguinte procedimento.

No Atlas, acesse sua instância de banco de dados federado para seu projeto.

Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Data Federation sob o título Services.

A página Data Federation é exibida.

Navegue até a página Gerenciar esquemas SQL.

Na seção Federated Database Instances , clique em ícone à direita do esquema e selecione Manage SQL Schemas no menu suspenso.

Crie um esquema.

Em uma coleção que tem um esquema vazio:

Clique em .
Clique Generate new schema from sample ou forneça seu próprio JSON.
Clique em Save.

Gerar novamente um esquema

Regenerate a schema any time the shape of your underlying data changes, such as when you add fields or change field types, so that your SQL queries reflect the current data. To keep schemas current automatically instead, see Schedule Schema Updates.

No Atlas, acesse sua instância de banco de dados federado para seu projeto.

Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Data Federation sob o título Services.

A página Data Federation é exibida.

Navegue até a página Gerenciar esquemas SQL.

Na seção Federated Database Instances , clique em ícone à direita do esquema e selecione Manage SQL Schemas no menu suspenso.

Gerar novamente o esquema.

Em uma coleção que já tem um esquema:

Clique em .
Clique em Generate new schema from sample.
Clique em Save.

Visualizar um esquema

No Atlas, acesse sua instância de banco de dados federado para seu projeto.

Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Data Federation sob o título Services.

A página Data Federation é exibida.

Navegue até a página Gerenciar esquemas SQL.

Na seção Federated Database Instances , clique em ícone à direita do esquema e selecione Manage SQL Schemas no menu suspenso.

Nesta página, você pode visualizar todos os esquemas existentes. Para visualizar um esquema específico no formato JSON, clique em .

Editar esquema

No Atlas, acesse sua instância de banco de dados federado para seu projeto.

Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Data Federation sob o título Services.

A página Data Federation é exibida.

Navegue até a página Gerenciar esquemas SQL.

Na seção Federated Database Instances , clique em ícone à direita do esquema e selecione Manage SQL Schemas no menu suspenso.

Edite o esquema.

Ao lado de um esquema, clique em .
Edite o JSON.
Clique em Save.

Excluir um esquema

No Atlas, acesse sua instância de banco de dados federado para seu projeto.

Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Data Federation sob o título Services.

A página Data Federation é exibida.

Navegue até a página Gerenciar esquemas SQL.

Na seção Federated Database Instances , clique em ícone à direita do esquema e selecione Manage SQL Schemas no menu suspenso.

Nesta página, você pode visualizar todos os esquemas existentes.

Exclua o esquema.

Para o esquema que você deseja excluir, clique em .
Clique em Clear....
Clique em Clear schema para confirmar.

Excluir todos os esquemas

No Atlas, acesse sua instância de banco de dados federado para seu projeto.

Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Data Federation sob o título Services.

A página Data Federation é exibida.

Navegue até a página Gerenciar esquemas SQL.

Na seção Federated Database Instances , clique em ícone à direita do esquema e selecione Manage SQL Schemas no menu suspenso.

Nesta página, você pode visualizar todos os esquemas existentes.

Exclua todos os esquemas.

Clique no ícone no canto superior direito.
Clique em Clear all schemas.
Clique em Clear all schemas novamente para confirmar.

Atualizações do esquema de agendamento

As atualizações de esquema agendadas ajudam a manter a precisão do esquema ao longo do tempo. As atualizações de esquema agendadas amostram cada namespace e mesclam o novo esquema com o existente. Por exemplo, as atualizações de esquema agendadas permitem que o Atlas Data Federation colete automaticamente novos campos adicionados às coleções.

No Atlas, acesse sua instância de banco de dados federado para seu projeto.

Se ainda não tiver sido exibido, selecione a organização que contém seu projeto no menu Organizations na barra de navegação.
Se ainda não estiver exibido, selecione seu projeto no menu Projects na barra de navegação.
Na barra lateral, clique em Data Federation sob o título Services.

A página Data Federation é exibida.

Navegue até a página Gerenciar esquemas SQL.

Na seção Federated Database Instances , clique em ícone à direita do esquema e selecione Manage SQL Schemas no menu suspenso.

Ative as atualizações de esquema agendadas.

Clique em Configure schema update schedule.
Selecione uma frequência.
Clique em Save.

Saiba mais

Voltar

CLI do Construtor de Esquema SQL do MongoDB

Tutoriais do SQL