O destino Via Kondado permite acesso via Link aos dados integrados e modelados pela Kondado

1. Acessando seus dados
   1. Link copia e cola
      1. Link copia e cola de integrações
      2. Link copia e cola de modelos
   1. Montando o link manualmente
      1. Token de acesso
      2. Leitura de dados
      3. Leitura de metadados
   1. Formato dos dados retornados
2. Como usar
   1. Unidades
      1. Alteração de unidades
      2. Unidade gratuita
   1. Alterar token de acesso
   2. Criar
   3. Desativar e arquivar
      1. Remover dados sem desativar o destino
   4. Recomendações de segurança
   5. Padrão de tabelas
   6. Modelos
      1. Editor de modelos
   7. Consultas
   8. MCP
   9. Conexão PostgreSQL (Beta)
      1. Limite de linhas e paginação
   10. Dúvidas comuns do Via Kondado

Acessando seus dados

Link copia e cola

A conexão com o Via Kondado é realizada via API. Você poderá obter facilmente o link de acesso API para qualquer tabela, de maneira similar ao modal abaixo. Você poderá alterar o separador de decimal entre vírgula e ponto e então clicar no ícone de copiar para obter o link

Link copia e cola de integrações

Para obter todos os links das tabelas de sua integração, basta acessar sua integração e clicar no ícone de compartilhar

O link de cada tabela estará também disponível ao clicar em DETALHES

Link copia e cola de modelos

Montando o link manualmente

A nossa API de leitura deve ser acessada com uma requisição GET no host https://hub.kondado.io e autenticada com o parâmetro token (query string)

Token de acesso

Para obter o token de acesso ao seu destino, basta acessá-lo, clicar nas 3 barras horizontais e então "Ver token"

Este token permite acesso aos seus dados. Mantenha-o em um lugar seguro

Leitura de dados

Para obter os dados de uma tabela tabela_x, basta acessar o path data/tabela_x.

Caso o parâmetro decimal_sep não seja informado, o separador de decimal será o ponto, utilize decimal_sep=comma para obter seus dados separados por vírgula, por exemplo:

https://hub.kondado.io/data/tabela_x?token=seu_token&decimal_sep=comma

Leitura de metadados

O path /metadata retorna metadados de suas tabelas no formato JSON

• /metadata/show_tables retorna um ARRAY de JSONs com a lista das tabelas em seu destino na chave tbl_name
• /metadata/kdd_show_tables retorna um ARRAY de JSONs com a lista das tabelas em seu destino, incluindo informações de localização desta tabela dentro da Kondado:
  • tbl_name informa o nome da tabela
  • tbl_id informa o id da tabela
  • origin_object_type informa o tipo de objeto que a tabela referencia.
    • pipeline significa integração
    • kubo significa modelo
  • origin_object_id informa o id deste objeto
  • origin_object_sub_location informa a localização da tabela dentro do objeto, para integrações que possuem mais de uma tabela. Retorna vazio caso seja a tabela principal da integração ou uma tabela de um modelo
  • origin_object_created_rev código interno que indica a versão do objeto que referencia a tabela
  • createdAt data de criação da tabela
  • updatedAt data de última atualização da tabela
• /metadata/kdd_show_table_sizes retorna um ARRAY de JSONs com a lista das tabelas em seu destino e informações sobre os tamanhos destas tabelas:
  • tbl_name informa o nome da tabela
  • tbl_id informa o id da tabela
  • num_rows número de linhas da tabela
  • num_cols número de colunas da tabela
  • num_cells número de células da tabela
  • size_bytes tamanho da tabela em bytes
  • billable_mb_size tamanho da tabela em megabytes a fim de contagem de acessos
  • billable_requests quantos acessos a tabela irá consumir ao ser lida
• /metadata/schemas/tabela_x retorna o schema da tabela tabela_x
  • col_type informa o nome do campo (chave/header)
  • col_type representa o tipo do campo: text, float, int, timestamp, date ou boolean

Formato dos dados retornados

Sempre que o link de dados (/data) for acessado, será retornada a versão mais recente de sua tabela no Via Kondado no formato CSV, o que permite compatibilidade com várias ferramentas de visualização e análise.

