yobx.sql — parse module#

SQL parser — translates a SQL string into a structured list of SqlOperation objects.

The parser handles a small but useful subset of SQL:

SELECT — column selection and simple arithmetic expressions (+, -, *, /).
WHERE / filter — comparison predicates (=, <, >, <=, >=, <>/!=) combined with AND / OR.
GROUP BY — column grouping (aggregations SUM, COUNT, AVG, MIN, MAX in the SELECT list are recognised).
JOIN — [INNER] JOIN … ON col1 = col2 linking two input tables.
Subqueries in the FROM clause: SELECT … FROM (SELECT … FROM table) [AS alias].

All names are case-insensitive; they are normalised to lower-case by parse_sql().

class yobx.sql.parse.AggExpr(func: str, arg: object)[source]#: An aggregation expression: SUM(col), COUNT(*), etc.

class yobx.sql.parse.BinaryExpr(left: object, op: str, right: object)[source]#: A binary expression: left op right.

class yobx.sql.parse.ColumnRef(column: str, table: str | None = None)[source]#: A bare column reference, optionally qualified: table.column.

class yobx.sql.parse.Condition(left: object, op: str, right: object)[source]#: A WHERE predicate, either a leaf comparison or a compound AND / OR.

class yobx.sql.parse.FilterOp(condition: Condition = <factory>)[source]#

Represents a WHERE clause.

Parameters:: condition – the parsed predicate tree.

class yobx.sql.parse.FuncCallExpr(func: str, args: List[object])[source]#: A call to a user-defined (custom) function: func_name(arg1, arg2, …).

class yobx.sql.parse.GroupByOp(columns: List[str] = <factory>)[source]#

Represents a GROUP BY clause.

Parameters:: columns – the column names to group by.

class yobx.sql.parse.JoinOp(right_table: str = '', left_key: str = '', right_key: str = '', join_type: str = 'inner')[source]#

Represents a JOIN clause.

Parameters:

right_table – the name of the right-hand table being joined.
left_key – column name from the left table used in the equi-join.
right_key – column name from the right table used in the equi-join.
join_type – 'inner' (default), 'left', 'right', or 'full'.

class yobx.sql.parse.Literal(value: object)[source]#: A scalar literal value (number or quoted string).

class yobx.sql.parse.ParsedQuery(operations: List[SqlOperation] = <factory>, from_table: str = '', columns: List[str] = <factory>, subquery: ParsedQuery | None = None)[source]#

The result of parse_sql().

Parameters:

operations – ordered list of SqlOperation objects derived from the SQL string. The order reflects the logical execution sequence: JoinOp (if any) → FilterOp (if any) → GroupByOp (if any) → SelectOp.
from_table – the primary (left) table name from the FROM clause, or the alias of the subquery when subquery is set.
columns – all column names referenced in the query, in the order they appear (deduped).
subquery – when the FROM clause contains a sub-select (FROM (SELECT …)), this holds the parsed inner query; otherwise None.

class yobx.sql.parse.SelectItem(expr: object, alias: str | None = None)[source]#

One item in the SELECT list: an expression with an optional alias.

output_name() → str[source]#: Return the alias, or derive a name from the expression.

class yobx.sql.parse.SelectOp(items: List[SelectItem] = <factory>, distinct: bool = False)[source]#

Represents the SELECT clause.

Parameters:

items – the list of SelectItem objects to compute.
distinct – True when the query contains SELECT DISTINCT.

class yobx.sql.parse.SqlOperation[source]#: Base class for all SQL operations produced by parse_sql().

yobx.sql.parse.parse_sql(query: str) → ParsedQuery[source]#

Parse a SQL query string and return a ParsedQuery.

The parser handles:

SELECT [DISTINCT] expr [AS alias], …
FROM table
FROM (SELECT …) [AS alias] — subquery in the FROM clause
[INNER|LEFT|RIGHT|FULL [OUTER]] JOIN table ON col = col
WHERE condition [AND|OR condition] …
GROUP BY col, …

Column names in the returned operations are normalised to lower-case.

Parameters:: query – the SQL query string to parse.
Returns:: a ParsedQuery with an operations list and a columns list of all referenced column names.

<<<

from yobx.sql.parse import parse_sql

pq = parse_sql("SELECT a, b FROM t WHERE a > 0")
for op in pq.operations:
    print(type(op).__name__, op)

>>>

    FilterOp FilterOp(condition=Condition(left=ColumnRef(column='a', table=None), op='>', right=Literal(value=0)))
    SelectOp SelectOp(items=[SelectItem(expr=ColumnRef(column='a', table=None), alias=None), SelectItem(expr=ColumnRef(column='b', table=None), alias=None)], distinct=False)

yobx.sql — parse module#

This Page