Tipagem correta de colunas no Power BI/Excel com a API de schema do Via Kondado

Use o código M abaixo para que o Power Query respeite os tipos de dados que a Kondado envia, em vez do "chute" automático que ele faz por amostragem.

---

Por que isso é necessário?

O método padrão de conexão Power BI/Excel via Power Query (descrito nos artigos Conexão Power BI Via Kondado e Como Usar PowerQuery no Excel com Via Kondado) carrega o CSV diretamente. Quando isso acontece, o Power Query tenta adivinhar o tipo de cada coluna por amostragem das primeiras linhas.

Esse "chute" pode falhar em alguns casos comuns:

• Colunas com muitos valores vazios — o Power Query não consegue inferir um tipo confiável.
• Colunas que parecem numéricas mas devem ser texto (ex.: códigos com zeros à esquerda, IDs longos, CEPs, números de pedido).
• Colunas com mistura de números e texto na amostra — ele pode definir como número e quebrar quando aparecer texto depois, ou vice-versa.
• Colunas de data/hora detectadas como texto.

A Kondado já conhece o tipo correto de cada coluna, porque essa informação faz parte do nosso modelo de dados. Você pode buscar esse schema diretamente na nossa API e aplicar no Power Query, garantindo que cada coluna entre com o tipo certo.

---

O que você vai precisar

1. Conta ativa na Kondado com pelo menos uma integração rodando.
2. Destino Via Kondado criado na sua conta.
3. Token do seu destino Via Kondado (ver Como obter o token abaixo).
4. Nome da tabela que deseja importar (ver Como obter o nome da tabela).
5. Power BI Desktop ou Excel 2016+ / Microsoft 365 (com Power Query).

---

Passo a passo no Power BI (ou Excel)

O procedimento é idêntico nas duas ferramentas — ambas usam o mesmo motor (Power Query / linguagem M). A única diferença é onde fica o botão para abrir o editor avançado.

1. Abra o Editor Avançado do Power Query

No Power BI Desktop:

1. Clique em Página Inicial → Transformar Dados (abre o Power Query).
2. No Power Query, clique em Página Inicial → Nova Fonte → Consulta em Branco.
3. Com a consulta em branco selecionada, clique em Página Inicial → Editor Avançado.

No Excel:

1. Vá em Dados → Obter Dados → Iniciar Editor do Power Query.
2. No Power Query, clique em Página Inicial → Nova Fonte → Consulta em Branco.
3. Com a consulta em branco selecionada, clique em Página Inicial → Editor Avançado.

2. Cole o código M abaixo

Substitua todo o conteúdo do Editor Avançado pelo código abaixo, depois ajuste as duas variáveis no topo (TableName e Token):

let
    // === Parâmetros — preencha com seus valores ===
    TableName = "COLOQUE_O_NOME_DA_TABELA_AQUI",
    Token     = "COLOQUE_O_TOKEN_DO_VIA_KONDADO_AQUI",

    // === 1. Carrega o CSV de dados ===
    CsvUrl = "https://hub.kondado.io/data/" & TableName & "?decimal_sep=comma&token=" & Token,
    Fonte  = Csv.Document(
        Web.Contents(CsvUrl),
        [Delimiter=",", Encoding=65001, QuoteStyle=QuoteStyle.None]
    ),

    // === 2. Promove a primeira linha como cabeçalho ===
    #"Cabeçalhos Promovidos" = Table.PromoteHeaders(Fonte, [PromoteAllScalars=true]),

    // === 3. Carrega o schema (tipagem oficial da Kondado) ===
    SchemaUrl      = "https://hub.kondado.io/metadata/schemas/" & TableName & "?decimal_sep=comma&token=" & Token,
    SchemaResponse = Json.Document(Web.Contents(SchemaUrl)),

    // === 4. Mapeia tipos da Kondado para tipos M ===
    TypeMapping = (col_type as text) as type =>
        if      col_type = "text"      then type text
        else if col_type = "float"     then type number
        else if col_type = "int"       then Int64.Type
        else if col_type = "boolean"   then type logical
        else if col_type = "date"      then type date
        else if col_type = "time"      then type time
        else if col_type = "timestamp" then type datetime
        else type any,

    // === 5. Gera lista {nome_coluna, tipo} a partir do schema ===
    ColumnTypes = List.Transform(
        SchemaResponse,
        each {Record.Field(_, "col_name"), TypeMapping(Record.Field(_, "col_type"))}
    ),

    // === 6. Aplica os tipos nas colunas ===
    #"Tipo Alterado" = Table.TransformColumnTypes(#"Cabeçalhos Promovidos", ColumnTypes)