O separador de colunas deste arquivo será a vírgula e você poderá alternar entre vírgula ou ponto como separador de decimais com o parâmetro decimal_sep caso crie o link manualmente ou diretamente no modal de obtenção do link de nossa plataforma.

Para aumentar a compatibilidade e formatação do CSV, quebras de linha (/n, /r e /r/n) em campos do tipo text serão removidos nas tabelas de integrações. Nas tabelas de modelos, esta remoção apenas ocorrerá devido a alterações realizadas pelo SQL do modelo.

Além disso, boa parte dos acentos e caracteres especiais serão substituídos.

Como usar

Unidades

Cada destino Via Kondado pode ser configurado para ter uma certa capacidade, de acordo com a quantidade de unidades alocadas. Uma unidade possui 3 componentes:

• Acessos
  • Cada unidade concede 2 mil acessos/mês
  • É uma medida de acesso aos dados e indica quantas leituras por mês a cada 10 mb (megabytes) podem ser realizadas via links de dados e metadados do destino.
  • Por exemplo, uma tabela de 5mb consome 1 acesso ao ser lida. Uma tabela de 18mb consome 2 acessos
• Células:
  • Cada unidade concede 10 milhões de células armazenadas por mês
  • É uma medida de armazenamento de dados. Indica quantas células por mês podem ser armazenadas no destino. De forma similar a uma planilha, uma célula é a menor unidade de uma tabela e representa a intersecção de uma linha e uma coluna. Dentro de um dado mês, a quantidade de células pode ser variável, já que uma tabela pode aumentar/diminuir de tamanho, bem como ser removida ou criada a qualquer momento e a contabilização de células por mês reflete esta variação
• Modelos ativos
  • Cada unidade concede 2 modelos ativos

Alteração de unidades

É possível alterar o número de unidades diretamente na página do destino

O modal que será aberto indicará a precificação mensal total. Podem ser concedidas unidades gratuitas, a nosso critério. Basta clicar em SALVAR para aplicar a nova configuração

Unidade gratuita

A unidade gratuita inclusa no plano do cliente é concedida no momento de criação ou edição das unidades do destino

Alterar token de acesso

Para alterar o token de acesso de seu destino, basta acessá-lo, clicar nas 3 barras horizontais e então “Alterar token”

Você deve alterar seu token sempre que suspeitar que ele foi comprometido. Aterações frequentes também são recomendadas. Ao alterar seu token, será gerado um novo e o anterior deixará de funcionar, sendo preciso atualizar o novo token em seus links

Criar

Após seu período de teste grátis, você pode ter quantas instâncias de Via Kondado quiser, cada um conterá seus próprios dados e terá seu próprio token de acesso. Para criar um novo destino, basta clicar em "+ Criar" no menu lateral, escolher Via Kondado, dar um nome e um número de unidades ao novo destino

Desativar e arquivar

Para desativar e arquivar seu destino, basta acessá-lo, clicar nas 3 barras horizontais e então “Desabilitar e arquivar”. Esta ação é irreversível, removerá os dados das tabelas deste destino e o tornará inacessível via Link. Integrações e modelos deste destino serão arquivados

Remover dados sem desativar o destino

Você pode arquivar uma integração ou modelo para remover estes dados específicos de seu destino Via Kondado

Recomendações de segurança

Seu token permite acesso aos seus dados, utilize o mais alto grau de segurança em sua manipulação

É possível obter este token de várias maneiras pela plataforma da Kondado, por isso recomendamos proteger o acesso à sua conta da Kondado aplicando configurações de login adequadas, permitindo acesso somente com métodos que possuam autenticação de 2 fatores habilitados e domínios restritos.

Padrão de tabelas

Nomes de tabelas

• Não começar com duckdb_, pragma_, pg_ ou sqlite_
• Não conter caracteres especiais ou espaço
• Utilizar sempre caixa baixa

Campos

• O número máximo de campos por tabela é 1500
• Os anos minimos e maximos para os campos dos tipos date e timestamp são, respectivamente, 1677 e 2262. Caso uma data não esteja dentro deste intervalo será retornada como vazia.

Modelos

