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 é enviada como um objeto JSON dentro da chave ksql. Os campos disponíveis são:

Campo	Obrigatório	Descrição
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")
distinct	Não	Quando true, emite SELECT DISTINCT no escopo da consulta (booleano, padrão false)
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
column_aliases	Não	Apelidos para renomear as colunas de saída (mesmo tamanho de columns)
alias	Não	Apelido para a tabela principal (alias de FROM), usado para prefixar colunas
joins	Não	Junção com outras tabelas
union	Não	Array de consultas para combinar com UNION ALL (substitui os demais campos)
with	Não	Array de CTEs (Common Table Expressions) — subconsultas nomeadas reutilizáveis (veja seção abaixo)

Exemplo mínimo

{
  "ksql": {
    "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}
]

Comparação coluna-com-coluna (value_column)

Em vez de comparar uma coluna com um valor fixo, você pode comparar uma coluna com outra coluna usando value_column no lugar de value:

"where_conditions": [
  {"column": "receita", "operator": ">", "value_column": "custo"},
  {"column": "data_envio", "operator": "<=", "value_column": "data_limite"}
]

value_column aceita apenas nomes de colunas válidos (letras, números, _ e .). As mesmas regras de segurança de column se aplicam.

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. Sempre que houver ao menos uma agregação diferente de none na consulta, as colunas marcadas como none viram automaticamente as colunas de agrupamento (GROUP BY implícito).

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 que não recebem agregação — elas viram colunas de agrupamento automaticamente quando há ao menos uma agregação real na consulta.

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

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

Deduplicar resultados (distinct)

A chave distinct é um booleano opcional (padrão false). Quando true, a consulta gerada usa SELECT DISTINCT no escopo correspondente, eliminando linhas duplicadas sem precisar de agregações.

{
  "ksql": {
    "table_name": "pedidos",
    "columns": ["pais", "cidade"],
    "column_aggregations": ["none", "none"],
    "distinct": true
  }
}

Onde usar distinct

• No nível raiz de uma consulta simples (sem union).
• Dentro de cada CTE definida em with[].ksql.
• Dentro de cada item do array union[] — cada arm pode ter seu próprio distinct.

A chave distinct não é aceita no nível raiz de uma consulta com union: a deduplicação deve ser declarada arm por arm.

Apelidos de coluna (column_aliases)

Use column_aliases para renomear as colunas retornadas pela consulta. O array deve ter o mesmo tamanho de columns e column_aggregations. Cada posição define o nome da coluna de saída correspondente. Use null para manter o nome original.

{
  "ksql": {
    "table_name": "pedidos",
    "columns": ["categoria", "receita", "quantidade"],
    "column_aggregations": ["none", "sum", "count"],
    "column_aliases": [null, "total_receita", "total_pedidos"]
  }
}

Neste exemplo, a saída terá as colunas: categoria, total_receita e total_pedidos.

Alias de tabela (alias)

O campo alias no nível raiz define um apelido para a tabela principal da consulta, útil quando você precisa prefixar colunas para evitar ambiguidade (especialmente com JOINs e CTEs).

{
  "ksql": {
    "table_name": "pedidos",
    "alias": "p",
    "columns": ["p.id", "p.cliente_id", "p.total"],
    "joins": [
      {
        "tableName": "clientes",
        "joinType": "LEFT",
        "conditions": [
          {"leftColumn": "p.cliente_id", "rightColumn": "clientes.id"}
        ]
      }
    ]
  }
}

O alias da tabela principal é diferente do alias usado dentro de CTEs no parâmetro with.

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 e order_by, 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:

{
  "ksql": {
    "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.

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

CTEs — Common Table Expressions (with)

O parâmetro with permite criar subconsultas nomeadas (CTEs) que podem ser referenciadas na consulta principal como se fossem tabelas. Isso é útil para organizar consultas complexas em etapas.

O with é um array de objetos. Cada objeto define um CTE com:

Campo	Obrigatório	Descrição
alias	Sim	Nome do CTE (usado como nome de tabela na consulta principal)
ksql	Sim*	Consulta KSQL que define os dados do CTE
saved_query_id	Sim*	ID de uma consulta salva que será usada como CTE (alternativa ao ksql)

* Use ksql ou saved_query_id, nunca ambos.

CTE com consulta inline

{
  "ksql": {
    "with": [
      {
        "alias": "vendas_recentes",
        "ksql": {
          "table_name": "vendas",
          "columns": ["produto", "receita", "data_venda"],
          "where_conditions": [
            {"column": "data_venda", "operator": "LAST_N_DAYS", "value": 30}
          ]
        }
      }
    ],
    "table_name": "vendas_recentes",
    "columns": ["produto", "receita"],
    "column_aggregations": ["none", "sum"],
    "order_by": [{"column": "receita", "direction": "desc"}],
    "limit": 10
  }
}

CTE com consulta salva

Se você possui consultas salvas, pode referenciá-las pelo ID em vez de reescrever o KSQL:

{
  "ksql": {
    "with": [
      {
        "alias": "base_clientes",
        "saved_query_id": 31
      }
    ],
    "table_name": "base_clientes",
    "columns": ["nome", "email", "total_compras"],
    "order_by": [{"column": "total_compras", "direction": "desc"}],
    "limit": 50
  }
}

Múltiplos CTEs

Você pode definir vários CTEs e combiná-los na consulta principal com JOINs:

{
  "ksql": {
    "with": [
      {
        "alias": "receita_produto",
        "ksql": {
          "table_name": "vendas",
          "columns": ["produto_id", "receita"],
          "column_aggregations": ["none", "sum"]
        }
      },
      {
        "alias": "custo_produto",
        "ksql": {
          "table_name": "custos",
          "columns": ["produto_id", "custo_total"],
          "column_aggregations": ["none", "sum"]
        }
      }
    ],
    "table_name": "receita_produto",
    "columns": ["receita_produto.produto_id", "receita_produto.receita", "custo_produto.custo_total"],
    "joins": [
      {
        "tableName": "custo_produto",
        "joinType": "LEFT",
        "conditions": [
          {"leftColumn": "receita_produto.produto_id", "rightColumn": "custo_produto.produto_id"}
        ]
      }
    ]
  }
}

CTEs aninhados

Um CTE pode conter seus próprios CTEs internos, permitindo encadear subconsultas em camadas (um CTE pode referenciar outro CTE já declarado, mas não a si próprio — recursão não é suportada):

{
  "ksql": {
    "with": [
      {
        "alias": "resumo",
        "ksql": {
          "with": [
            {
              "alias": "vendas_mes",
              "ksql": {
                "table_name": "vendas",
                "columns": ["categoria", "receita"],
                "column_aggregations": ["none", "sum"],
                "where_conditions": [
                  {"column": "data_venda", "operator": "LAST_MONTH"}
                ]
              }
            }
          ],
          "table_name": "vendas_mes",
          "columns": ["categoria", "receita"],
          "where_conditions": [
            {"column": "receita", "operator": ">", "value": 1000}
          ]
        }
      }
    ],
    "table_name": "resumo",
    "columns": ["categoria", "receita"],
    "order_by": [{"column": "receita", "direction": "desc"}]
  }
}

⚠️ Todos os CTEs são executados no mesmo banco de dados da consulta principal. As mesmas regras de segurança e validação se aplicam a cada CTE individualmente.

Limites e restrições

Restrição	Valor
Máximo de registros por consulta	1.000
Condições de filtro	Apenas AND
Subconsultas	Suportadas via CTEs (parâmetro with)
UNION simples	Não suportado (apenas UNION ALL)

Exemplos completos

Vendas por região no último mês

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

Top 10 clientes por valor de compra

{
  "ksql": {
    "table_name": "pedidos",
    "columns": ["pedidos.cliente_id", "clientes.nome", "pedidos.valor"],
  "column_aggregations": ["none", "none", "sum"],
  "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

{
  "ksql": {
    "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": 1000
  }
}

Consultas KSQL estão em modo beta