in
    #"Tipo Alterado"

Importante sobre o separador decimal: o parâmetro decimal_sep=comma precisa estar igual nas duas URLs (dados e schema). Se você preferir ponto, troque para decimal_sep=dot nos dois lugares.

3. Concluir e carregar

1. Clique em Concluído no Editor Avançado.
2. O Power Query vai pedir autenticação para os dois URLs (data e metadata). Em ambos, escolha Anônimo e clique em Conectar.
3. Renomeie a consulta para o nome da sua tabela (clique com o botão direito sobre a consulta → Renomear).
4. Clique em Página Inicial → Fechar e Aplicar (Power BI) ou Fechar e Carregar (Excel).

Pronto — sua tabela entra com a tipagem correta, sem depender da amostragem.

---

Como obter o Token do Via Kondado

1. Acesse app.kondado.com.br e faça login.
2. No menu lateral, clique em Destinos.
3. Selecione o destino do tipo Via Kondado.
4. O token está disponível na tela de detalhes do destino — copie-o e guarde com segurança.

Atenção: o token dá acesso aos seus dados. Não compartilhe publicamente, não suba em repositórios Git e troque imediatamente caso suspeite de vazamento. Para mais detalhes sobre o destino, veja Via Kondado.

Como obter o nome da tabela

1. Em app.kondado.com.br, vá em Integrações.
2. Selecione a integração desejada.
3. Clique no botão Visualizar Dados.
4. Na janela, escolha o separador decimal e localize a tabela que você quer importar.
5. Você pode copiar o link completo (já contém token e nome da tabela) ou apenas anotar o nome da tabela. O nome aparece no final da URL: https://hub.kondado.io/data/nome_da_tabela?token=....

---

Como o mapeamento de tipos funciona

A API /metadata/schemas/{tabela} retorna um array JSON com a estrutura abaixo:

[
  {"col_name": "id",          "col_type": "int"},
  {"col_name": "created_at",  "col_type": "timestamp"},
  {"col_name": "total_value", "col_type": "float"},
  {"col_name": "is_active",   "col_type": "boolean"},
  {"col_name": "description", "col_type": "text"}
]

O código M acima converte esses tipos da Kondado para os tipos nativos do Power Query:

Tipo Kondado	Tipo Power Query (M)	Observação
text	type text	Texto / string
int	Int64.Type	Inteiro de 64 bits
float	type number	Número decimal
boolean	type logical	Verdadeiro/Falso
date	type date	Apenas data
time	type time	Apenas hora
timestamp	type datetime	Data e hora
(qualquer outro)	type any	Mantém o que o Power Query inferir

---

Dúvidas comuns

O Power Query mostra erro de autenticação

Vá em Arquivo → Opções e configurações → Configurações da fonte de dados, encontre as URLs hub.kondado.io, clique em Editar Permissões e selecione Anônimo. As URLs de /data/ e /metadata/schemas/ precisam de credencial separada.

Atualização agendada no Power BI Online não funciona

Geralmente é o erro de "níveis de privacidade". Veja a seção "Agendamento de Atualização Automática no Power BI Online" no artigo Conexão Power BI Via Kondado.

Posso parametrizar o Token e o TableName?

Sim — é a abordagem recomendada para reuso. Crie parâmetros do Power Query (Página Inicial → Gerenciar Parâmetros → Novo Parâmetro) chamados TableName e Token, e remova as duas linhas de declaração do topo do código M. Assim você usa o mesmo template para várias tabelas só trocando os parâmetros.

Funciona com qualquer tabela?

Sim — o endpoint /metadata/schemas/{tabela} existe para toda tabela acessível pelo Via Kondado. Inclui tabelas de integrações nativas e tabelas geradas pelos seus modelos KSQL.

E se eu adicionar uma coluna nova depois?

Basta atualizar a consulta no Power Query (Página Inicial → Atualizar Visualização). Como o schema é buscado dinamicamente, novas colunas entram automaticamente com o tipo correto.

---

Próximos passos

• Via Kondado — visão geral
• Conexão Power BI Via Kondado (método simples, sem tipagem)
• Como Usar PowerQuery no Excel com Via Kondado
• Via Kondado: Referência KSQL