É possível utilizar nossa funcionalidade de modelos no destino Via Kondado, que utiliza a sintaxe DuckDB, com as seguintes particularidades:

1. Seu SQL deve conter apenas um comando do tipo SELECT
2. O comando SHOW não é permitido em seu SQL
3. Alias de colunas serão normalizados na tabela final, substituindo caracteres não ANSI e espaços por "_"
4. Não deve ser utilizada a notação de ponto "." para se referir a tabelas em seu SQL
5. Não é permitida a função RANGE
6. PIVOT e UNPIVOT devem ser embalados dentro de uma subquery (por exemplo: SELECT * FROM (PIVOT Cities ON YEAR USING SUM(POPULATION)) e SELECT * FROM monthly_sales UNPIVOT (sales FOR month IN (jan, feb, mar, apr, may, jun)))
7. O tempo total de execução de fato de seu modelo, incluindo carregamento das tabelas dependentes não deverá exceder 10 minutos, sendo no máximo 5 minutos para execução do SQL em si. Caso estes limites sejam excedidos, pode ser necessário consultar menos tabelas, trabalhar com tabelas diminuídas (por exemplo, com o tratamento antecipado utilizando outros modelos a montante) ou simplificar seu SQL
8. Devido à arquitetura do destino Via Kondado, poderá haver variação considerável entre os tempos de cada execução de um mesmo modelo

Veja mais sobre modelos:

Editor de modelos

O editor de modelos do Via Kondado permite que você teste seu SQL durante a edição.

O teste utiliza amostras das tabelas consultadas, o que irá retornar um resultado diferente da execução real do SQL com os dados originais

Para testar seu SQL, primeiro selecione um destino do tipo Via Kondado e, então você verá o botão TESTAR SQL. Basta clicar nele. Você pode também utilizar o atalho CTRL+ENTER

O teste irá considerar todo o SQL contido no editor, independente do que estiver selecionado ou se o texto foi salvo (o que também pode ser feito com CTRL+S)

Caso durante o teste seja encontrado um erro, ele será apresentado. Caso não haja erros, o resultado da execução com a amostra de dados será apresentado e você poderá também executar seu modelo imediatamenete - clicar neste botão irá também salvar o SQL que está em seu editor

Este destino está em modo beta

Consultas (Beta)

Além de baixar tabelas completas, o Via Kondado permite que você faça consultas diretamente nos seus dados — filtrando, agrupando e transformando as informações antes do download.

Com consultas, você pode:

• Filtrar registros por condições específicas (ex: apenas vendas do último mês)
• Selecionar apenas as colunas que precisa
• Agrupar dados e calcular totais, médias, contagens e outras métricas
• Ordenar resultados por qualquer coluna
• Criar colunas calculadas com expressões personalizadas
• Combinar tabelas usando JOINs
• Unir dados de tabelas diferentes com UNION ALL

As consultas utilizam a linguagem KSQL, uma sintaxe própria da Kondado em formato JSON. Veja a referência completa do KSQL para detalhes sobre a sintaxe e funções disponíveis.

ℹ️ Beta: As consultas estão disponíveis em modo beta. Funcionalidades e limites podem ser ajustados.

Como funciona

1. Monte sua consulta usando a sintaxe KSQL (formato JSON)
2. Envie a consulta pela URL do Via Kondado, da mesma forma que faz o download de tabelas
3. O resultado será entregue como um arquivo CSV para download

Endpoints

As consultas são enviadas ao host https://hub.kondado.io, autenticadas com seu token do Via Kondado via parâmetro token na query string:

Método	Endpoint	Descrição
POST	/query?token=SEU_TOKEN	Envia o JSON da consulta no corpo da requisição
GET	/query/{payload_base64}?token=SEU_TOKEN	Envia a consulta codificada em Base64 no caminho da URL
GET	/query?ksql={payload_base64}&token=SEU_TOKEN	Envia a consulta codificada em Base64 como parâmetro de query string
GET	/query?query_id={id}&token=SEU_TOKEN	Executa uma consulta salva pelo ID

POST /query

Envie o JSON no corpo da requisição. A estrutura raiz aceita o campo ksql (com a definição da consulta) ou o campo query_id (ID de uma consulta salva previamente):

