Via Kondado: Referência KSQL

O KSQL é a linguagem de consulta da Kondado. Ele utiliza uma sintaxe em formato JSON que permite filtrar, agrupar, ordenar e transformar seus dados de forma simples e segura.

ℹ️ Beta: Consultas via KSQL estão disponíveis em modo beta.

Estrutura básica

Uma consulta KSQL é um objeto JSON com os seguintes campos:

Campo	Obrigatório	Descrição
dest_collection_id	Sim	Identificador da sua coleção de destino
table_name	Sim	Nome da tabela a ser consultada
columns	Sim	Lista de colunas a retornar
column_aggregations	Não	Tipo de agregação para cada coluna (ex: "sum", "avg", "none")
dimensions	Não	Colunas de agrupamento (equivalente ao GROUP BY)
where_conditions	Não	Condições de filtro
order_by	Não	Ordenação dos resultados
limit	Não	Número máximo de registros (máximo: 1.000)
customColumns	Não	Colunas calculadas com expressões personalizadas
column_transformations	Não	Transformações aplicadas às colunas
joins	Não	Junção com outras tabelas
union	Não	Array de consultas para combinar com UNION ALL (substitui os demais campos)

Exemplo mínimo

{
  "dest_collection_id": 12345,
  "table_name": "vendas",
  "columns": ["produto", "valor", "data"]
}

Filtros (where_conditions)

Os filtros são definidos como uma lista de condições. Todas as condições são combinadas com E (AND).

"where_conditions": [
  {"column": "status", "operator": "=", "value": "ativo"},
  {"column": "valor", "operator": ">", "value": 100}
]

Operadores de comparação

Operador	Descrição	Exemplo de valor
=	Igual a	"ativo"
!=	Diferente de	"cancelado"
>	Maior que	100
<	Menor que	50
>=	Maior ou igual a	100
<=	Menor ou igual a	200

Operadores de conjunto

Operador	Descrição	Exemplo de valor
IN	Está na lista	["SP", "RJ", "MG"]
NOT IN	Não está na lista	["cancelado", "expirado"]

Operadores de texto

Operador	Descrição	Exemplo de valor
LIKE	Corresponde ao padrão (use % como coringa)	"%kondado%"
NOT LIKE	Não corresponde ao padrão	"%teste%"
STARTS_WITH	Começa com	"BR"
ENDS_WITH	Termina com	".com"
CONTAINS	Contém o texto	"kondado"
NOT_CONTAINS	Não contém o texto	"teste"

Operadores de nulo

Operador	Descrição
IS NULL	É nulo
IS NOT NULL	Não é nulo

Operador de intervalo

Operador	Descrição	Exemplo de valor
BETWEEN	Está entre dois valores	[100, 500]

Operadores de data relativa

Estes operadores facilitam filtros de data sem precisar calcular datas manualmente:

Operador	Descrição
LAST_N_DAYS	Últimos N dias
NEXT_N_DAYS	Próximos N dias
LAST_N_HOURS	Últimas N horas
LAST_N_MINUTES	Últimos N minutos
THIS_WEEK	Semana atual
LAST_WEEK	Semana passada
THIS_MONTH	Mês atual
LAST_MONTH	Mês passado
THIS_QUARTER	Trimestre atual
LAST_QUARTER	Trimestre passado
THIS_YEAR	Ano atual
LAST_YEAR	Ano passado

Exemplo:

{"column": "criado_em", "operator": "LAST_N_DAYS", "value": 7}

Agregações

Para calcular métricas sobre seus dados, use column_aggregations junto com dimensions.

O campo column_aggregations é uma lista com o mesmo tamanho de columns. Cada posição define a agregação da coluna correspondente. Use "none" para colunas sem agregação (que devem estar em dimensions).

{
  "table_name": "pedidos",
  "columns": ["categoria", "receita", "quantidade"],
  "column_aggregations": ["none", "sum", "count"],
  "dimensions": ["categoria"]
}

Funções de agregação disponíveis

Função	Descrição
none	Sem agregação (coluna de agrupamento)
sum	Soma dos valores
avg	Média dos valores
count	Contagem de registros
count_distinct	Contagem de valores únicos
min	Valor mínimo
max	Valor máximo
stddev	Desvio padrão
variance	Variância

Ordenação (order_by)

"order_by": [
  {"column": "receita", "direction": "desc"},
  {"column": "nome", "direction": "asc"}
]

Colunas calculadas (customColumns)

Crie colunas derivadas usando expressões:

"customColumns": [
  {"name": "lucro", "expression": "receita - custo"},
  {"name": "margem", "expression": "(receita - custo) / receita * 100"}
]

As colunas calculadas podem ser usadas em columns, where_conditions, order_by e dimensions, como qualquer outra coluna.

Funções disponíveis em expressões

Matemáticas: ABS, CEIL, FLOOR, ROUND, TRUNCATE, MOD, SQRT, POWER, EXP, LOG, LN, SIGN

Texto: UPPER, LOWER, TRIM, LTRIM, RTRIM, SUBSTR, SUBSTRING, LENGTH, REPLACE, CONCAT, SPLIT_PART, LEFT, RIGHT, LPAD, RPAD, REVERSE, REPEAT, INSTR, LOCATE, REGEXP_EXTRACT, REGEXP_REPLACE, REGEXP_LIKE

