polyglot-sql 0.5.2__tar.gz → 0.5.4__tar.gz

{polyglot_sql-0.5.2 → polyglot_sql-0.5.4}/Cargo.lock

@@ -605,7 +605,7 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "criterion",
  "once_cell",
@@ -621,7 +621,7 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql-ffi"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "cbindgen",
  "polyglot-sql",
@@ -631,11 +631,11 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql-function-catalogs"
-version = "0.5.2"
+version = "0.5.4"
 
 [[package]]
 name = "polyglot-sql-python"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "polyglot-sql",
  "pyo3",
@@ -646,7 +646,7 @@ dependencies = [
 
 [[package]]
 name = "polyglot-sql-wasm"
-version = "0.5.2"
+version = "0.5.4"
 dependencies = [
  "console_error_panic_hook",
  "js-sys",

{polyglot_sql-0.5.2 → polyglot_sql-0.5.4}/Cargo.toml

@@ -6,7 +6,7 @@ exclude = [
 ]
 
 [workspace.package]
-version = "0.5.2"
+version = "0.5.4"
 edition = "2021"
 license = "MIT"
 authors = ["polyglot contributors"]

{polyglot_sql-0.5.2 → polyglot_sql-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyglot-sql
-Version: 0.5.2
+Version: 0.5.4
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -68,6 +68,16 @@ polyglot_sql.parse_one("VARCHAR(255)", dialect="duckdb", into=polyglot_sql.DataT
 polyglot_sql.format_sql("SELECT a,b FROM t WHERE x=1", dialect="postgres")
 ```
 
+```python
+ast = polyglot_sql.parse_one("SELECT id FROM a UNION ALL SELECT id FROM b")
+order_expr = polyglot_sql.parse_one("SELECT id").args["expressions"][0]
+ast = polyglot_sql.set_limit(ast, 100)
+ast = polyglot_sql.set_offset(ast, 10)
+ast = polyglot_sql.set_order_by(ast, order_expr)
+polyglot_sql.generate(ast)
+# ["SELECT id FROM a UNION ALL SELECT id FROM b ORDER BY id LIMIT 100 OFFSET 10"]
+```
+
 ### Format Guard Behavior
 
 `format_sql` uses Rust core formatting guards with default limits:
@@ -125,29 +135,72 @@ emission are intentionally out of scope.
 
 ```python
 analysis = polyglot_sql.analyze_query(
-    "SELECT SUM(o.amount) AS total FROM orders AS o",
+    "WITH base AS (SELECT id, amount FROM orders) SELECT * FROM base",
     {
         "dialect": "generic",
         "schema": {
             "tables": [
                 {
                     "name": "orders",
-                    "columns": [{"name": "amount", "type": "DECIMAL(10,2)"}],
+                    "columns": [
+                        {"name": "id", "type": "INT", "nullable": False},
+                        {"name": "amount", "type": "DECIMAL(10,2)", "nullable": True},
+                    ],
                 }
             ]
         },
     },
 )
-print(analysis["projections"][0]["transformKind"])  # "aggregation"
-print(analysis["projections"][0]["typeHint"])       # "DECIMAL(10, 2)"
+print(analysis["cteFacts"][0]["bodySql"])           # "SELECT id, amount FROM orders"
+print(analysis["starProjections"][0]["expandedColumns"])  # ["id", "amount"]
+print(analysis["projections"][0]["nullability"])    # "non_null"
 print(analysis["baseTables"][0]["name"])            # "orders"
+print(analysis["baseTables"][0]["table"])           # "orders"
 ```
 
 `analysis["relations"]` reports sources visible in the analyzed scope.
 `analysis["baseTables"]` reports deduplicated physical table dependencies across
-nested CTEs, derived tables, subqueries, and set-operation branches. Validation
+nested CTEs, derived tables, subqueries, and set-operation branches. For
+physical relation facts, `name` remains the qualified display name while
+`catalog`, `schema`, and `table` expose parsed identifier parts. Validation
 uses broad type families, while query analysis preserves parseable detailed
-schema type strings for projection `typeHint` values.
+schema type strings for projection `typeHint` values. `analysis["cteFacts"]`
+reports top-level CTE definitions, `analysis["starProjections"]` records the
+original star projections and schema-expanded columns, and each projection has
+conservative `nullability`: `"non_null"`, `"nullable"`, or `"unknown"`.
+Function-like projections may include `transformFunction` with the function
+name, literal arguments, and column arguments, for example for
+`DATE_TRUNC('month', created_at)`.
+
+Validation schema dictionaries use:
+
+```python
+schema = {
+    "strict": True,
+    "tables": [
+        {
+            "name": "orders",
+            "schema": "analytics",
+            "aliases": ["o"],
+            "primaryKey": ["id"],
+            "uniqueKeys": [["external_id"]],
+            "foreignKeys": [
+                {
+                    "columns": ["customer_id"],
+                    "references": {"table": "customers", "columns": ["id"]},
+                }
+            ],
+            "columns": [
+                {"name": "id", "type": "INT", "nullable": False, "primaryKey": True},
+                {"name": "amount", "type": "DECIMAL(10,2)", "nullable": True},
+            ],
+        }
+    ],
+}
+```
+
+Use the `type` key for column types. `dataType` / `data_type` are not accepted
+aliases in this payload.
 
 ## API Reference
 

{polyglot_sql-0.5.2/crates/polyglot-sql-python → polyglot_sql-0.5.4}/README.md

@@ -41,6 +41,16 @@ polyglot_sql.parse_one("VARCHAR(255)", dialect="duckdb", into=polyglot_sql.DataT
 polyglot_sql.format_sql("SELECT a,b FROM t WHERE x=1", dialect="postgres")
 ```
 
+```python
+ast = polyglot_sql.parse_one("SELECT id FROM a UNION ALL SELECT id FROM b")
+order_expr = polyglot_sql.parse_one("SELECT id").args["expressions"][0]
+ast = polyglot_sql.set_limit(ast, 100)
+ast = polyglot_sql.set_offset(ast, 10)
+ast = polyglot_sql.set_order_by(ast, order_expr)
+polyglot_sql.generate(ast)
+# ["SELECT id FROM a UNION ALL SELECT id FROM b ORDER BY id LIMIT 100 OFFSET 10"]
+```
+
 ### Format Guard Behavior
 
 `format_sql` uses Rust core formatting guards with default limits:
@@ -98,29 +108,72 @@ emission are intentionally out of scope.
 
 ```python
 analysis = polyglot_sql.analyze_query(
-    "SELECT SUM(o.amount) AS total FROM orders AS o",
+    "WITH base AS (SELECT id, amount FROM orders) SELECT * FROM base",
     {
         "dialect": "generic",
         "schema": {
             "tables": [
                 {
                     "name": "orders",
-                    "columns": [{"name": "amount", "type": "DECIMAL(10,2)"}],
+                    "columns": [
+                        {"name": "id", "type": "INT", "nullable": False},
+                        {"name": "amount", "type": "DECIMAL(10,2)", "nullable": True},
+                    ],
                 }
             ]
         },
     },
 )
-print(analysis["projections"][0]["transformKind"])  # "aggregation"
-print(analysis["projections"][0]["typeHint"])       # "DECIMAL(10, 2)"
+print(analysis["cteFacts"][0]["bodySql"])           # "SELECT id, amount FROM orders"
+print(analysis["starProjections"][0]["expandedColumns"])  # ["id", "amount"]
+print(analysis["projections"][0]["nullability"])    # "non_null"
 print(analysis["baseTables"][0]["name"])            # "orders"
+print(analysis["baseTables"][0]["table"])           # "orders"
 ```
 
 `analysis["relations"]` reports sources visible in the analyzed scope.
 `analysis["baseTables"]` reports deduplicated physical table dependencies across
-nested CTEs, derived tables, subqueries, and set-operation branches. Validation
+nested CTEs, derived tables, subqueries, and set-operation branches. For
+physical relation facts, `name` remains the qualified display name while
+`catalog`, `schema`, and `table` expose parsed identifier parts. Validation
 uses broad type families, while query analysis preserves parseable detailed
-schema type strings for projection `typeHint` values.
+schema type strings for projection `typeHint` values. `analysis["cteFacts"]`
+reports top-level CTE definitions, `analysis["starProjections"]` records the
+original star projections and schema-expanded columns, and each projection has
+conservative `nullability`: `"non_null"`, `"nullable"`, or `"unknown"`.
+Function-like projections may include `transformFunction` with the function
+name, literal arguments, and column arguments, for example for
+`DATE_TRUNC('month', created_at)`.
+
+Validation schema dictionaries use:
+
+```python
+schema = {
+    "strict": True,
+    "tables": [
+        {
+            "name": "orders",
+            "schema": "analytics",
+            "aliases": ["o"],
+            "primaryKey": ["id"],
+            "uniqueKeys": [["external_id"]],
+            "foreignKeys": [
+                {
+                    "columns": ["customer_id"],
+                    "references": {"table": "customers", "columns": ["id"]},
+                }
+            ],
+            "columns": [
+                {"name": "id", "type": "INT", "nullable": False, "primaryKey": True},
+                {"name": "amount", "type": "DECIMAL(10,2)", "nullable": True},
+            ],
+        }
+    ],
+}
+```
+
+Use the `type` key for column types. `dataType` / `data_type` are not accepted
+aliases in this payload.
 
 ## API Reference
 

{polyglot_sql-0.5.2 → polyglot_sql-0.5.4}/crates/polyglot-sql/Cargo.toml

@@ -106,7 +106,7 @@ thiserror = { workspace = true }
 unicode-segmentation = { workspace = true }
 stacker = { version = "0.1", optional = true }
 ts-rs = { version = "12.0", features = ["serde-compat"], optional = true }
-polyglot-sql-function-catalogs = { path = "../polyglot-sql-function-catalogs", version = "0.5.2", optional = true, default-features = false }
+polyglot-sql-function-catalogs = { path = "../polyglot-sql-function-catalogs", version = "0.5.4", optional = true, default-features = false }
 
 [dev-dependencies]
 pretty_assertions = "1.4"

{polyglot_sql-0.5.2 → polyglot_sql-0.5.4}/crates/polyglot-sql/README.md

@@ -318,19 +318,31 @@ scope, while `base_tables` reports deduplicated physical table dependencies
 across CTEs, derived tables, subqueries, and set-operation branches. When a
 `ValidationSchema` is supplied, detailed type strings such as `DECIMAL(10,2)`
 are preserved in projection `type_hint` values when parseable.
+For physical table relations, `name` remains the qualified display name and
+`catalog`, `schema`, and `table` expose parsed identifier parts.
+`cte_facts` reports top-level CTE names, declared columns, original CTE body SQL,
+and CTE output columns. `star_projections` reports the original top-level star
+projection index, optional table qualifier, and schema-expanded columns when
+known. Each projection also includes conservative `nullability`:
+`non_null`, `nullable`, or `unknown`.
 
 ```rust
-use polyglot_sql::{analyze_query, AnalyzeQueryOptions, DialectType, QueryShape};
+use polyglot_sql::{
+    analyze_query, AnalyzeQueryOptions, DialectType, ProjectionNullability, QueryShape,
+};
 
 let schema: polyglot_sql::ValidationSchema = serde_json::from_value(serde_json::json!({
     "tables": [{
         "name": "orders",
-        "columns": [{"name": "amount", "type": "DECIMAL(10,2)"}]
+        "columns": [
+            {"name": "id", "type": "INT", "nullable": false},
+            {"name": "amount", "type": "DECIMAL(10,2)", "nullable": true}
+        ]
     }]
 })).unwrap();
 
 let analysis = analyze_query(
-    "SELECT SUM(o.amount) AS total FROM orders o",
+    "WITH base AS (SELECT id, amount FROM orders) SELECT * FROM base",
     AnalyzeQueryOptions {
         dialect: DialectType::Generic,
         schema: Some(schema),
@@ -338,12 +350,44 @@ let analysis = analyze_query(
 ).unwrap();
 
 assert_eq!(analysis.shape, QueryShape::Select);
-assert_eq!(analysis.projections[0].name.as_deref(), Some("total"));
-assert_eq!(analysis.projections[0].transform_kind, polyglot_sql::TransformKind::Aggregation);
+assert_eq!(analysis.cte_facts[0].name, "base");
+assert_eq!(analysis.cte_facts[0].body_sql, "SELECT id, amount FROM orders");
+assert_eq!(analysis.star_projections[0].expanded_columns, vec!["id", "amount"]);
+assert_eq!(analysis.projections[0].nullability, ProjectionNullability::NonNull);
 assert_eq!(analysis.base_tables[0].name, "orders");
-assert_eq!(analysis.base_tables[0].alias.as_deref(), Some("o"));
+assert_eq!(analysis.base_tables[0].table.as_deref(), Some("orders"));
+```
+
+External JSON schemas use this shape:
+
+```json
+{
+  "strict": true,
+  "tables": [
+    {
+      "name": "orders",
+      "schema": "analytics",
+      "aliases": ["o"],
+      "primaryKey": ["id"],
+      "uniqueKeys": [["external_id"]],
+      "foreignKeys": [
+        {
+          "columns": ["customer_id"],
+          "references": { "table": "customers", "columns": ["id"] }
+        }
+      ],
+      "columns": [
+        { "name": "id", "type": "INT", "nullable": false, "primaryKey": true },
+        { "name": "amount", "type": "DECIMAL(10,2)", "nullable": true }
+      ]
+    }
+  ]
+}
 ```
 
+Use the `type` key for column types in JSON. `dataType` / `data_type` are not
+accepted aliases.
+
 ### Tokenize
 
 Access the raw token stream with full source position spans. Each token carries a `Span` with byte offsets and line/column numbers.

polyglot_sql-0.5.4/crates/polyglot-sql/src/ast_json.rs

@@ -0,0 +1,278 @@
+//! Compatibility helpers for Expression JSON accepted at public API boundaries.
+//!
+//! The canonical AST representation is the serde JSON form of [`Expression`].
+//! Some wrappers historically exposed JavaScript values that stringify unit
+//! variants such as `Expression::Null` as `{}`. These helpers repair that
+//! narrow compatibility shape while preserving errors for unknown AST forms.
+
+use crate::expressions::Expression;
+use serde_json::{json, Value};
+
+/// Deserialize a single [`Expression`] from JSON, accepting known compatibility
+/// shapes used by SDK boundaries.
+pub fn expression_from_str(input: &str) -> Result<Expression, String> {
+    let value: Value = serde_json::from_str(input).map_err(|error| error.to_string())?;
+    expression_from_value(value)
+}
+
+/// Deserialize a list of [`Expression`] values from JSON, accepting known
+/// compatibility shapes used by SDK boundaries.
+pub fn expressions_from_str(input: &str) -> Result<Vec<Expression>, String> {
+    let value: Value = serde_json::from_str(input).map_err(|error| error.to_string())?;
+    expressions_from_value(value)
+}
+
+/// Deserialize a single [`Expression`] from a JSON value.
+pub fn expression_from_value(value: Value) -> Result<Expression, String> {
+    match serde_json::from_value::<Expression>(value.clone()) {
+        Ok(expression) => Ok(expression),
+        Err(original_error) => {
+            let mut repaired = value;
+            normalize_expression_value(&mut repaired);
+            serde_json::from_value::<Expression>(repaired)
+                .map_err(|error| format!("{error}; original error: {original_error}"))
+        }
+    }
+}
+
+/// Deserialize a list of [`Expression`] values from a JSON value.
+pub fn expressions_from_value(value: Value) -> Result<Vec<Expression>, String> {
+    match serde_json::from_value::<Vec<Expression>>(value.clone()) {
+        Ok(expressions) => Ok(expressions),
+        Err(original_error) => {
+            let mut repaired = value;
+            if let Value::Array(items) = &mut repaired {
+                for item in items {
+                    normalize_expression_value(item);
+                }
+            }
+            serde_json::from_value::<Vec<Expression>>(repaired)
+                .map_err(|error| format!("{error}; original error: {original_error}"))
+        }
+    }
+}
+
+/// Serialize an [`Expression`] through serde JSON first so wrapper layers expose
+/// canonical JSON-compatible values instead of runtime-specific JS shapes.
+pub fn expression_to_value(expression: &Expression) -> Result<Value, String> {
+    serde_json::to_value(expression).map_err(|error| error.to_string())
+}
+
+fn normalize_expression_value(value: &mut Value) {
+    match value {
+        Value::Object(map) if map.is_empty() => {
+            *value = json!({ "null": null });
+        }
+        Value::Object(map) if map.len() == 1 => {
+            let (kind, payload) = map.iter_mut().next().expect("single entry exists");
+            if kind == "null" && matches!(payload, Value::Object(inner) if inner.is_empty()) {
+                *payload = Value::Null;
+                return;
+            }
+
+            if kind == "is_null" {
+                normalize_is_null_payload(payload);
+            }
+
+            match payload {
+                Value::Object(payload_map) => normalize_struct_fields(payload_map),
+                Value::Array(items) => {
+                    for item in items {
+                        normalize_expression_value(item);
+                    }
+                }
+                _ => {}
+            }
+        }
+        Value::Object(map) => normalize_struct_fields(map),
+        Value::Array(items) => {
+            for item in items {
+                normalize_expression_value(item);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn normalize_is_null_payload(payload: &mut Value) {
+    let Value::Array(items) = payload else {
+        return;
+    };
+    if items.len() != 1 {
+        return;
+    }
+
+    let mut this = items.remove(0);
+    normalize_expression_value(&mut this);
+    *payload = json!({
+        "this": this,
+        "not": false,
+        "postfix_form": false
+    });
+}
+
+fn normalize_struct_fields(map: &mut serde_json::Map<String, Value>) {
+    for (key, value) in map.iter_mut() {
+        if is_expression_array_field(key) {
+            if let Value::Array(items) = value {
+                for item in items {
+                    normalize_expression_value(item);
+                }
+                continue;
+            }
+        }
+
+        if is_expression_field(key) {
+            normalize_expression_value(value);
+        } else {
+            normalize_container_value(value);
+        }
+    }
+}
+
+fn normalize_container_value(value: &mut Value) {
+    match value {
+        Value::Object(map) => normalize_struct_fields(map),
+        Value::Array(items) => {
+            for item in items {
+                normalize_container_value(item);
+            }
+        }
+        _ => {}
+    }
+}
+
+fn is_expression_field(key: &str) -> bool {
+    matches!(
+        key,
+        "this"
+            | "left"
+            | "right"
+            | "low"
+            | "high"
+            | "expression"
+            | "condition"
+            | "query"
+            | "unnest"
+            | "on"
+            | "prewhere"
+            | "where"
+            | "where_clause"
+            | "having"
+            | "qualify"
+            | "source"
+            | "body"
+            | "default"
+            | "true_value"
+            | "false_value"
+            | "else_result"
+            | "target"
+            | "format"
+            | "limit"
+            | "offset"
+    )
+}
+
+fn is_expression_array_field(key: &str) -> bool {
+    matches!(
+        key,
+        "expressions"
+            | "args"
+            | "columns"
+            | "values"
+            | "partition_by"
+            | "order_by"
+            | "group_by"
+            | "distinct_on"
+            | "limit_by"
+            | "settings"
+            | "for_xml"
+            | "for_json"
+            | "exclude"
+            | "hints"
+            | "on_columns"
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::expressions::Expression;
+
+    fn column_json(name: &str) -> Value {
+        json!({
+            "column": {
+                "name": {
+                    "name": name,
+                    "quoted": false,
+                    "trailing_comments": [],
+                    "span": null
+                },
+                "table": null,
+                "join_mark": false,
+                "trailing_comments": [],
+                "span": null,
+                "inferred_type": null
+            }
+        })
+    }
+
+    #[test]
+    fn expression_from_value_accepts_legacy_empty_object_as_null() {
+        assert!(matches!(
+            expression_from_value(json!({})).expect("empty object should become NULL"),
+            Expression::Null(_)
+        ));
+    }
+
+    #[test]
+    fn expression_from_value_accepts_empty_null_payload() {
+        assert!(matches!(
+            expression_from_value(json!({ "null": {} })).expect("empty null payload should work"),
+            Expression::Null(_)
+        ));
+    }
+
+    #[test]
+    fn expression_from_value_repairs_nested_null_expression_fields() {
+        let expression = expression_from_value(json!({
+            "between": {
+                "this": column_json("created_at"),
+                "low": { "literal": { "literal_type": "string", "value": "2024-01-01" } },
+                "high": {},
+                "not": false,
+                "symmetric": null
+            }
+        }))
+        .expect("between high bound should be repaired");
+
+        match expression {
+            Expression::Between(between) => assert!(matches!(between.high, Expression::Null(_))),
+            other => panic!("expected between expression, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn expression_from_value_accepts_is_null_array_shorthand() {
+        let expression = expression_from_value(json!({
+            "is_null": [column_json("deleted_at")]
+        }))
+        .expect("is_null shorthand should be repaired");
+
+        match expression {
+            Expression::IsNull(is_null) => {
+                assert!(!is_null.not);
+                assert!(!is_null.postfix_form);
+                assert!(matches!(is_null.this, Expression::Column(_)));
+            }
+            other => panic!("expected is_null expression, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn expression_from_value_keeps_unknown_ast_as_error() {
+        let error = expression_from_value(json!({ "not_a_real_expression": {} }))
+            .expect_err("unknown expression should stay invalid");
+        assert!(error.contains("not_a_real_expression"));
+    }
+}