{
  "ksql": {
    "table_name": "vendas",
    "columns": ["produto", "valor", "data"],
    "where_conditions": [
      {
        "column": "data",
        "operator": "LAST_N_DAYS",
        "value": 30
      }
    ],
    "order_by": [{"column": "valor", "direction": "desc"}],
    "limit": 1000
  }
}

Executando uma consulta salva pelo ID:

{"query_id": "abc123"}

GET /query/{payload_base64}

Codifique em Base64 apenas o objeto KSQL (sem o envelope {"ksql": ...}) e envie no caminho da URL. Se o valor do caminho não for um Base64 válido, será interpretado como query_id de uma consulta salva.

Formatos de resposta

Parâmetro	Valor	Comportamento
response_format	download (padrão)	Redireciona para o link de download do CSV
response_format	link_and_schema	Retorna JSON com link de download e esquema das colunas

Exemplo de resposta com link_and_schema:

{
  "download_link": "https://...",
  "schema": [
    {"col_name": "produto", "col_type": "STRING"},
    {"col_name": "valor", "col_type": "DOUBLE"}
  ],
  "row_cap": 1000,
  "truncated": false
}

Limite de registros

As consultas retornam no máximo 1.000 registros por execução, independentemente do valor informado no campo limit. A resposta inclui row_cap: 1000 e a flag truncated, que indica se o resultado foi truncado (true) ou retornou todos os registros (false).

Consumo de leituras

O consumo de leituras de consultas é baseado na quantidade de dados escaneados, em incrementos de 10 MB. A cobrança mínima é de 1 leitura por consulta.

Dados escaneados	Leituras consumidas
Até 10 MB	1
10 MB a 20 MB	2
20 MB a 30 MB	3
...	...

💡 Dica: Selecione apenas as colunas que precisa e use filtros para reduzir a quantidade de dados escaneados e economizar leituras.

Desconto no app Kondado: Consultas feitas diretamente pelo aplicativo da Kondado consomem apenas 0,2 leitura por incremento, em vez de 1.

Exemplos

Consulta simples com filtro:

{
  "ksql": {
    "table_name": "clientes",
    "columns": ["nome", "email", "cidade"],
    "where_conditions": [
      {"column": "cidade", "operator": "=", "value": "São Paulo"}
    ],
    "limit": 50
  }
}

Consulta com agrupamento:

{
  "ksql": {
    "table_name": "pedidos",
    "columns": ["categoria", "receita"],
    "column_aggregations": ["none", "sum"],
    "dimensions": ["categoria"],
    "order_by": [{"column": "receita", "direction": "desc"}]
  }
}

Para mais exemplos e a documentação completa da sintaxe, consulte a Referência KSQL.

MCP

O MCP (Model Context Protocol) permite que LLMs e ferramentas de IA — como o Claude e o ChatGPT — acessem os dados da sua Via Kondado por meio de consultas KSQL, de forma autenticada e programática. É um canal adicional ao acesso por CSV, dashboards e BI: enquanto esses são pensados para consumo humano ou por ferramentas tradicionais, o MCP é o caminho oficial para conectar agentes de IA à sua Via Kondado.

Endpoint

O endpoint do MCP é único e igual para todos os clientes — a autenticação é que define a quem cada chamada pertence:

https://mcp.kondado.io/mcp

Autenticação

Há dois caminhos suportados de autenticação. Use o que melhor se encaixa no seu cliente MCP:

1. OAuth (recomendado para apps com suporte a OAuth 2.1 + DCR)

Apps como Claude, ChatGPT e similares — que suportam OAuth 2.1 com Dynamic Client Registration (RFC 7591) — descobrem todas as configurações automaticamente a partir do endpoint /mcp. Você só precisa configurar a URL https://mcp.kondado.io/mcp no app cliente; ele cuida do restante:

1. O cliente recebe um 401 Unauthorized com cabeçalho WWW-Authenticate apontando para o resource-metadata.
2. O cliente descobre o authorization-server pelos endpoints /.well-known/oauth-protected-resource e /.well-known/oauth-authorization-server.
3. O cliente faz Dynamic Client Registration automaticamente.
4. Uma tela de consentimento é aberta em https://app.kondado.com.br/oauth/authorize — você faz login, escolhe a Via Kondado de destino e autoriza.
5. O cliente recebe um access token e um refresh token, e passa a usar Bearer token nas chamadas seguintes.

