Manual do Usuário

1\ antes de começar entrar o acesso é pelo keycloak — não há login próprio da plataforma ao abrir o endereço, você é levado à tela de autenticação da empresa e volta autenticado o espaço de trabalho (tenant) vem do seu usuário cada espaço tem os próprios dados, conexões e painéis o que você vê é o do seu espaço, sempre a barra superior elemento para que serve idioma português, english, español, français muda a interface na hora 🌙 / ☀️ alterna entre tema claro e escuro 🔔 sino alertas e insights do pulse (ver automação https //docs citsmart com/tdbt manual do usuario#12 automao ) seu nome identifica a sessão sair encerra a sessão o menu lateral quatro grupos análise & preparação — explorar, datasets, fluxos de dados, modelagem, sql lab, galeria visualização — páginas/dashs/apps, relatórios, portal análise dados, portal de relatórios automação & ia — automação, conhecimento, conectores llm administração — conexões, histórico, perfis de acesso, configurações o menu pode ser recolhido para ganhar espaço horizontal o que aparece nele depende dos seus perfis — ver perfis de acesso https //docs citsmart com/tdbt manual do usuario#perfis de acesso o caminho mais curto para o primeiro gráfico explorar → enviar arquivo e escolha um csv, excel, json ou parquet arraste um campo para dimensões e outro para medidas escolha o tipo de apresentação salvar no dashboard 2\ conceitos da plataforma vale ler esta seção uma vez quase toda dúvida de uso nasce de confundir dois destes conceitos conceito o que é conexão o acesso a uma origem banco, api rest, arquivo guarda endereço e credencial dataset uma tabela consultável na plataforma, com campos classificados em dimensões e medidas é a matéria prima de toda análise consulta salva uma análise montada no explorar e guardada com nome pode ser reaproveitada em painéis e páginas dashboard uma grade de widgets com filtros globais página uma composição livre de blocos — inclui texto, botões, vídeo e conteúdo incorporado, além de gráficos aplicação um conjunto de páginas e dashboards navegáveis como um produto só, com ícone, cor e tela inicial relatório um documento em seções, feito para ser exportado em pdf, excel, word ou powerpoint fluxo de dados uma sequência de passos que transforma uma ou mais origens e gera um dataset novo modelo tabelas de uma conexão ligadas por relacionamentos, que geram um dataset sem escrever sql documento de conhecimento regra de negócio, glossário ou definição em markdown, consultado pela ia e exibível nos widgets dashboard, página ou relatório? dashboard quando o objetivo é acompanhar números lado a lado, filtros no topo, atualização periódica página quando o objetivo é conduzir texto explicativo entre os gráficos, parâmetros, botões de ação relatório quando o objetivo é entregar o material vai virar arquivo e circular por e mail 3\ explorar — o construtor de análises é a tela onde as análises nascem painel de fontes (esquerda) enviar arquivo — csv, excel, json ou parquet viram dataset na hora conectar fonte de dados — banco ou api rest (ver conexões https //docs citsmart com/tdbt manual do usuario#14 conexes ) nova planilha (digitar dados) — cria um dataset digitando os dados à mão, útil para metas, orçamentos e tabelas de apoio datasets e consultas salvas — o que já existe, com busca painel de campos os campos do dataset, separados em dimensões (o que agrupa), medidas (o que se soma) e métricas (cálculos nomeados, reutilizáveis) o botão f+ cria um campo calculado ; o σ ao lado de uma métrica indica um cálculo salvo no dataset montando a análise tipo de apresentação — 36 formatos (ver referência https //docs citsmart com/tdbt manual do usuario#16 referncia rpida ) dimensões — arraste os campos que agrupam medidas — arraste os campos numéricos; escolha a agregação (sum, avg, min, max, count, count distinct, mediana, p90, p95, desvio padrão, variância) filtros — arraste campos para restringir segmentos — salve o conjunto de filtros atual com um nome e reaplique depois em um clique os três popovers de ajuste formatação — paleta, título, títulos dos eixos, formato dos números, rótulos, empilhamento, orientação, legenda, opções da tabela dinâmica interação — o que acontece ao clicar detalhar, filtrar o painel, abrir uma url, abrir outro dashboard, ou nada análise — linha de tendência, linha de média, linha de referência (meta), previsão, agrupamento (k means) a barra de ações botão o que faz salvar grava a consulta se já estava aberta uma, atualiza; a mensagem confirma qual das duas coisas aconteceu salvar como… cria uma consulta nova a partir da atual csv baixa o resultado prever projeta os próximos períodos de uma série insights resumo executivo e anomalias detectadas permite assinar a métrica no pulse consulta mostra o sql gerado — útil para conferir ou levar a outra ferramenta form condicional regras que colorem as células (ver abaixo) indicadores colunas de sinalizadores (ver abaixo) salvar no dashboard envia a análise para um painel modo foco esconde a configuração e amplia o gráfico formatação condicional disponível em tabela e dinâmica três tipos de regra escala de cor — o valor pinta a célula em um degradê barra de dados — uma barra proporcional dentro da célula limiar — pinta quando o valor passa de um limite (>, ≥, <, ≤, =) o campo regra por texto aceita linguagem natural (“destaque em vermelho vendas abaixo de 1000”) e a ia monta a regra o painel pode ser redimensionado pelo canto , e o tamanho fica guardado colunas de indicador também em tabela e dinâmica é a ideia dos conjuntos de ícones do excel o valor cai numa faixa e a faixa define um símbolo seis conjuntos prontos — semáforo, setas, sinais, bandeiras, bolinhas, estrelas — e o campo do símbolo aceita qualquer emoji ou texto curto colado ao criar, os limites já vêm sugeridos a partir dos terços do intervalo real da coluna, arredondados ajuste os à sua régua as faixas valem de cima para baixo a primeira que casar define o símbolo cada indicador escolhe onde aparece em coluna própria — uma coluna nova à direita na dinâmica, ela avalia o total da linha o sinal fala da linha inteira dentro da célula do valor — o símbolo entra na célula, como no excel na dinâmica é a única forma de sinalizar célula a célula para ter os dois, crie dois indicadores sobre a mesma medida tabela dinâmica a barra própria da dinâmica oferece expandir tudo / recolher tudo e o seletor de níveis escalonado (hierarquia recuada numa coluna) ou colunas (uma coluna por dimensão) trocar eixos — leva as dimensões de linha para as colunas e vice versa subtotais e col total heatmap — colore as células por escala csv arraste a divisa entre as colunas para redimensioná las detalhar um ponto duplo clique em uma barra, fatia ou célula abre a janela de detalhe com as linhas por trás daquele número datas e valores saem formatados conforme a configuração do sistema os cabeçalhos usam o rótulo do cadastro do dataset (o nome técnico fica na dica da coluna) copiar leva a tabela para a área de transferência separada por tab — colando no excel, cai direto nas células análise de ia um dos tipos de apresentação em vez de um gráfico, a plataforma escreve a leitura dos dados em texto o campo pergunta direciona a análise (“compare com o mês anterior e aponte o que explica a queda”) exige um conector llm configurado 4\ datasets a tela lista os datasets do espaço ao editar um, há seis abas identidade nome, descrição e a marca fonte certificada (confiável) , que sinaliza aos demais usuários que aquele dataset é oficial mostra também a origem — e avisa quando a conexão de origem não existe mais o dataset continua consultável com o que já foi materializado, mas não consegue se atualizar campos cada campo tem rótulo — o nome que aparece nas telas é o que resolve sum valor da venda virar “valor da venda” em filtros, parâmetros e no detalhe papel — dimensão ou medida tipo — o tipo do dado edite quantos quiser e use salvar campos para gravar todos de uma vez; o contador mostra quantos estão com alteração pendente \+ campo calculado cria uma coluna por expressão sql, por exemplo (receita custo) / nullif(receita, 0) acesso os perfis (roles) que podem ver e usar o dataset no explorar vazio = visível a todos administradores sempre veem sincronização define com que frequência os dados são trazidos da origem — vale para todas as consultas e painéis que usam o dataset intervalo (minutos, horas, dias) ou expressão cron de cinco campos, com conferência dos próximos disparos como atualizar completa — recarrega a origem inteira sempre fiel, mais cara incremental — traz só o que mudou desde a última vez exige uma coluna de avanço (crescente data de atualização ou id sequencial) e as colunas que identificam a linha atenção com a carga incremental ela não enxerga linhas excluídas na origem configure a recarga periódica de reconciliação — é o que impede a diferença de se acumular, e o melhor uso da expressão cron, para cair fora do horário de pico dados edita as células diretamente (até 500 linhas de amostra) é como se mantém uma planilha de metas ou uma tabela de apoio criada na plataforma sql para datasets vindos de consulta permite trocar o sql que os alimenta 5\ fluxos de dados um fluxo transforma dados e gera um dataset é a alternativa ao sql para quem prefere montar a transformação passo a passo — e ao mesmo tempo comporta sql e javascript onde eles forem necessários estrutura origens — os datasets de entrada, cada um com um apelido usado nos passos variáveis — valores reaproveitáveis, escritos como $ dentro dos passos há 15 embutidas (data e hora atuais, última execução, usuário, espaço) passos — a sequência de transformações resultado final — o passo que vira dataset prévia cada passo mostra o resultado daquele ponto , com contagem de colunas e linhas de amostra é assim que se confere a transformação sem executar o fluxo inteiro a prévia não chama serviços externos passos de ia e de api aparecem com as colunas vazias use o testar do próprio passo e depois executar passos disponíveis preparar — filtrar linhas · colunas · coluna calculada · converter tipo · ordenar · limitar linhas · remover duplicatas · substituir texto · dividir coluna combinar — juntar (left, inner, full, anti, semi) · empilhar · juntar por semelhança (jaro winkler ou levenshtein) remodelar — agrupar e resumir · colunas viram linhas · linhas viram colunas análise avançada — detectar anomalias (z score ou iqr, comparando dentro de cada grupo) · faixas de valor (quantis ou intervalos iguais) · normalizar escala · correlação · agrupar semelhantes (k means) · prever série · preencher faltantes código e ia — sql · código (javascript) · definir variável · perguntar à ia · buscar de api passo sql o passo anterior chega como entrada e as origens pelo apelido é uma consulta só , sem ponto e vírgula use ${variável} onde entra uma data de corte ou um parâmetro passo código (javascript) recebe a linha (ou todas as linhas, no modo tabela) e a lista de variáveis o painel lateral mostra como a linha chega , com a amostra real e os cuidados — principalmente com valores nulos, que derrubam o passo se usados sem verificação passo perguntar à ia classifica, extrai ou resume o conteúdo de cada linha com um modelo de linguagem traz exemplos prontos (classificar, extrair, resumir, sentimento) custo cada pergunta distinta é uma chamada paga linhas que geram a mesma pergunta são perguntadas uma vez só — classificar mil linhas em dez categorias custa dez chamadas há uma trava de máximo de linhas passo buscar de api três modos enriquecer cada linha (uma chamada por valor distinto), empilhar o resultado ou juntar por chave também tem trava de linhas e um testar em 5 linhas agendamento depois da primeira execução bem sucedida, o fluxo pode rodar sozinho na frequência escolhida 6\ modelagem conecta tabelas de uma fonte, sugere os relacionamentos e gera datasets sem escrever sql escolha a conexão à esquerda e clique nas tabelas para adicioná las as relações prováveis aparecem sozinhas — confirme, ajuste o tipo de junção ou remova defina a tabela base ver sql para conferir o que foi montado; gerar dataset para materializar cada relacionamento tem a opção prevenir fan out , que evita que uma junção de um para muitos infle as medidas o modelo pode ser ao vivo (consulta a fonte a cada uso, com pushdown) ou materializado (copia para o motor analítico) 7\ sql lab para quem escreve sql schema — as tabelas disponíveis; clique para ver as colunas join é permitido salvas — suas consultas sql guardadas gerar sql por linguagem natural — descreva a consulta e revise o que a ia escreveu antes de executar data manager — selecione dois ou mais datasets e a plataforma sugere associações prováveis , analisando nomes de colunas, tipos e sobreposição real de chaves, com percentual de confiança gera o sql do modelo unir (append) — empilha datasets alinhando colunas por nome materializar como dataset ou criar gráfico a partir do resultado histórico de execuções, para reaproveitar um sql já rodado 8\ galeria de modelos modelos prontos de dashboards, relatórios e apps, filtráveis por setor escolha o modelo, aponte o dataset e a plataforma monta a estrutura — os campos do modelo são mapeados automaticamente para as colunas escolhidas você também pode transformar seus próprios dashboards e relatórios em modelos, pelo botão modelo dentro deles 9\ páginas, dashboards e aplicações uma tela só reúne os três, porque eles se compõem dashboards uma grade de widgets cada widget tem cabeçalho com as ações ↑ ↓ ordenam inteira / ½ / ⅓ definem a largura ✎ abre o construtor 📖 vincula conhecimento (ver abaixo) ✕ remove arraste a alça do canto inferior direito para mudar a altura barra superior recurso o que faz auto refresh reconsulta em intervalo fixo ao vivo reconsulta quando um dataset usado muda tema e tela cheia só para exibição 🔒 trava o layout contra arrasto acidental + seção / + card / + consulta salva acrescenta conteúdo pdf exporta o painel ⭐ 🔗 \</> 🗑 favoritar, link público, incorporação, excluir comentários discussão anexada ao painel filtros aceitam três tipos de campo — valor (multisseleção), numérico (intervalo) e data (intervalo) — e oferecem escopo por widget — a quais widgets cada filtro se aplica cascata — as opções de um filtro refletem os demais filtros ativos clicar num ponto do gráfico aplica cross filter ao painel, conforme a configuração de interação da análise retratos (versões) guardam o estado do painel — capturados diariamente e a cada clique — e permitem comparar dois retratos indicador a indicador páginas composição livre, em fluxo vertical ou grade tipos de bloco bloco para que serve texto markdown títulos, listas, ênfase gráfico / tabela / métrica dados, montados ali ou vindos de uma consulta salva parâmetro um seletor que filtra os demais blocos da mesma fonte de dados aceita multisseleção ação botão navegar, definir parâmetro, disparar evento, abrir relatório, gravar dado, abrir link html / vídeo / incorporar conteúdo próprio, youtube ou iframe externo aplicações reúnem páginas e dashboards existentes como telas de um produto só, com nome, descrição, ícone, cor e tela inicial dois modos estrutura — editar telas, identidade e acesso executar — navegar como o usuário final conhecimento no widget o ícone 📖 no cabeçalho aparece quando há orientação vinculada — e só quando há duas formas, que servem a coisas diferentes nota do widget — o que vale só ali “este total exclui devoluções” documentos da base — o que vale em muitos lugares a definição de “cliente ativo”, a regra de rateio escritos uma vez, corrigidos uma vez, e a correção chega a todo widget que aponta para eles nas telas públicas aparece apenas a nota os documentos da base exigem sessão, e publicá los junto com o link exporia material interno consultas salvas vinculadas ao arrastar uma consulta salva para um painel ou página, fica registrado de qual consulta ela veio — o ícone de elo no cabeçalho indica isso a configuração é lida da origem a cada abertura, inclusive no pdf e nas telas públicas editar o widget no construtor desfaz o vínculo (com aviso) a partir dali as mudanças valem só naquele painel se a consulta for apagada , o widget continua funcionando com a última configuração conhecida compartilhamento acesso por perfil — quais roles podem abrir link público — endereço que dispensa login pode ser revogado incorporação — código para embutir em outro sistema, com filtros travados no servidor 10\ relatórios documentos em seções, feitos para virar arquivo seções tipo conteúdo texto markdown, com marcadores de data e nome do relatório tabela listagem simples (com escolha e rótulo das colunas, e subtotais por campo) ou agregação gráfico barras, linhas, área ou pizza parâmetro um seletor que filtra as demais seções da mesma fonte de dados cada seção tem título, formato dos números, limite de linhas e largura (inteira ou metade — duas meias formam uma linha) gráfico legenda mostrar legenda liga e desliga; texto da legenda troca o nome da série o campo mostra como placeholder o nome atual (sum vendas), e apagá lo volta ao original na pizza a legenda lista as fatias, e o texto vem dos próprios dados — por isso o campo não aparece ali parâmetros mesmo desenho do bloco de parâmetro das páginas fonte de dados, campo, rótulo e multisseleção o recorte é por fonte de dados — um parâmetro de uf não filtra seção que lê outra tabela os parâmetros valem também nos arquivos exportados , e cada formato registra o recorte aplicado parágrafo no pdf, resumo no excel, cabeçalho no word, capa no powerpoint um arquivo filtrado que não diz por qual valor engana quem o receber adiante exportação pdf , excel , word e powerpoint o pdf desenha os gráficos com a mesma paleta da tela modelo transforma o relatório num modelo reaproveitável na galeria 11\ portais duas telas de consumo, para quem usa e não constrói portal análise dados — tudo que você tem permissão de executar dashboards, páginas e aplicações, em cards ou listagem, com busca portal de relatórios — os relatórios que você pode ver, já com os botões de exportação 12\ automação cinco recursos, na mesma tela envio agendado de relatórios escolha o relatório, os destinatários, o formato do anexo e a frequência — intervalo ou expressão cron de seis campos (ex 0 0 8 mon fri = dias úteis às 8h), com fuso horário enviar agora testa na hora alertas por condição de dado vigiam uma consulta salva e disparam quando o valor passa de um limiar (maior que, menor que, igual a) ou quando foge do padrão ( anomalia por desvio σ ) canais e mail , in app (sino) e webhook testar mostra o valor atual e se dispararia agora entrega de dados agendada exporta o resultado de uma consulta salva — com seus filtros — em csv ou xlsx e envia por e mail no intervalo ou cron definido gatilhos por evento de negócio disparam e mail ou relatório quando o sistema de origem chama o webhook — por exemplo, um pedido confirmado copie a url gerada e configure no sistema transacional nos textos de assunto e corpo, use e os campos do payload como pulse — insights proativos assine uma métrica pelo botão assinar no pulse , dentro do modal insights do explorar o pulse verifica periodicamente e avisa no sino (e por e mail) quando surge uma anomalia ou tendência — sem você precisar procurar sem smtp configurado, os envios ficam em dry run são registrados no log do servidor, mas não saem ver configurações https //docs citsmart com/tdbt manual do usuario#configuraes 13\ conhecimento e ia conhecimento a base que a ia consulta ao responder — e de onde saem as orientações exibidas nos widgets organize pastas e documentos markdown crie na tela ou faça upload de md, txt, csv, json, docx cada documento pode ser vinculado a datasets sem marcar nenhum, vale como conhecimento geral; marcando, o assistente usa aquele documento apenas nas conversas sobre os datasets escolhidos conectores llm os modelos de linguagem que a plataforma usa provedores suportados provedor observação anthropic chave em console anthropic com openai chave em platform openai com google gemini chave no google ai studio ollama (local) roda na sua infraestrutura; não precisa de chave vllm (servidor próprio) servidor compatível com a api da openai um conector precisa estar ativo e marcado como padrão — sem isso, os recursos de ia não têm a quem perguntar testar confirma que o modelo responde ollama e vllm rodam na sua infraestrutura e não mandam dado nenhum para fora o assistente (botão ia) presente no canto inferior direito permite conversar com os dados em linguagem natural, com perguntas de acompanhamento; a ia responde em texto e monta o gráfico gerar insights automáticos sobre um dataset gerar um painel ou página inteiros a partir de uma descrição (“vendas por região e evolução mensal”), com a opção de salvar ou descartar falar em vez de digitar, nos navegadores com reconhecimento de voz 14\ conexões tipos suportados banco de dados , agrupados por família relacional (sql) — postgresql, mysql, sql server, sqlite (arquivo) e afins data warehouse (nuvem) query engine / olap — inclui opensearch, cujos índices aparecem como tabelas big data (hadoop) object storage — parquet/csv por uri, com região e endpoint minio opcional nosql api rest , com autenticação nenhuma , basic , token/jwt (bearer) ou cabeçalho personalizado (api key) , cabeçalhos extras e caminho json para quando os registros vêm dentro de um envelope (resultado itens) testar api confere antes de salvar importar ao conectar, a plataforma lista as tabelas (ou índices) selecione as que interessam cada uma vira um dataset com o nome da tabela a tela conexões (administração) manutenção do que já existe renomear, trocar parâmetros, testar , excluir e definir quais perfis podem mexer em cada conexão aqui, nenhum perfil marcado = só administrador — o oposto dos datasets, onde lista vazia libera a diferença é proposital nos datasets se lê dado; aqui se altera a credencial de um banco excluir uma conexão em uso avisa quantos datasets deixarão de se atualizar 15\ administração histórico registro de acessos aos componentes de bi quando, quem, tipo e componente perfis de acesso define quais funcionalidades cada perfil (role) pode acessar — é o que decide o menu de cada usuário regras que valem a pena conhecer administradores sempre acessam tudo um usuário sem nenhuma funcionalidade concedida enxerga o sistema sem restrição de menu é proposital evita travar o acesso de todos por um cadastro incompleto segurança em nível de linha (rls) fica na mesma área dê atributos ao usuário (regiao=sul) crie a regra por dataset linhas onde o campo regiao = o atributo regiao do usuário a partir daí, cada pessoa vê apenas as linhas que lhe cabem, em qualquer tela configurações formato de data e moeda — data, hora, moeda, separadores e casas decimais, com prévia vale para explorar, relatórios, dashboards e páginas “segue o idioma” usa a convenção do idioma escolhido na barra superior prefira um formato fixo quando o material precisa sair igual para todo mundo e mail (smtp) — remetente, host, porta, usuário e senha sem habilitar envio real , tudo fica em dry run backup e portabilidade — exporta todos os elementos criados (dashboards, consultas, relatórios, automação, configurações) num único json, e importa um pacote para restaurar ou migrar os dados brutos das fontes não são incluídos — apenas as definições a inclusão de segredos (senhas e chaves) é opcional e explícita 16\ referência rápida tipos de apresentação comparação — barras · linhas · área · combinado · cascata · tornado · bullet · marimekko composição — pizza · rosca · treemap · sunburst · funil · stream graph relação — dispersão · bolhas · correlação em matriz (heatmap) · radar · coordenadas paralelas · sankey · grafo · árvore distribuição — histograma · boxplot evolução no tempo — calendário · gantt · candlestick · pulse número único — kpi · tendência · medidor (gauge) tabelas — tabela · tabela dinâmica geográfico — mapa (país, uf, cidade, bairro) texto — nuvem de palavras narrativa — análise de ia agregações sum · avg · min · max · count · count distinct · median · p90 · p95 · stddev · variance formatos de número formato exemplo número 1 234,56 milhares 1 235 moeda r$ 1 234,56 percentual 1 234,6% o símbolo da moeda e os separadores vêm das configurações do espaço 17\ perguntas frequentes alterei uma consulta salva e o painel não mudou painéis criados antes da versão que introduziu o vínculo guardam uma cópia solta adicione a consulta ao painel novamente a partir daí ele acompanha a origem um campo aparece com nome técnico (sum vendas) nos filtros preencha o rótulo do campo em datasets → campos ele vale para filtros, parâmetros, cabeçalhos e para a janela de detalhe o e mail não chega confira em configurações → e mail se habilitar envio real está ligado sem isso, os envios ficam em dry run e só aparecem no log do servidor os recursos de ia estão indisponíveis é preciso um conector em conectores llm que esteja ativo e marcado como padrão a carga incremental está deixando linhas para trás a carga incremental não enxerga exclusões na origem configure a recarga periódica de reconciliação na aba sincronização do dataset o dataset parou de se atualizar veja a aba identidade se a conexão de origem foi excluída, o dataset continua consultável com o que já foi materializado, mas não se atualiza mais não consigo ver um menu que meu colega vê o menu depende dos perfis peça a um administrador para conferir em perfis de acesso preciso que os números saiam iguais para todo mundo, em qualquer idioma em configurações → formato , escolha um formato fixo em vez de “segue o idioma” este manual descreve a plataforma como ela está recursos e telas evoluem — em caso de divergência, a tela é a referência