apunkt/ktx
1
0
Fork 0
mirror of https://github.com/Kaelio/ktx.git synced 2026-06-07 07:55:13 +02:00
Code Issues Projects Releases Packages Wiki Activity

Polish documentation copy (#98)

Browse source
This commit is contained in:
Luca Martial 2026-05-14 12:43:14 -04:00 • committed by GitHub
parent ce23aca4c4
commit 372c90b533
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
65 changed files with 478 additions and 478 deletions
Download patch file Download diff file Expand all files Collapse all files

8
python/ktx-sl/AGENTS.md
View file

@ -1,6 +1,6 @@
# Semantic Layer Engine
Python semantic layer that generates SQL from structured JSON queries. No `from` clause — sources are inferred from fully-qualified field names (`source.column`).
Python semantic layer that generates SQL from structured JSON queries. No `from` clause - sources are inferred from fully-qualified field names (`source.column`).
## Quick Start
@ -16,7 +16,7 @@ Use `--model` to pass a self-contained YAML model (list of source definitions) i
### 1. Create an inline model file
```yaml
# /tmp/model.yaml — a YAML list of source definitions
# /tmp/model.yaml - a YAML list of source definitions
- name: orders
table: public.orders
grain: [id]
@ -119,9 +119,9 @@ uv run python -m semantic_layer.cli --model /tmp/model.yaml \
## Coding Guidelines
### Expression handling — always use sqlglot AST, never regex on SQL
### Expression handling - always use sqlglot AST, never regex on SQL
- **Parse expressions** with `sqlglot.parse_one(f"SELECT {expr}")` and walk/transform the AST. Never use `str.replace()`, `re.sub()`, or string splitting on SQL fragments — these corrupt string literals, aliases, and nested expressions.
- **Parse expressions** with `sqlglot.parse_one(f"SELECT {expr}")` and walk/transform the AST. Never use `str.replace()`, `re.sub()`, or string splitting on SQL fragments - these corrupt string literals, aliases, and nested expressions.
- **Quote reserved words first**: always call `quote_reserved_identifiers(expr)` before passing to `sqlglot.parse_one()`. Column/source names like `group`, `key`, `order` will fail to parse otherwise.
- **Use the parse cache** in `parser.py` (`ExpressionParser._parse_as_select()`) for read-only AST walks. Direct `sqlglot.parse_one()` calls are fine when you need to `.transform()` the tree.
- **Regex is fine for non-SQL tasks**: sanitizing alias names, masking string literals before parse, etc. The rule is: don't use regex to interpret SQL structure.