Para os apps com suporte a OAuth, nenhuma outra configuração além da URL do endpoint é necessária — o app já descobre os fluxos de autenticação e registro sozinho.

2. Token legado (clientes sem OAuth ou configuração manual)

Para clientes MCP que não suportam OAuth/DCR (CLIs simples, scripts próprios, integrações server-to-server), ou quando você prefere usar um token de longa duração, o mesmo token de acesso da sua Via Kondado também funciona como Bearer token no MCP.

Como usar: envie o cabeçalho Authorization: Bearer SEU_TOKEN em cada chamada para https://mcp.kondado.io/mcp. Esse é o mesmo token usado para acessar dados via Link da Via Kondado — veja a seção Token de acesso para saber onde encontrá-lo.

Apps suportados

Veja os guias específicos para cada app cliente:

• Claude
• ChatGPT
• Outros clientes MCP genéricos podem ser configurados manualmente com a URL https://mcp.kondado.io/mcp e o token legado.

Limitações da v1

• Somente leitura: o MCP atualmente permite apenas leitura dos dados — nenhuma operação de escrita, inserção, atualização ou exclusão é exposta.
• Apenas KSQL: as consultas usam exclusivamente a sintaxe KSQL (formato JSON). SQL bruto não é suportado por enquanto.
• Uma Via Kondado por sessão OAuth: cada sessão OAuth é vinculada a uma única Via Kondado. Para acessar dados de outra Via Kondado, basta reautenticar e escolher o destino desejado.

Conexão PostgreSQL (Beta)

Além do link de acesso e do MCP, a sua Via Kondado também aceita conexão pelo protocolo PostgreSQL. Com isso, ferramentas de BI que já falam Postgres — como o Power BI, o Metabase, o Tableau e o DBeaver — se conectam diretamente aos seus dados integrados, sem exportar arquivos e sem que você precise manter um banco de dados próprio.

Você usa o conector PostgreSQL nativo da própria ferramenta e informa o token de acesso da sua Via Kondado como senha. Não é preciso instalar driver, criar banco nem provisionar servidor.

Como funciona

A Via Kondado disponibiliza um endpoint que fala o protocolo do PostgreSQL. As tabelas das suas integrações e as suas consultas salvas aparecem como tabelas comuns dentro do schema public, e a sua ferramenta de BI as consulta com SQL normal.

Vale entender um ponto importante: esse endpoint não é um banco de dados PostgreSQL e não guarda uma cópia dos seus dados. Ele apenas traduz a consulta enviada pela sua ferramenta e devolve o resultado a partir da mesma origem já usada pelo link de acesso e pelo MCP. Por isso o acesso é somente leitura: apenas SELECT é aceito, e comandos de escrita ou de criação de estrutura (INSERT, UPDATE, DELETE, CREATE) são recusados com mensagem de erro.

Dados de conexão

Parâmetro	Valor
Host / Servidor	kdb.kondado.io
Porta	5432
Banco de dados	kdb
Schema	public
Usuário	qualquer valor — não é validado (pode usar kondado)
Senha	o token de acesso da sua Via Kondado
SSL	suportado — recomendamos sslmode=require
Permissões	somente leitura (apenas SELECT)
Linhas por consulta	máximo 1.000 — sem paginação por OFFSET; veja Limite de linhas e paginação

O token de acesso é o mesmo usado no link de acesso e no MCP. Você o encontra na tela da sua Via Kondado, no menu de três barras, na opção Ver token — veja Token de acesso. Não é preciso solicitar liberação: qualquer Via Kondado ativa já aceita a conexão.

Conectando o Power BI

O Power BI se conecta pelo conector PostgreSQL nativo, que já vem instalado — não é necessário instalar nenhum driver adicional.

