/ /

Comandos do Esquema do Atlas Data Federation

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

O Atlas Data Federation coleta amostras de documentos de suas coleções para gerar o esquema inicial. Para obter informações básicas sobre o gerenciamento de esquemas e os outros tipos de sistema suportados, consulte Gerenciamento de esquemas.

Observação

Os sqlGenerateSchema sqlGetSchema sqlSetSchema comandos, e e seus equivalentes da UI do Atlas se aplicam somente ao tipo de sistema Atlas Data Federation . Eles não se aplicam a sistemas Enterprise Advanced (EA) autogerenciados, que usam o CLI do MongoDB SQL Schema Builder, ou a queries em um Atlas cluster padrão que não usa o Atlas Data Federation.

sqlGenerateSchema

O comando sqlGenerateSchema gera um esquema de interface SQL para as collections ou visualizações especificadas. O Atlas Data Federation coleta amostras de 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	Especifica a lista separada por vírgula de namespaces para os quais gerar esquemas. Um namespace inclui o nome do banco de dados , um separador de ponto ()`.` e a coleção ou nome de visualização (isto`<database>.<collection>\|<view>` é,). Para gerar esquemas para todas as coleções em um banco de dados, especifique `` da coleção ou nome de visualização (isto`<database>.` é,). Se omitido, o Atlas Data Federation gera esquemas para todas as coleções e visualizações no banco de dados atual.	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 deseja armazenar o esquema gerado para a coleção ou visualização. 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 retornará 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	Esquema JSON da coleção ou visualização. O esquema JSON pode conter os seguintes campos: `bsonType` `properties` `items` `additionalProperties` `required` Para saber mais sobre esses campos, consulte Palavras-chave do JSON schema.

Se você definir o esquema da coleção ou visualização com a opção setSchemas, poderá verificar se o comando foi bem-sucedido executando o comando sqlGetSchema. O campo sqlGetSchema comando metadata.description 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 puder 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 collection ou o nome da visualizaçã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 collection.	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 retornará uma saída semelhante à seguinte se a collection 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: Indica que o esquema foi definido pelo comando sqlGenerateSchema porque a setSchema opção foi definida true como.

set using sqlSetSchema: Indica que o esquema foi definido usando o comando sqlSetSchema.

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	Esquema JSON da coleção ou visualização. O esquema JSON pode conter os seguintes campos: `bsonType` `properties` `items` Para saber mais sobre esses campos, consulte Palavras-chave do JSON schema.

sqlSetSchema

O comando sqlSetSchema define ou remove o esquema de uma coleção ou visualização. O comando aplica o esquema fornecido diretamente. O comando não valida o esquema fornecido em relação aos dados da 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 collection para a qual definir o esquema. Forneça um nome de collection ou um nome de visualização.	Condicional
`<view-name>`	string	Nome da visualização para a qual definir o esquema. Forneça um nome de visualização ou um nome de collection.	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 retornará 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 seguintes utilizam os comandos de esquema do Atlas Data Federation para gerar, recuperar, configurar e remover o esquema para a coleção anterior.

Gerar um esquema

O seguinte comando 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 seguinte comando 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 do 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 collection 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 UI do Atlas

Você pode executar as mesmas ações de esquema na UI do Atlas a partir da página Manage SQL Schemas. Os documentos de amostras da UI para gerar esquemas, os mesmos do 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 procedimento a seguir.

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.

Regenerar um esquema

Regenere um esquema sempre que a forma dos dados subjacentes for alterada, como ao adicionar campos ou alterar os tipos de campo , para que as queries SQL reflitam os dados atuais. Para manter os esquemas atualizados automaticamente, consulte Agendar atualizações de 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.

Regenere o esquema.

Em uma collection que já possui 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 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.

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 programadas 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, atualizações de esquema agendadas permitem que Atlas Data Federation escolha automaticamente novos campos adicionados a collections.

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