O que um snapshot guarda
Os nomes chegam qualificados quando a tabela fica fora do namespace padrão. O PostgreSQL retorna
accounting.invoices para uma tabela em outro esquema e apenas users para uma no public. O SQL Server aplica a mesma regra em torno do dbo. O Oracle retorna OWNER.TABLE quando o owner difere do usuário conectado.
Um snapshot carrega nomes e nada além disso. Ele não guarda linhas, nem credenciais, nem string de conexão. Tabelas de sistema nunca chegam a ele: o adaptador do banco descarta pg_*, information_schema e as views de dicionário do Oracle antes de o snapshot sair do adaptador.
Descoberta ao vivo e descoberta em cache
O Manager expõe duas superfícies de esquema, e elas diferem de propósito.
A separação segue os dois casos de uso. Quem pede um esquema quer a verdade atual, muitas vezes logo depois de uma migração adicionar uma coluna. A validação roda na entrada de todo job, então uma ida ao banco de dados a cada chamada custaria muito mais do que devolve.
A descoberta segue uma ordem fixa, e cada portão roda antes de o próximo adquirir qualquer coisa:
1
Checar o tenant
O Fetcher valida o escopo do tenant antes de tocar em qualquer recurso.
2
Resolver a conexão
O Fetcher resolve a conexão dentro desse escopo. Uma conexão desconhecida — ou uma que pertence a outro tenant — para aqui como
404 Not Found.3
Consultar o cache
No caminho que usa cache primeiro, um acerto retorna de imediato. O Fetcher não constrói conector e não abre sessão de banco de dados.
4
Abrir a fonte de dados
Em uma falha de cache, o Fetcher resolve o driver do tipo de fonte de dados, abre um conector e lê o catálogo. Ele fecha o conector em todo caminho, sucesso ou falha.
5
Gravar no cache
O Fetcher armazena o snapshot sob o tenant e o nome da configuração, e então o retorna.
O que o cache de esquema entrega
O cache transforma uma ida ao banco de dados em uma consulta local. Um acerto pula a construção do conector e a leitura do catálogo juntas, então um job que valida vinte tabelas em três fontes de dados não paga por nenhuma delas uma segunda vez dentro da janela.
- Chave. Toda leitura e toda escrita têm escopo no tenant e no nome da configuração. Um tenant nunca vê o snapshot de outro tenant e nunca o contamina.
- Duração. Cinco minutos por padrão.
SCHEMA_CACHE_TTL_SECONDSdefine isso no Manager. - Armazenamento de apoio. O Manager mantém o cache no Valkey ou no Redis, e cai para a memória do processo quando esse armazenamento está inacessível.
O cache é uma otimização, e o Fetcher o trata como tal. Uma leitura de cache que falha degrada para uma descoberta ao vivo. Uma escrita de cache que falha ainda retorna o snapshot descoberto para quem chamou. Nenhuma das duas falhas chega à sua resposta.
Rodar sem cache
Um hospedeiro que incorpora o Engine liga o cache de esquema como uma porta opcional, e muitos hospedeiros a deixam de fora. Sem ela, toda chamada de esquema descobre ao vivo na fonte de dados. A validação continua exatamente igual de correta — ela apenas paga a ida ao banco a cada vez. Adicione um cache quando o tráfego de validação se repete contra esquemas estáveis. Deixe-o de fora quando o hospedeiro roda extrações ocasionais, ou quando uma leitura ao vivo a cada chamada é o comportamento que você quer.Descoberta por banco de dados
As leituras de catálogo carregam um tempo limite de 30 segundos.
Inferência no MongoDB
O MongoDB não tem esquema declarado, então o Fetcher constrói um em duas passagens. Uma agregação sobre a coleção produz os nomes de campos. Uma amostra de até 50 documentos então dá a cada campo o tipo dele. A passagem de nomes de campos é limitada pelo tamanho da coleção. Em uma coleção de até 10.000 documentos, o Fetcher lê no máximo os primeiros 1.000. Acima de 10.000 documentos, ele usa uma amostra aleatória:
O snapshot nomeia os campos que esses documentos carregam. Um campo que aparece apenas fora da leitura — depois dos primeiros 1.000 documentos, ou fora da amostra aleatória — não está no snapshot.
Nomeie esse campo no
mappedFields do trabalho quando precisar dele. A extração projeta os nomes que você envia contra a própria coleção, então um campo que o snapshot omite é extraído mesmo assim. POST /v1/management/connections/validate-schema responde a partir do snapshot, então reporta esse campo como FIELD_NOT_FOUND.
Quando a agregação falha em uma coleção, o Fetcher cai para amostragem naquela coleção e continua. A descoberta das demais coleções segue em frente.
Validação antes da extração
POST /v1/management/connections/validate-schema recebe o mesmo mapa mappedFields que um job de extração carrega. Envie-o antes de submeter o job.
- Formato e contagens. A requisição permite 10 fontes de dados, 20 tabelas por fonte de dados e 50 campos por tabela. Uma violação é reportada antes de o Fetcher tocar em um banco de dados.
- Conexões. Toda fonte de dados nomeada precisa resolver para uma conexão dentro do escopo do tenant.
- Existência. Toda tabela e todo campo precisam existir no snapshot da fonte de dados.
success. Um mapeamento com problemas responde failure e nomeia cada um:
Um nome de campo casa com uma coluna exata, ou com o pai de um caminho pontuado. Uma requisição por
natural_person valida quando o snapshot guarda natural_person.mother_name. O MongoDB achata documentos aninhados em nomes pontuados, então referências ao pai são um padrão comum ali.DATA_SOURCE_DOWN contra aquela fonte de dados apenas, e as demais fontes de dados continuam sendo validadas.
Próximos passos
Jobs de extração
Submeta um job, acompanhe-o e leia o resultado.
Conexões
Registre, teste, atualize e exclua uma conexão com uma fonte de dados.
Fontes de dados
O que cada um dos cinco motores de banco de dados faz de diferente.
Conceitos centrais
O modelo do Fetcher em um só lugar.