O MongoDB SQL Schema Builder CLI é a ferramenta de gerenciamento de esquema para implementações autogerenciadas Enterprise Advanced (EA) da Interface SQL. Você baixa e executa a CLI em seu cluster para produzir o JSON schema. A interface SQL usa esse esquema para converter queries SQL em operações MongoDB .
Esta página explica o que é a ferramenta, o que é necessário para executá-la, como invocá-la e os sinalizadores que ela aceita. Para obter a visão geral do gerenciamento de esquemas e os outros tipos de sistemas compatíveis, consulte Gerenciamento de esquemas.
Casos de uso
Use o Construtor de Esquema SQL do MongoDB quando executar a interface SQL em uma implantação autogerenciada da EA e precisar gerar ou atualizar o esquema para suas collections. O CLI é o caminho de gerenciamento de esquema suportado para este tipo de implantação.
A CLI não coleta amostras dos seus dados. Em vez disso, ele analisa cada documento em cada collection processada, de modo que o esquema gerado reflita com precisão os dados exatos nas collections. Mesmo os campos que aparecem em apenas uma pequena fração dos documentos são incluídos no esquema.
A recuperação do esquema é sempre iniciada pelo usuário. A CLI não atualiza um esquema automaticamente ou em um agendamento. Você deve gerar novamente um esquema sempre que a forma dos dados subjacentes for alterada, para que a interface SQL opere com as informações do esquema fornecidas.
Pré-requisitos
Antes de executar o CLI do Construtor de Esquemas SQL do MongoDB , certifique-se de atender aos seguintes requisitos:
Seu sistema é um cluster MongoDB Enterprise . A CLI não oferece suporte a clusters de MongoDB Community .
Você pode se conectar ao cluster a partir da máquina onde executa a CLI, com uma string de conexão (
--uri) ou um arquivo de configuração (--file).O usuário de banco de dados que a CLI autentica tem, no mínimo:
O privilégio do
readem cada banco de dados que você deseja processar. Este privilégio permite que a CLI enumera e analise suas collections.Os privilégios
find,inserteupdatena collection__sql_schemasem cada banco de dados que você processar, ou a funçãoreadWriteno banco de dados. A CLI grava cada esquema com um upsert, portanto, o privilégioupdateé necessário mesmo na primeira execução.
Você pode fornecer credenciais com os sinalizadores --username e --password ou incluí-las na string de conexão. Se você não fornecer as credenciais, a CLI tentará se conectar sem autenticação e registrará um aviso.
Invoque a CLI
Você executa a CLI do MongoDB SQL Schema Builder a partir da linha de comando em seu cluster para gerar ou atualizar um esquema. O binário é denominado mongodb-schema-manager.
O exemplo seguinte analisa cada collection no banco de dados do sales e grava registros de rastreamento em um diretório do logs:
mongodb-schema-manager \ --uri "mongodb://<host>:<port>" \ --ns-include "sales.*" \ --logpath ./logs \ --verbosity info
Quando a execução for concluída, a CLI imprime os bancos de dados e os namespaces para os quais criou ou modificou um esquema. Se algum namespace tiver um nível de polimorfismo grande demais para uso significativo, ele será considerado instável. A CLI lista esses namespaces. Para mais informações, consulte Esquemas instáveis.
Como os esquemas são armazenados
A CLI grava um documento de esquema por namespace em uma coleção do __sql_schemas em cada banco de dados que ela processa.
Importante
Trate a coleção __sql_schemas como um namespace reservado para a interface SQL. Não o modifique manualmente. Use a CLI para criar e atualizar os esquemas que ela contém.
Inspecionar esquemas armazenados
Para revisar os esquemas que o CLI gerou, execute um pipeline de agregação na coleção __sql_schemas no banco de dados que você deseja inspecionar. Cada documento relata os seguintes metadados:
lastUpdated: a data e a hora da gravação do esquema mais recente.unstable: Se o esquema é instável. Para mais informações, consulte Esquemas instáveis.
Para listar o status de cada esquema em um banco de dados sem imprimir o corpo completo do esquema, execute o seguinte pipeline no mongosh:
db.__sql_schemas.aggregate([ { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1 } }, { $sort: { namespace: 1 } } ])
Para visualizar o esquema completo de uma coleção específica, corresponda seu nome:
db.__sql_schemas.aggregate([ { $match: { _id: "<collection-name>" } }, { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1, schema: 1 } } ])
Por padrão, a CLI exclui implicitamente qualquer banco de dados ou collection cujo nome comece com dois sublinhados (__), incluindo a própria collection __sql_schemas. Para incluir esses namespaces, você deve especificá-los explicitamente com --ns-include. Por exemplo, --ns-include "*.__*" inclui collections que começam com __ em bancos de dados que não começam com __.
O CLI deriva o esquema de uma visualização do pipeline de visualização e os esquemas das coleções de origem que o pipeline referencia. Em condições normais, a CLI não amostra visualizações. Para garantir que o esquema derivado de uma visualização seja preciso, primeiro gere esquemas atualizados para as collections de origem.
Se não existir nenhum esquema para uma coleção de origem ou se a CLI não puder derivar o esquema a partir dos esquemas de coleção de origem disponíveis, a CLI voltará a executar a visualização e amostrar seus documentos de saída.
Referência de sinalizador CLI
A CLI do Construtor de Esquema SQL do MongoDB aceita as seguintes sinalizações. Você deve fornecer --uri ou --file para que a CLI possa se conectar ao seu cluster.
-f, --file <CONFIG_FILE>- O caminho para um arquivo de configuração. Os argumentos da linha de comando têm precedência sobre os valores no arquivo de configuração.
--uri <URI>- A string de conexão do seu cluster.
-u, --username <USERNAME>- O nome de usuário para autenticação. Você também pode especificar o nome de usuário na string de conexão.
-p, --password <PASSWORD>- A senha para autenticação. Você também pode especificar a senha na string de conexão.
--ns-include <NS_INCLUDE>- Os bancos de dados e coleções a serem incluídos, no formato
<database_pattern>.<collection_pattern>. A sintaxe de Glob é suportada, comomydb.*. Repita o sinalizador para especificar vários padrões. Se você omitir este sinalizador, a CLI incluirá todos os bancos de dados e collections. Os namespaces que começam com__são implicitamente excluídos, a menos que você os especifique explicitamente. --ns-exclude <NS_EXCLUDE>- Os bancos de dados e coleções para excluir, no mesmo formato que
--ns-include. Repita o sinalizador para especificar vários padrões. Este sinalizador tem precedência sobre--ns-include. --quiet- Habilita o modo silencioso para menos saída. Padrão:
false. -o, --logpath <LOGPATH>- O diretório onde a CLI grava arquivos de log. Os arquivos de log são denominados
mongodb-schema-manager.log.{date}. Se você omitir este sinalizador, a CLI não gravará arquivos de log. -v, --verbosity <VERBOSITY>- O nível de registro a ser capturado no arquivo de log. Exige
--logpath. Aceitatrace,debug,info,warnouerror. Padrão:warn. -a, --action <SCHEMA_ACTION>A ação a ser executada no esquema. Padrão:
merge. Aceita os seguintes valores:merge: mescla o novo esquema com o esquema existente. Se não existir nenhum esquema, esta ação criará um. Esta ação não atualiza esquemas instáveis.overwrite: Ignora e substitui o esquema existente. Se não existir nenhum esquema, esta ação criará um. Use essa ação para atualizar um esquema instável.clear: remove o camposchemado documento de esquema existente. Se não existir nenhum esquema, esta ação capturará somente metadados.
--dry-run- Executa uma execução seca sem analisar esquemas ou gravar no banco de dados. Use este sinalizador para testar seus padrões
--ns-includee--ns-exclude. Padrão:false. --resolver <RESOLVER>- O resolvedor de DNS a ser usado se a resolução de DNS falhar ou for lenta. Aceita
cloudflare,googleouquad9. -j, --jobs <JOBS>- O número máximo de tarefas simultâneas de processamento de esquema. Deve ser um número inteiro maior que
0. Padrão: duas vezes o número de núcleos físicos.
Esquemas instáveis
Quando os documentos de uma collection variam muito em forma, como collections que usam nomes de campo como chaves de mapa, a CLI marca o esquema derivado como instável. Um esquema instável define unstable como true no documento de esquema, limita o número de campos capturados e define additionalProperties como true. Um esquema instável pode não representar totalmente os dados no namespace.
Quando uma execução produz um ou mais esquemas instáveis, a CLI imprime os namespaces afetados:
The following namespaces have unstable schemas. They may not fully represent the data in the namespace. Unstable schemas are not updated by the schema-manager by default. To update them, use the 'overwrite' action.
A ação merge padrão não atualiza um esquema instável. Para atualizar um esquema instável, execute a CLI com --action overwrite.
Quando regenerar um esquema
Regenere um esquema quando a forma dos dados subjacentes for alterada, como quando você adicionar campos, remover campos ou alterar o tipo de dados de um campo existente. A CLI não detecta alterações na forma de dados por conta própria, portanto, a recuperação é sempre iniciada pelo usuário. Um esquema desatualizado pode fazer com que a interface SQL mapeie coleções para as tabelas e colunas erradas.