The MongoDB SQL Schema Builder CLI is the schema-management tool for the SQL Interface on Enterprise Advanced (EA) self-managed deployments and on Atlas dedicated clusters (M10 and above). You download and run the CLI against your cluster to generate or update the schema for your collections. The SQL Interface uses those schemas to translate SQL queries into MongoDB operations.
A CLI não amostra seus dados. Em vez disso, ele analisa cada documento em cada coleção que processa, para que o esquema gerado reflita com precisão os dados exatos nas coleções. Até mesmo os campos que aparecem em apenas uma pequena fração de documentos são incluídos no esquema.
A regeneração do esquema é sempre iniciada pelo usuário. A CLI não atualiza um esquema automaticamente ou de acordo com agendar. Você deve regenerar um esquema sempre que a forma dos seus dados subjacentes mudar, para que a SQL Interface opere com as informações de esquema fornecidas. Se você precisar de atualizar periodicamente, poderá automatizá-las configurando uma tarefa cron para executar o comando de regeneração para agendar.
Pré-requisitos
Antes de executar o MongoDB SQL Schema Builder CLI, certifique-se de atender aos seguintes requisitos:
Your deployment is either a MongoDB Enterprise cluster (Enterprise Advanced (EA) self-managed) or a dedicated cluster (
M10and above) running MongoDB 6.0 or later (Atlas). The CLI does not support MongoDB Community clusters, Free clusters, Flex clusters, orM2andM5shared Atlas clusters.Em um cluster dedicado, a SQL Interface é habilitada para cada cluster que você deseja fazer query com SQL. Para saber mais, consulte Configurar do servidor da SQL Interface.
A CLI do MongoDB SQL Esquema Builder é compatível com seu sistema operacional e arquitetura:
Windows
x86_64.Linux
x86_64earm64: OpenSSL 1.0 com glibc 2.26 ou posterior, OpenSSL 1.1 com glibc 2.28 ou posterior, ou OpenSSL 3.0 com glibc 2.28 ou posterior. O MongoDB recomenda o OpenSSL 3.0 ou posterior para conexões seguras.
Você pode se conectar ao cluster a partir da máquina onde você executa a CLI com uma string de conexão.
O usuário de banco de dados que a CLI autentica tem, no mínimo:
O privilégio
readem cada banco de dados que você deseja processar. Esse privilégio permite que a CLI enumere e analise suas coleções.Os privilégios
find,inserteupdatena coleção__sql_schemasem cada banco de dados que você processa, ou a funçãoreadWriteno banco de dados. A CLI grava cada esquema com um upsert, portanto, o privilégioupdateé necessário mesmo ao executar pela primeira vez.Em um cluster dedicado, o privilégio
readno banco de dados__mdb_internal_sqlinterface.
Você pode fornecer credenciais com os sinalizadores --username e --password ou incluí-las na string de conexão. Se você não fornecer credenciais, a CLI tentará se conectar sem autenticação e registrará um log de aviso.
Invocar a CLI
Você executa o MongoDB SQL Schema Builder CLI na linha de comando em seu cluster para gerar ou atualizar um esquema. O binário é chamado mongodb-schema-manager.
Obtenha uma string de conexão
A CLI precisa de uma string de conexão (--uri) para se conectar ao seu cluster. Você também pode fornecer um arquivo de configuração (--file) para não precisar redigitar os argumentos a cada execução.
O exemplo a seguir analisa cada coleção no banco de dados sales e grava logs de rastreamento em um diretório logs:
mongodb-schema-manager \ --uri "mongodb://<host>:<port>" \ --ns-include "sales.*" \ --logpath ./logs \ --verbosity info
When the run completes, the CLI prints the databases and namespaces for which it created or modified a schema. If any namespace has a level of polymorphism too great for meaningful use, it is deemed unstable. The CLI lists those namespaces. For more information, see Unstable Schemas.
Como os esquemas são armazenados
A CLI grava um documento de esquema por namespace em uma coleção __sql_schemas em cada banco de dados que 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 ele contém.
Inspecionar esquemas armazenados
Para revisar os esquemas gerados pela CLI, 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 de esquema mais recente.unstable: Whether the schema is unstable. For more information, see Unstable Schemas.
Para listar o status de cada esquema em um banco de dados sem imprimir o corpo completo do esquema, execute o seguinte pipeline em mongosh:
db.getCollection("__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 ao seu nome:
db.getCollection("__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 coleção cujo nome comece com dois sublinhados (__), incluindo a própria coleção __sql_schemas. Para incluir esses namespaces, você deve especificá-los explicitamente com --ns-include. Por exemplo, --ns-include "*.__*" inclui coleções que começam com __ em bancos de dados que não começam com __.
A CLI deriva o esquema de uma visualização do pipeline de visualização e dos esquemas das coleções de origem que o pipeline referencia. Em condições normais, a CLI não visualiza amostras. Para garantir que o esquema derivado de uma visualização seja preciso, primeiro gere esquemas atualizados para as coleções de origem.
Se não houver esquema para uma coleção de origem ou se a CLI não puder derivar o esquema 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 MongoDB SQL Schema Builder aceita os seguintes sinalizadores. 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 para o 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 as coleções a serem incluídos, no formato
<database_pattern>.<collection_pattern>. A sintaxe Glob é compatível, comomydb.*. Repita o sinalizador para especificar vários padrões. Se você omitir esse sinalizador, a CLI incluirá todos os bancos de dados e coleções. 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 a serem excluídos, no mesmo formato que
--ns-include. Repita o sinalizador para especificar vários padrões. Este sinalizador tem precedência sobre--ns-include. --quiet- Ativa 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 nomeados
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 log a ser capturado no arquivo de log. Requer
--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 nenhum esquema existir, esta ação criará um. Esta ação não atualiza esquemas instáveis.overwrite: Ignora e substitui o esquema existente. Se nenhum esquema existir, esta ação criará um. Use esta ação para atualizar um esquema instável.clear: Remove o camposchemado documento de esquema existente. Se não houver esquema, esta ação captura apenas metadados.
--dry-run- Executa uma execução de teste 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 de esquema em processamento simultâneas. 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 coleção variam muito em forma, como coleções 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 do 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 ação de executar produz um ou mais esquemas instáveis, a CLI imprime os namespace 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 gerar novamente um esquema
Regenere um esquema quando a forma dos dados subjacentes for alterada, como quando você adiciona campos, remove campos ou altera o tipo de dados de um campo existente. O CLI não detecta alterações na forma dos dados por conta própria, portanto, a regeneraçã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.
Saiba mais
Visão geral do MongoDB gerente de esquema (PDF): Referência técnica completa para o MongoDB SQL Construtor de esquema.