Data: DATE, YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, DATE_FORMAT, DATE_TRUNC, DATE_ADD, DATE_DIFF, CURRENT_DATE, CURRENT_TIMESTAMP, NOW, EXTRACT, TO_DATE, TO_TIMESTAMP, FROM_UNIXTIME

Conversão: CAST, COALESCE, NULLIF, NVL, IFNULL, GREATEST, LEAST

Condicional: IF, IIF, CASE WHEN ... THEN ... ELSE ... END

Transformações de colunas (column_transformations)

Aplique transformações sequenciais a colunas existentes. As transformações são processadas na ordem em que aparecem.

"column_transformations": {
  "nome": [
    {"type": "text", "operation": "uppercase"}
  ],
  "criado_em": [
    {"type": "date", "operation": "year_month"}
  ],
  "valor": [
    {"type": "number", "operation": "round", "params": {"decimals": 2}}
  ]
}

Transformações de texto: uppercase, lowercase, trim, ltrim, rtrim, extract_domain, extract_before, extract_after, replace (params: find, replace), regexp_extract (params: pattern), regexp_replace (params: pattern, replacement)

Transformações de data: date, year_month, year_week, year_quarter, year, hour, minute, extract_year, extract_month, extract_day, extract_hour, date_add_days (params: days), date_add_hours (params: hours), date_add_minutes (params: minutes)

Transformações numéricas: round (params: decimals), floor, ceil, abs, truncate (params: decimals), divide (params: divisor), multiply (params: multiplier)

Conversões de tipo: cast_to_text, cast_to_int, cast_to_number, cast_to_date, cast_to_timestamp

JOINs

Combine dados de múltiplas tabelas:

{
  "table_name": "pedidos",
  "columns": ["pedidos.id", "clientes.nome", "pedidos.total"],
  "column_aggregations": ["none", "none", "none"],
  "joins": [
    {
      "tableName": "clientes",
      "joinType": "LEFT",
      "conditions": [
        {
          "leftColumn": "pedidos.cliente_id",
          "rightColumn": "clientes.id"
        }
      ]
    }
  ]
}

Tipos de JOIN: INNER (apenas registros com correspondência), LEFT (todos da tabela principal + correspondências), RIGHT (todos da tabela unida + correspondências), FULL (todos de ambas), CROSS (produto cartesiano).

Ao usar JOINs, prefixe os nomes das colunas com o nome da tabela (ex: pedidos.id, clientes.nome).

UNION ALL

Combine resultados de consultas em tabelas diferentes. Todas as consultas ficam dentro do array union (mínimo 2). Os campos order_by e limit ficam no nível raiz.

{
  "union": [
    {
      "table_name": "vendas_2025",
      "dest_collection_id": 12345,
      "columns": ["mes", "receita"],
      "column_aggregations": ["none", "sum"],
      "dimensions": ["mes"]
    },
    {
      "table_name": "vendas_2024",
      "columns": ["mes", "receita"],
      "column_aggregations": ["none", "sum"],
      "dimensions": ["mes"]
    }
  ],
  "order_by": [{"column": "receita", "direction": "desc"}],
  "limit": 500
}

Limites e restrições

Restrição	Valor
Máximo de registros por consulta	1.000
Condições de filtro	Apenas AND
Subconsultas	Não suportadas
DISTINCT	Não suportado (use count_distinct)
UNION simples	Não suportado (apenas UNION ALL)

Exemplos completos

Vendas por região no último mês

{
  "dest_collection_id": 12345,
  "table_name": "vendas",
  "columns": ["regiao", "receita", "pedidos"],
  "column_aggregations": ["none", "sum", "count"],
  "dimensions": ["regiao"],
  "where_conditions": [
    {"column": "data_venda", "operator": "LAST_MONTH"}
  ],
  "order_by": [{"column": "receita", "direction": "desc"}]
}

Top 10 clientes por valor de compra

{
  "dest_collection_id": 12345,
  "table_name": "pedidos",
  "columns": ["pedidos.cliente_id", "clientes.nome", "pedidos.valor"],
  "column_aggregations": ["none", "none", "sum"],
  "dimensions": ["pedidos.cliente_id", "clientes.nome"],
  "joins": [
    {
      "tableName": "clientes",
      "joinType": "LEFT",
      "conditions": [
        {"leftColumn": "pedidos.cliente_id", "rightColumn": "clientes.id"}
      ]
    }
  ],
  "order_by": [{"column": "valor", "direction": "desc"}],
  "limit": 10
}

Filtro com múltiplas condições

{
  "dest_collection_id": 12345,
  "table_name": "leads",
  "columns": ["nome", "email", "origem", "score"],
  "where_conditions": [
    {"column": "score", "operator": ">=", "value": 80},
    {"column": "origem", "operator": "IN", "value": ["google", "facebook"]},
    {"column": "email", "operator": "IS NOT NULL"},
    {"column": "criado_em", "operator": "LAST_N_DAYS", "value": 90}
  ],
  "order_by": [{"column": "score", "direction": "desc"}],
  "limit": 100
}

Consultas KSQL estão em modo beta