@polyglot-sql/sdk 0.5.2 → 0.5.4

package/README.md

@@ -347,9 +347,9 @@ Walk, search, and transform parsed AST nodes.
 
 ```typescript
 import {
-  parse, Dialect, walk, transform, findAll, findFirst, findByType,
+  parse, Dialect, col, walk, transform, findAll, findFirst, findByType,
   getColumns, getColumnNames, getTableNames, renameColumns, renameTables,
-  addWhere, removeWhere, setLimit, setDistinct, qualifyColumns,
+  addWhere, removeWhere, setLimit, setOffset, setOrderBy, setDistinct, qualifyColumns,
   getAggregateFunctions, hasSubqueries, nodeCount,
 } from '@polyglot-sql/sdk';
 
@@ -382,6 +382,8 @@ const qualified = qualifyColumns(ast, 'users');
 
 // Modify query structure
 const withLimit = setLimit(ast, 100);
+const withOffset = setOffset(withLimit, 10);
+const ordered = setOrderBy(withOffset, col('a').toJSON());
 const distinct = setDistinct(ast, true);
 const noWhere = removeWhere(ast);
 ```
@@ -608,30 +610,75 @@ lineage graph. `relations` contains sources visible in the analyzed scope;
 `baseTables` contains deduplicated physical dependencies across nested CTEs,
 derived tables, subqueries, and set-operation branches. With a schema,
 parseable detailed type strings such as `DECIMAL(10,2)` are preserved in
-projection `typeHint` values.
+projection `typeHint` values. `cteFacts` reports top-level CTE definitions,
+`starProjections` records original star projections and schema-expanded
+columns, and each projection includes conservative `nullability`: `'non_null'`,
+`'nullable'`, or `'unknown'`.
+For physical relation facts, `name` remains the qualified display name while
+`catalog`, `schema`, and `table` expose parsed identifier parts.
 
 ```typescript
 import { analyzeQuery, Dialect } from '@polyglot-sql/sdk';
 
-const result = analyzeQuery('SELECT SUM(o.amount) AS total FROM orders AS o', {
-  dialect: Dialect.Generic,
-  schema: {
-    tables: [
-      { name: 'orders', columns: [{ name: 'amount', type: 'DECIMAL(10,2)' }] },
-    ],
+const result = analyzeQuery(
+  'WITH base AS (SELECT id, amount FROM orders) SELECT * FROM base',
+  {
+    dialect: Dialect.Generic,
+    schema: {
+      tables: [
+        {
+          name: 'orders',
+          columns: [
+            { name: 'id', type: 'INT', nullable: false },
+            { name: 'amount', type: 'DECIMAL(10,2)', nullable: true },
+          ],
+        },
+      ],
+    },
   },
-});
+);
 
 if (result.success) {
-  console.log(result.analysis.projections[0].transformKind); // 'aggregation'
-  console.log(result.analysis.projections[0].typeHint);      // 'DECIMAL(10, 2)'
-  console.log(result.analysis.baseTables[0].name);           // 'orders'
-  console.log(result.analysis.baseTables[0].alias);          // 'o'
+  console.log(result.analysis.cteFacts[0].bodySql);                // 'SELECT id, amount FROM orders'
+  console.log(result.analysis.starProjections[0].expandedColumns); // ['id', 'amount']
+  console.log(result.analysis.projections[0].nullability);         // 'non_null'
+  console.log(result.analysis.baseTables[0].name);                 // 'orders'
+  console.log(result.analysis.baseTables[0].table);                // 'orders'
 }
 
 const duckdbSummary = analyzeQuery('SELECT 1', Dialect.DuckDB);
 ```
 
+`ValidationSchema` objects use this shape:
+
+```typescript
+const 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.
+
 ## OpenLineage Output
 
 Generate OpenLineage-compatible JSON payloads from SQL analysis. The SDK only
@@ -838,6 +885,7 @@ const formattedSafe = pg.formatWithOptions('SELECT a,b FROM t', Dialect.Generic,
 | `removeSelectColumns(node, predicate)` | Remove columns from SELECT |
 | `setLimit(node, limit)` | Set LIMIT clause |
 | `setOffset(node, offset)` | Set OFFSET clause |
+| `setOrderBy(node, orderBy)` | Set ORDER BY clause |
 | `removeLimitOffset(node)` | Remove LIMIT and OFFSET |
 | `setDistinct(node, distinct?)` | Set SELECT DISTINCT |
 | `clone(node)` | Deep clone AST |