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. 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+" na barra superior, 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": 100
  }
}

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"}
  ]
}

Limite de registros

As consultas retornam no máximo 1.000 registros por execução, independentemente do valor informado no campo limit.

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.

Dúvidas comuns do Via Kondado

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