Sincronização e escaneamento de bancos de dados
Sincronização e escaneamento de bancos de dados
O Analytics executa periodicamente diferentes tipos de consultas em seu data warehouse para se manter atualizado com os metadados do seu banco de dados. Conhecer informações sobre seus dados ajuda o Analytics a fazer coisas como exibir automaticamente o gráfico adequado para os resultados e preencher menus suspensos em widgets de filtro.
- Sincronizar esquema do banco de dados: obtém o esquema do banco de dados, estruturas de tabelas, campos, restrições (chaves primárias e estrangeiras) e desativa tabelas excluídas.
- Escanear valores de campo: realiza amostragens dos valores das colunas para preencher menus suspensos de filtro, encontrar valores distintos e identificar visualizações válidas. O Analytics não armazena tabelas completas do seu banco de dados.
- Fingerprinting: amostra as primeiras 10.000 linhas da tabela para calcular estatísticas para cada campo na amostra dependendo do tipo, notavelmente: contagem de valores distintos, % de valores nulos (todos os tipos de campo), média, mediana, mínimo, máximo e quartis (tipos numéricos).
Sincronização, escaneamento e fingerprinting inicial
Quando o Analytics se conecta pela primeira vez ao seu banco de dados, ele executa uma sincronização para determinar os metadados das colunas em suas tabelas e atribuir automaticamente a cada coluna um tipo semântico.
Você pode acompanhar o progresso dessas consultas em Ícone de engrenagem > Configurações de administração > Ferramentas > Tarefas, filtrando pelas diversas tarefas de sincronização.
Após a execução das consultas, você pode visualizar e editar os metadados sincronizados em Configurações de administração > Metadados da tabela. Para mais informações, consulte editando metadados.
Escolher quando as sincronizações e escaneamentos acontecem
Por padrão, o Analytics realiza uma sincronização leve a cada hora e um escaneamento intensivo dos valores dos campos uma vez por dia. Se você possui um banco de dados grande, pode ser interessante escolher quando as sincronizações e escaneamentos aconteçam.
- Clique no Ícone de engrenagem.
- Selecione Configurações de administração.
- Acesse Bancos de dados.
- Selecione seu banco de dados.
- Na seção Conexão e sincronização, clique em Editar detalhes da conexão.
- Expanda Mostrar opções avançadas.
- Ative a opção Escolher quando sincronizações e escaneamentos acontecem.
A partir daí, você poderá definir os horários para as sincronizações e escaneamentos.
Sincronização do banco de dados
As opções incluem:
- A frequência da sincronização: horária (padrão) ou diária.
- O horário para executar a sincronização, no fuso horário do servidor onde seu app Analytics está rodando.
Escaneamento para valores de filtro
Os escaneamentos incluem apenas “campos ativos”: campos que tenham sido usados nos últimos quatorze dias. O Analytics não escaneará campos que não foram usados há mais de quatorze dias. Campos que se tornarem inativos voltarão a ser ativos quando alguém os utilizar, e o Analytics os incluirá no próximo escaneamento.
As opções incluem:
- Regularmente, em um agendamento possibilita rodar as consultas de escaneamento com a frequência que corresponde à taxa de alteração do seu banco de dados. O horário é definido no fuso horário do servidor onde o app Analytics está rodando. Esta é a melhor opção para bancos de dados pequenos ou tabelas com valores distintos que são atualizados frequentemente.
- Apenas quando adicionar um novo widget de filtro é uma ótima opção se você quer que as consultas de escaneamento sejam executadas sob demanda. Ativar essa opção liga o comportamento de que o Analytics apenas escaneará e armazenará em cache os valores dos campo(s) usados quando alguém adicionar um novo widget de filtro a um dashboard ou pergunta SQL (isto é, adicionarem um parâmetro em sua consulta SQL).
- Nunca, farei isso manualmente se precisar é uma opção para bancos de dados extremamente grandes ou que raramente têm novos valores adicionados. Use o botão Re-escanear valores do campo para executar um escaneamento manual e atualizar os valores dos filtros.
Independentemente da opção escolhida, se você configurar um campo para usar uma lista suspensa em widgets de filtro, o Analytics precisará obter valores para essa lista. Sempre que alguém usar esse widget de filtro, o Analytics primeiro buscará valores armazenados em cache (válidos por quatorze dias) para preencher a lista; caso contrário, ele re-escaneará esse campo para obter os valores mais atualizados.
Sincronizando tabelas e colunas manualmente
- Acesse Configurações de administração > Bancos de dados > seu banco de dados.
- Clique em Sincronizar esquema do banco de dados.
Escaneando valores de colunas manualmente
Para escanear valores de todas as colunas de uma tabela:
- Acesse Configurações de administração > Metadados da tabela > seu banco de dados.
- Selecione a tabela que deseja atualizar de acordo com seu banco de dados.
- Clique no ícone de engrenagem no topo da página.
- Clique em Re-escanear esta tabela.
Para escanear valores de uma coluna específica:
- Acesse Configurações de administração > Metadados da tabela > seu banco de dados.
- Selecione a tabela.
- Encontre a coluna que deseja atualizar.
- Clique no ícone de engrenagem no painel da coluna.
- Clique em Re-escanear este campo.
Limpar valores em cache para uma tabela ou campo
Para limpar os valores de campo escaneados para uma tabela:
- Acesse Configurações de administração > Metadados da tabela.
- Selecione o banco de dados e a tabela.
- Clique no ícone de engrenagem no canto superior direito.
- Clique em Descartar valores de campo em cache.
Também é possível fazer o Analytics esquecer os valores em cache para campos individuais clicando no ícone de engrenagem de um campo e selecionando Descartar valores de campo em cache.
Desabilitar sincronização e escaneamento para tabelas específicas
Para evitar que o Analytics execute sincronizações e escaneamentos em uma tabela específica, altere a visibilidade da tabela para Oculta:
- Acesse Configurações de administração > Metadados da tabela > seu banco de dados.
- Passe o mouse sobre o nome da tabela na barra lateral.
- Clique no ícone de olho.
Ocultar uma tabela também impedirá que ela apareça no construtor de consultas e na referência de modelo de dados. Usuários ainda podem consultar tabelas ocultas pelo editor SQL.
Sincronização e escaneamento via API
O Analytics realiza sincronizações e escaneamentos regularmente, mas se o administrador do banco de dados acabou de alterar o esquema ou se muitos dados são adicionados automaticamente em horários específicos, você pode criar um script que utilize a API do Analytics para forçar uma sincronização ou escaneamento. A API oferece duas formas de iniciar uma sincronização ou escaneamento de um banco de dados:
Sincronizar ou escanear o banco de dados
Você pode usar esses endpoints autenticando com um ID de usuário e passando um token de sessão no cabeçalho da requisição.
- Sincronizar esquema do banco de dados:
/api/database/{id}/sync_schema - Re-escanear valores de campo:
/api/database/{id}/rescan_values
Sincronizar uma única tabela
/api/notify/db/{id}para informar o Analytics para sincronizar um banco de dados, ou opcionalmente uma tabela específica./api/notify/db/{id}/new-tablepara sincronizar uma tabela nova, sem sincronizar o banco de dados completo. Requerschema_nameetable_name.
Para usar esse endpoint, você deve passar uma string via a variável de ambiente MB_API_KEY. Essa string é diferente das chaves de API do Analytics.
Criamos o endpoint notify para que as pessoas possam informar ao seu Analytics para sincronizar após uma operação de ETL ser concluída.
Veja nossa documentação da API.
Como as sincronizações de banco de dados funcionam
Uma sincronização no Analytics é uma consulta que obtém uma lista de nomes atualizados de tabelas e views, nomes de colunas e tipos de dados das colunas do seu banco de dados:
SELECT
TRUE
FROM
"your_schema"."your_table_or_view"
WHERE
1 <> 1
LIMIT 0
Por padrão, essa consulta é executada durante a configuração e novamente a cada hora. Essa consulta costuma ser rápida na maioria dos bancos relacionais, mas pode ser mais lenta em MongoDB e alguns drivers comunitários. A sincronização não pode ser desativada completamente, pois o Analytics deixaria de funcionar.
Veja o tipo de dados que as sincronizações obtêm e o motivo:
| O quê | Por quê |
|---|---|
| Nomes das tabelas | Sem tabelas, o que estaríamos realmente fazendo? |
| Nomes dos campos | Sem campos, mesmo problema |
| Tipos de dados dos campos | Para consulta e manipulação dos tipos |
| Chaves primárias | Exibição da tabela, visualizações detalhadas e junções automáticas |
| Chaves estrangeiras | Junções automáticas e visualização de relacionamentos |
Como os escaneamentos de banco de dados funcionam
Um escaneamento no Analytics é uma consulta que armazena em cache os valores das colunas para os filtros dos menus suspensos, selecionando os primeiros 1.000 registros distintos de cada tabela, em ordem crescente:
SELECT
"your_table_or_view"."column" AS "column"
FROM
"your_schema"."your_table_or_view"
GROUP BY
"your_table_or_view"."column"
ORDER BY
"your_table_or_view"."column" ASC
LIMIT 1000
Para cada registro, o Analytics armazena somente os primeiros 100 kilobytes de texto, então se você possui dados com 1.000 caracteres cada (como endereços) e sua coluna tem mais de 100 endereços únicos, o Analytics arquivará em cache apenas os primeiros 100 valores da consulta de escaneamento.
Os valores em cache são exibidos nos menus suspensos dos filtros. Se os usuários digitarem valores não listados nos primeiros 1.000 registros distintos ou nos 100kB de texto, o Analytics executará uma consulta em seu banco para buscar esses valores em tempo real.
Um escaneamento é mais custoso que uma sincronização, então ele é executado apenas uma vez durante a configuração e novamente uma vez por dia, por padrão. Se você desativar totalmente os escaneamentos, precisará atualizar os dados manualmente executando escaneamentos manuais.
Para reduzir o número de tabelas e campos que o Analytics precisa escanear para se manter atualizado, ele executa o escaneamento somente para campos usados nos últimos quatorze dias.
Veja o tipo de dados que o escaneamento obtém e o motivo:
| O quê | Por quê |
|---|---|
| Valores distintos para campos categóricos | Para fornecer UI de filtro com dropdown em vez de entrada de texto |
| Valores em cache para campos ativos | Melhora a experiência da interface dos filtros |
| Valores avançados de campos (com contexto de filtro) | Valores quando os dados estão restritos (sandboxed) |
Refazer fingerprinting dos dados periodicamente
O fingerprinting periódico aumentará a carga no seu banco de dados.
Por padrão, o Analytics executa consultas de fingerprinting somente quando você conecta o banco de dados pela primeira vez.
Ative essa opção se quiser que o Analytics utilize amostras maiores dos valores das colunas para sugerir melhor as opções na interface:
- Acesse Admin > Bancos de dados > seu banco de dados.
- Clique em Editar detalhes da conexão.
- Expanda Mostrar opções avançadas.
- Ative Refazer fingerprinting das tabelas periodicamente.
Como o fingerprinting de banco de dados funciona
A consulta de fingerprinting analisa as primeiras 10.000 linhas de uma tabela ou view do seu banco:
SELECT
*
FROM
"your_schema"."your_table_or_view"
LIMIT 10000
O Analytics usa os resultados dessa consulta para fornecer sugestões melhores na interface (como auto-binning).
Para evitar sobrecarregar seu banco, o Analytics executa consultas de fingerprinting apenas na primeira vez em que você configura a conexão com o banco de dados.
Por padrão, o Analytics não repete o fingerprinting após o inicial. Para reexecutá-lo, você pode ativar o recurso de refazer fingerprinting periodicamente.
Veja o tipo de dados que o fingerprinting obtém e o motivo:
| O quê | Por quê |
|---|---|
| Contagem de valores distintos | Determina a estratégia de armazenamento em cache dos valores do campo |
| Valores numéricos mínimos/máximos | Agrupamento em visualizações e filtros de intervalo |
| Intervalo de datas (datas mínimas/máximas) | Filtros de data padrão e exibição de linha do tempo |
| Detecção de tipos especiais (URL, email, JSON, dados geográficos como estados dos EUA) | Renderização e filtragem de campos |
| Proporção de valores nulos | Avaliação da qualidade dos dados |
| Valores médios/medianos | Configurações padrão para visualizações |
| Métricas de comprimento de texto | Oculta campos de texto longo na interface |
Leitura adicional
O Analytics não realiza caching ou limitação de taxa durante o processo de sincronização e escaneamento. Se seus dados parecerem faltando ou desatualizados, consulte:
Leia a documentação para outras versões do Analytics.