fn_registry/docs/capabilities/tql.md

group, tag, lang, domain, n, description

group	tag	lang	domain	n	description
cpp-tables	cpp-tables	cpp	core	10	Table Query Language: pipeline de transformacion tabular pura (filter, group, agg, sort, join, stats, formulas Lua, emit/apply round-trip) + render UI completa (data_table).

cpp-tables — Table Query Language (C++ puro)

Stack de transformacion tabular C++. Nucleo headless (filtros, agrupacion, stats, joins, formulas Lua, round-trip TQL). Entry-point de render via data_table_cpp_viz que compone todo el stack con UI ImGui completa. Apps migran desde el playground cambiando solo el include path.

Funciones del grupo

ID	Firma corta	Que hace
auto_detect_type_cpp_core	ColumnType auto_detect_type(cells, rows, cols, col, sample_n=64)	Infiere ColumnType escaneando hasta N celdas no-vacias
compute_column_stats_cpp_core	ColStats compute_column_stats(cells, rows, cols, col, ...)	Mean, p25/p50/p75, hist 24 bins, top-8 categorias
compute_stage_cpp_core	StageOutput compute_stage(cells, rows, cols, headers, types, stage)	Ejecuta un Stage TQL: filter → group+agg → sort
compute_pipeline_cpp_core	StageOutput compute_pipeline(cells, rows, cols, headers, types, stages)	Encadena N stages secuencialmente
join_tables_cpp_core	StageOutput join_tables(left..., right, jn)	Hash join multi-key (inner/left/right/full)
lua_engine_cpp_core	Engine* get(); string eval(engine, id, ctx, err)	Motor Lua 5.4 sandbox para formulas de columnas derivadas
tql_emit_cpp_core	std::string tql::emit(state, headers, types)	Serializa State a texto Lua TQL v1
tql_apply_cpp_core	ApplyResult tql::apply(lua_text, available_headers)	Parsea texto TQL v1 y produce State + warnings
tql_helpers_cpp_core	op_label, view_mode_token, agg_fn_token, ...	Conversiones puras enum↔token usadas por emit/apply

Tipos usados

• data_table_types_cpp_core — enums y structs base: ColumnType, Op, Stage, StageOutput, Filter, Aggregation, Join, TableInput, ViewMode, VizPanel, ViewConfig, State, etc.

Ejemplo canonico end-to-end

// 1. Datos raw (row-major, 4 filas x 3 cols)
#include "core/auto_detect_type.h"
#include "core/compute_pipeline.h"
#include "core/tql_emit.h"
#include "core/tql_apply.h"
using namespace data_table;

const char* raw[] = {
    "EU","A","100",
    "US","A","200",
    "EU","B","300",
    "EU","A","50"
};
std::vector<std::string> hdrs  = {"region","type","revenue"};

// 2. Auto-detectar tipos
std::vector<ColumnType> types;
for (int c = 0; c < 3; ++c) types.push_back(auto_detect_type(raw, 4, 3, c));

// 3. Pipeline: filtrar EU, agrupar por type, sumar revenue
Stage s0;
s0.filters.push_back({0, Op::Eq, "EU"});

Stage s1;
s1.breakouts = {"type"};
Aggregation agg; agg.fn = AggFn::Sum; agg.col = "revenue"; s1.aggregations.push_back(agg);
s1.sorts.push_back({"sum_revenue", true});

// 4. Ejecutar pipeline
StageOutput out = compute_pipeline(raw, 4, 3, hdrs, types, {s0, s1});
// out.rows==2: [B,300] [A,150]

// 5. Persistir estado como TQL (para guardar en BD o portapapeles)
State st;
st.stages = {s0, s1};
st.display = ViewMode::Bar;
std::string tql_text = tql::emit(st, hdrs, types);

// 6. Restaurar desde TQL
tql::ApplyResult res = tql::apply(tql_text, hdrs);
if (res.ok) {
    // res.state listo — compilar formulas derivadas con lua_engine si las hay
}

| data_table_cpp_viz | void data_table::render(id, tables, st, show_chrome=true) | Render UI completa: chips bar, tabla, viz panels, drill, TQL editor, Ask AI. Entry-point publica del stack. |

Fronteras del grupo headless (core)

• NO incluye render: ningun include de ImGui, ImPlot ni tipos de ventana.
• NO incluye I/O: no lee archivos CSV, no escribe a disco.
• El motor Lua (lua_engine) es la unica funcion impura del grupo — gestiona estado del interprete.
• tql_apply abre/cierra su propio lua_State por llamada (no usa lua_engine internamente). Fórmulas en DerivedColumn.formula se almacenan verbatim; el caller las compila con lua_engine::compile().
• La deteccion de fechas solo reconoce ISO 8601 (YYYY-MM-DD). Otros formatos caen en String.
• Los joins trabajan sobre TableInput en memoria; no hay join lazy ni streaming.

Prerequisitos

• data_table_types_cpp_core debe estar en el include path (cpp/functions/).
• Para lua_engine y tql_apply: linkar contra la lib Lua 5.4 vendored (cpp/vendor/lua/, target lua54).
• Para tests headless: usar add_fn_test del cpp/tests/CMakeLists.txt — no necesita fn_framework ni ImGui context.