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")
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)
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 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).

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

{
  "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"],
      "dimensions": ["mes"]
      },
      {
        "table_name": "vendas_2024",
      "columns": ["mes", "receita"],
      "column_aggregations": ["none", "sum"],
      "dimensions": ["mes"]
      }
    ],
    "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"],
    "dimensions": ["produto"],
    "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"],
          "dimensions": ["produto_id"]
        }
      },
      {
        "alias": "custo_produto",
        "ksql": {
          "table_name": "custos",
          "columns": ["produto_id", "custo_total"],
          "column_aggregations": ["none", "sum"],
          "dimensions": ["produto_id"]
        }
      }
    ],
    "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 (recursivos)

Um CTE pode conter seus próprios CTEs internos, permitindo encadeamento de subconsultas:

{
  "ksql": {
    "with": [
      {
        "alias": "resumo",
        "ksql": {
          "with": [
            {
              "alias": "vendas_mes",
              "ksql": {
                "table_name": "vendas",
                "columns": ["categoria", "receita"],
                "column_aggregations": ["none", "sum"],
                "dimensions": ["categoria"],
                "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)
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

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

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

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

Consultas KSQL estão em modo beta