1. No Power BI Desktop, clique em Obter dados › Banco de dados › Banco de dados PostgreSQL.
2. Em Servidor, informe kdb.kondado.io:5432. Em Banco de dados, informe kdb.
3. Escolha o modo de conectividade: Importar ou DirectQuery. Os dois funcionam.
4. Na tela de credenciais, selecione a aba Banco de dados. Preencha Nome de usuário com qualquer valor e Senha com o token de acesso da sua Via Kondado.
5. No navegador de objetos, expanda kdb › public e selecione as tabelas que deseja usar.

O que aparece como tabela

• As tabelas das suas integrações, com os mesmos nomes usados no link de acesso — veja Padrão de tabelas.
• As suas consultas salvas, que aparecem como tabelas próprias. Filtros e agregações feitos na ferramenta de BI são aplicados sobre o resultado da consulta salva.

O catálogo é atualizado sozinho: uma tabela nova (ou removida) aparece — ou some — em cerca de um minuto, sem precisar reconectar a ferramenta.

Limite de linhas e paginação

Cada consulta feita por esta conexão lê no máximo 1.000 linhas. Esse teto vale sempre: consultas sem LIMIT recebem o limite automaticamente, e consultas com um LIMIT maior são reduzidas para 1.000 — um LIMIT 100000, por exemplo, devolve 1.000 linhas.

Não há paginação: OFFSET não é suportado

Não é possível “virar a página” para buscar as linhas seguintes. Uma consulta com OFFSET diferente de zero é recusada com erro (SQLSTATE 0A000), informando que o recurso não é suportado. A recusa é proposital: sem ela, uma ferramenta que paginasse receberia sempre o mesmo primeiro bloco de linhas acreditando estar avançando.

O que fazer quando você precisa de mais de 1.000 linhas

• Filtre dentro da consulta (por data, cliente, status ou chave) até o recorte caber em 1.000 linhas. O filtro é aplicado na origem dos dados, e não depois da leitura — então ele realmente reduz o que é lido. Quebrar um período grande em vários recortes menores (mês a mês, por exemplo) é a forma suportada de percorrer um volume maior.
• Agregue em vez de detalhar: SUM, COUNT e AVG com GROUP BY são calculados sobre a tabela inteira e voltam com poucas linhas — esse é o uso para o qual a conexão foi desenhada. Atenção: se a agregação gerar mais de 1.000 grupos, o resultado também é truncado em silêncio.
• Use uma consulta salva como tabela: a lógica dela roda sobre o conjunto completo de dados e você recebe apenas o resultado final — que continua limitado a 1.000 linhas.
• Para extrair grandes volumes (a tabela inteira, cargas para outro sistema), use o link de acesso, que é a via preparada para exportação e não tem esse teto.

Limitações

• Somente leitura: nenhuma operação de escrita, alteração, exclusão ou criação de estrutura é permitida.
• Limite de linhas por resultado: cada consulta lê no máximo 1.000 linhas, o corte é silencioso e não há paginação por OFFSET — veja Limite de linhas e paginação.
• Nem todo SQL é aceito: a conexão atende o SQL que as ferramentas de BI normalmente geram (SELECT, WHERE, GROUP BY, ORDER BY, JOIN, LIMIT e funções de agregação). Recursos fora desse conjunto — como window functions (OVER), OFFSET diferente de zero, subconsultas dentro de filtros, SELECT * sobre JOIN, COUNT(DISTINCT a, b) e ORDER BY por expressão arbitrária — retornam um erro explícito, em vez de um resultado aproximado.
• Tipos de dado: os campos são apresentados como text, bigint, double precision, boolean, date ou timestamp.
• Limites de uso: existem limites de frequência de consultas e de conexões simultâneas por token e por origem. Se o seu painel atingir esses limites, reduza a frequência de atualização ou a quantidade de visuais que consultam ao mesmo tempo.
• Beta: a conexão PostgreSQL está em evolução e o conjunto de recursos suportados pode mudar.

Outras ferramentas

Os mesmos dados de conexão valem para Metabase, Tableau e DBeaver, sempre pelo conector PostgreSQL nativo de cada ferramenta. Em geral, qualquer ferramenta que aceite um endpoint PostgreSQL com usuário e senha deve funcionar, respeitando as limitações acima.

Dúvidas comuns do Via Kondado

Preparamos um artigo com respostas às dúvidas comuns sobre o Via Kondado, confira aqui.