> ## Documentation Index > Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt > Use this file to discover all available pages before exploring further. # Data Catalog > Data lake on-premise na infraestrutura do cliente. Organizado, governado e descobrível. Base para Memory, Knowledge e Skills. O **Data Catalog** é o repositório de dados armazenado diretamente na infraestrutura cloud do próprio cliente — AWS S3, Google Cloud Storage ou Azure Blob Storage. Ele documenta, classifica e estabelece ownership sobre todos os datasets ingeridos pelos Data Pipelines. ![Camadas do Data Catalog: dados brutos normalizados e agregados no data lake](https://mintcdn.com/strattumai/_Up8bxNlvkhKDeA-/images/illustrations/data-foundation.svg?fit=max\&auto=format\&n=_Up8bxNlvkhKDeA-\&q=85\&s=0400345711d8c31f2d702b1b1baec991) Os dados chegam brutos, são normalizados na camada clean e agregados na camada semantic — todas vivendo no mesmo lake, na cloud do cliente. > [!NOTE] > > Não é apenas um índice de metadados — é um data lake real, projetado para times de 1 a 5 pessoas. Os dados nunca saem do ambiente do cliente: sem vendor lock-in, sem dados em terceiros. *** ## Por que isso importa O diferencial crítico do Data Catalog é que **os dados ficam on-premise na infra cloud do cliente**. Isso é determinante para fintechs, healthtechs e cooperativas de crédito com exigências regulatórias de localização de dados (LGPD, Bacen). Comparado a alternativas como Databricks: * Não exige clusters gerenciados por terceiros * O query engine (DuckDB) roda embutido — sem custo de compute separado * Operável por times de 1–5 pessoas sem especialista em Spark *** ## Conectar um data lake existente ou construir do zero A Strattum se adapta à maturidade de dados da empresa. Há dois pontos de partida: | Cenário | Como funciona | | - | - | | **A empresa já tem data lake** | A Strattum opera sobre o Databricks, Snowflake, BigQuery ou Redshift existente. Sem migração, sem duplicar o dado, sem reescrever pipelines que já rodam. | | **A empresa ainda não tem** | A Strattum entrega o Delta Lake na nuvem do cliente (AWS, Azure, GCP, OCI), com ingestão, transformação e catálogo prontos para alimentar Memory e agentes. | Nos dois casos o dado permanece no ambiente do cliente e o catálogo — descrição, ownership, linhagem e políticas de acesso — é o mesmo. *** ## Estrutura de camadas (Medallion) O Catalog organiza os dados em três camadas lógicas: > **raw/** > > Dados imutáveis, exatamente como chegaram da fonte. Sem transformação. Serve para auditoria e reprocessamento histórico. Nunca é modificado após a carga inicial. > **clean/** > > Dados normalizados, deduplicados e com chaves padronizadas (CPF, CNPJ, email). É o tronco principal que alimenta Memory (grafos), Knowledge (vetores) e as Skills (queries SQL). > **semantic/** > > Data marts pré-agregados via dbt (opcional). Consultas analíticas pré-construídas consumidas pelas Skills — ex: `fct_receita_por_cliente`, `fct_health_score`. Use quando precisar de métricas calculadas com performance. ### Quando usar cada camada | Caso de uso | Camada | | - | - | | Auditoria de dados originais | `raw/` | | Contexto de entidades para Memory | `clean/` | | Indexação de documentos para Knowledge | `clean/` | | Métricas calculadas para Skills | `semantic/` | | Reprocessamento histórico | `raw/` | *** ## Tecnologias de armazenamento e consulta | Componente | Tecnologia | Função | | - | - | - | | **Armazenamento** | S3 / GCS / Azure Blob (do cliente) | Object storage do próprio cliente | | **Formato** | Parquet + Delta Lake | ACID transactions, versionamento e schema evolution | | **Query Engine** | DuckDB (embutido) | SQL analítico ultrarrápido direto nos arquivos — sem clusters | | **Metadados** | PostgreSQL interno | Catálogo de datasets: descrição, owner, linhagem, schema history | O uso do **DuckDB** é o diferencial técnico crítico: performance analítica com zero complexidade de infraestrutura, sem precisar de Spark, Databricks ou qualquer cluster externo. *** ## Navegando pelo Catalog no Console Acesse **Data Catalog** no menu lateral para ver todos os datasets disponíveis: **1. Visão geral dos datasets** A tela inicial lista todos os datasets por categoria (CRM, ERP, Helpdesk, etc.) com status de saúde, timestamp do último sync e owner. **2. Inspecionar um dataset** Clique em qualquer dataset para ver: * Schema completo (colunas, tipos, exemplos de valores) * Linhagem: de qual conector veio e quais transformações foram aplicadas * Histórico de sincronizações * Políticas de acesso configuradas **3. Explorar a camada clean** Clique na aba **Clean** para ver os dados normalizados prontos para consumo. Você pode executar queries SQL diretamente via DuckDB no Console. **4. Verificar linhagem** O gráfico de linhagem mostra o caminho completo do dado: fonte original → pipeline de ingestão → transformação dbt → dataset final. *** ## Carga incremental (aba Carga) Cada tabela do Catalog tem uma aba **Carga**, com o card **Configuração da carga**. Ela vale para tabelas raw, clean e federadas. Escolha os valores e clique em **Salvar**; nada muda antes disso. | Campo | O que define | | - | - | | **Modo** | **Incremental** traz só o que mudou desde o último ciclo. **Full refresh** recarrega a tabela inteira a cada ciclo. | | **Coluna de cursor** | A coluna que diz quando a linha mudou, normalmente `updated_at`. O incremental lê só as linhas com valor maior que o último guardado. | | **Chave primária** | A coluna que identifica a linha. Uma linha alterada substitui a anterior em vez de duplicar. | | **Avança por** | O que move o cursor para frente: o horário da execução ou o maior valor lido. Veja abaixo. | ### As três posições guardadas Um dado passa por três etapas, e cada uma guarda a sua posição: | Etapa | Posição guardada | | - | - | | **Fonte para raw** | O valor da coluna de cursor da fonte (por exemplo `updated_at`), por conector e tabela. | | **Raw para clean** | A clean é reconstruída a cada build. A plataforma dá a cada linha uma versão em `updated_at`: linha sem mudança mantém a data antiga, linha nova ou alterada recebe o horário da build. Se o SQL do modelo já traz o seu próprio `updated_at`, vale o da fonte. | | **Clean ou federada para o grafo** | O Memory Worker lê só as linhas com `updated_at` maior que a marca-d'água daquela fonte. Uma tabela raw usada direto como fonte do grafo é relida por inteiro quando muda, e ignorada quando não muda. | ### Avança por: horário da execução ou maior valor lido | Opção | Como o cursor avança | Quando escolher | | - | - | - | | **Horário da execução** | Para o menor entre o horário da execução (menos uma margem de 10 minutos) e o maior valor lido. | A coluna pode ter datas erradas ou no futuro. Uma linha com data futura é relida a cada ciclo, e uma data errada nunca trava a tabela. | | **Maior valor lido** | Para o maior valor lido. No grafo, menos a margem de 10 minutos, então os últimos 10 minutos abaixo do máximo são relidos. | A coluna é confiável e você quer ler cada linha uma vez só. | O custo da escolha está nas linhas com data futura. No **maior valor lido**, uma linha gravada com data futura por engano empurra o cursor para frente e esconde as linhas gravadas depois com valores menores. No **horário da execução**, essa linha só é relida a cada ciclo. Os padrões mantêm o comportamento de antes: **horário da execução** na leitura do grafo e **maior valor lido** na carga raw. Voltar de **maior valor lido** para **horário da execução** recua a posição e relê, uma vez, as linhas gravadas enquanto o maior valor segurava o cursor. Onde o controle aparece: * Tabelas federadas (leitura do grafo). * Tabelas clean cujo `updated_at` vem da fonte. Quando o `updated_at` é a versão de linha da plataforma, a tabela é sempre incremental e nunca tem data futura, então o controle fica oculto. * Tabelas raw dos conectores de banco de dados: PostgreSQL, MySQL, MongoDB e BigQuery. * Conectores de API seguem o mesmo controle onde a aba Carga o mostra. Conectores com lógica própria de cursor (GitHub, Notion e Google Drive, por exemplo) não mostram a opção. > [!WARNING] > > O `updated_at` precisa ser o horário em que a linha foi gravada. Uma linha inserida depois com uma data de negócio antiga fica invisível para a carga incremental. *** ## Governança e metadados Cada dataset registrado no Catalog é um ativo de dados governado: | Atributo | Descrição | | - | - | | **Nome e descrição** | Nome legível e descrição em linguagem natural | | **Owner** | Email do responsável técnico pelo dataset | | **Linhagem** | Quais conectores originaram o dado e quais transformações foram aplicadas | | **Políticas de acesso** | YAMLs versionados em Git que definem permissões por serviço e papel | | **Monitoramento de qualidade** | Completude, frescor, consistência e unicidade | ### Campos PII e controle de acesso Campos com dados pessoais (CPF, email, telefone) podem ser configurados para serem visíveis apenas para papéis autorizados. Analistas sem permissão veem os valores mascarados automaticamente. *** ## Transformations (dbt) As Transformations permitem criar a camada `semantic/` com data marts pré-calculados. São definidas em SQL via dbt e versionadas no Workspace Git. > [!NOTE] > > Para configurar uma Transformation, é necessário ter pelo menos um conector ativo. Acesse **Data Catalog → Transformations** para criar e gerenciar transformações. Casos de uso típicos: * `fct_health_score` — score de saúde por conta calculado de uso + tickets + NPS * `fct_inadimplencia` — status de inadimplência por tomador * `dim_clientes_clean` — clientes normalizados com chaves padronizadas *** ## Integrações com outros produtos | Produto | Como o Data Catalog se conecta | | - | - | | **Data Pipelines** | Pipelines alimentam o Catalog — cada dataset ingerido é registrado automaticamente com linhagem | | **Memory** | O Memory Worker lê tabelas normalizadas do `clean/` para extrair entidades e construir o grafo | | **Knowledge** | Textos de documentos são parseados e salvos em `clean/`. O Knowledge Worker lê dali para gerar chunks | | **Skills** | Scripts executados por agentes consultam data marts do `semantic/` e tabelas do `clean/` via DuckDB para métricas exatas | | **Evals** | Métricas de qualidade dos datasets (completude, frescor) alimentam a avaliação de contexto | | **Observability** | Monitora saúde dos datasets: fontes desatualizadas, campos faltando, schemas quebrados | *** ## Exemplos de uso > **Fintech — Dados de crédito unificados** > > Uma fintech conecta seu sistema de originação (PostgreSQL), CRM (HubSpot) e plataforma de cobrança via Data Pipelines. O Catalog organiza tudo em `clean/dim_clientes`, `clean/fct_contratos` e `clean/fct_pagamentos`. O Memory Worker lê essas tabelas para montar o perfil unificado do tomador — sem que o analista precise consultar três sistemas diferentes. > **SaaS B2B — Data mart para análise de churn** > > O time de produto cria um data mart `semantic/fct_health_score` via dbt, consolidando dados de uso do produto, tickets e NPS por conta. Uma Skill consulta esse mart via SQL para investigar quais contas estão com score degradado e cruzar com o histórico de interações da Memory. > **Cooperativa de Crédito — Auditoria regulatória** > > Uma cooperativa precisa demonstrar para auditoria que dados de associados são acessados apenas por serviços autorizados. O Catalog registra cada consulta (audit trail), aplica políticas de row-level security e garante que campos PII são filtrados automaticamente para papéis sem permissão. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.