@polyglot-sql/sdk 0.5.1 → 0.5.3

package/README.md

@@ -604,26 +604,76 @@ are marked as `virtual`.
 ## Compact Query Analysis
 
 Use `analyzeQuery` when you need summary facts instead of the full AST or full
-lineage graph:
+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. `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'`.
 
 ```typescript
 import { analyzeQuery, Dialect } from '@polyglot-sql/sdk';
 
-const result = analyzeQuery('SELECT CAST(total AS TEXT) AS total_text FROM orders', {
-  dialect: Dialect.Generic,
-  schema: {
-    tables: [
-      { name: 'orders', columns: [{ name: 'total', type: 'INT' }] },
-    ],
+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); // 'cast'
-  console.log(result.analysis.relations[0].name);            // 'orders'
+  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'
 }
+
+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
@@ -743,7 +793,7 @@ const formattedSafe = pg.formatWithOptions('SELECT a,b FROM t', Dialect.Generic,
 | `lineage(column, sql, dialect?, trimSelects?)` | Trace column lineage through a query |
 | `lineageWithSchema(column, sql, schema, dialect?, trimSelects?)` | Trace lineage with schema-based qualification |
 | `getSourceTables(column, sql, dialect?)` | Get source tables for a column |
-| `analyzeQuery(sql, options?)` | Return compact projection, relation, CTE, set-operation, and upstream-reference facts |
+| `analyzeQuery(sql, optionsOrDialect?)` | Return compact projection, visible relation, transitive base-table, CTE, set-operation, and upstream-reference facts |
 | `openLineageColumnLineage(sql, options)` | Build an OpenLineage columnLineage facet and datasets |
 | `openLineageJobEvent(sql, options)` | Build an OpenLineage JobEvent payload |
 | `openLineageRunEvent(sql, options)` | Build an OpenLineage RunEvent payload |