{"id":29039377,"url":"https://github.com/0x1000000/sqexpress","last_synced_at":"2026-04-02T20:45:57.347Z","repository":{"id":50150229,"uuid":"303515449","full_name":"0x1000000/SqExpress","owner":"0x1000000","description":"SqExpress is a sql query builder which allows creating SQL expressions directly in C# code with strong typing and intellisense.","archived":false,"fork":false,"pushed_at":"2024-09-17T13:23:44.000Z","size":1130,"stargazers_count":105,"open_issues_count":1,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-26T14:02:09.977Z","etag":null,"topics":["data-access","ms-sql","mysql","postgres-sql","sql-builder"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0x1000000.png","metadata":{"files":{"readme":"Readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"Roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-12T21:18:43.000Z","updated_at":"2025-06-09T21:01:25.000Z","dependencies_parsed_at":"2023-02-08T16:31:34.118Z","dependency_job_id":"3ffe033d-c4af-4afc-9b68-12ec8a981f8e","html_url":"https://github.com/0x1000000/SqExpress","commit_stats":{"total_commits":93,"total_committers":2,"mean_commits":46.5,"dds":"0.010752688172043001","last_synced_commit":"dc0c710666ce9eefa588cdb079173c14d39bfdfe"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/0x1000000/SqExpress","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x1000000%2FSqExpress","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x1000000%2FSqExpress/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x1000000%2FSqExpress/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x1000000%2FSqExpress/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0x1000000","download_url":"https://codeload.github.com/0x1000000/SqExpress/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0x1000000%2FSqExpress/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262081079,"owners_count":23255658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-access","ms-sql","mysql","postgres-sql","sql-builder"],"created_at":"2025-06-26T14:02:01.483Z","updated_at":"2026-04-02T20:45:57.333Z","avatar_url":"https://github.com/0x1000000.png","language":"C#","readme":"# SqExpress\n\n![Logo](https://github.com/0x1000000/SqExpress/blob/main/SqExpress/Icon.png)\nFor those who like SQL but hate raw strings.\n\nThe library provides a generic SQL syntax tree with export to MS T-SQL, PostgreSQL, and MySQL text. It includes polyfills to compensate for features lacking in certain databases, such as the \"MERGE\" command. It also provides a set of builders and operators that will help you build complex SQL expressions. It also includes a T-SQL parser (`SqTSqlParser`) for converting existing SQL text into SqExpress AST.\n\nIt does not use LINQ, and your C# code will be as close to real SQL as possible. This makes it ideal when you need full SQL flexibility to create efficient DB requests.\n\nSqExpress comes with a simple but efficient data access mechanism that wraps ADO.Net DbConnection and can be used with MS SQL Client, Npgsql, or MySQL Connector.\n\nYou can use SqExpress together with the \"Code First\" concept when you declare SQL tables as C# classes with the possibility to generate recreation scripts for a target platform (MS SQL or PostgreSQL or MySQL).\n\nYou can also use it in conjunction with the \"Database First\" concept using an included code modification utility. The utility can also be used to generate flexible DTO classes with all required database mappings.\n\nSqExpress is also a strong fit when SQL is produced dynamically, including by AI agents. Because SQL can be parsed into the SqExpress AST, validated against an allowed table model, traversed, rewritten with additional security predicates, and exported back to SQL, SqExpress can act as a fail-closed safety layer for AI-generated T-SQL within the supported parser surface.\n\n# Content\n\n### Resources\n\n1. [Video Tutorials](#video-tutorials)\n2. [Articles](#articles)\n3. [T-SQL to SqExpress Transpiler (Web Tool) **NEW!!!**](#t-sql-to-sqexpress-transpiler-web-tool)\n4. [Demo Application](#demo-application)\n\n### Intro\n\n1. [Get Started](#get-started)\n2. [When to Use SqExpress (and When Not)](#when-to-use-sqexpress-and-when-not)\n\n### Basics\n\n1. [Creating Table Descriptors](#creating-table-descriptors)\n2. [Inserting Data](#inserting-data)\n3. [Selecting Data](#selecting-data)\n4. [Updating Data](#updating-data)\n5. [Deleting Data](#deleting-data)\n6. [More Tables and foreign keys](#more-tables-and-foreign-keys)\n7. [Data Selection](#data-selection)\n8. [Joining Tables](#joining-tables)\n9. [Aliasing](#aliasing)\n10. [Derived Tables](#derived-tables)\n11. [Subqueries](#subqueries)\n12. [CTE](#cte)\n13. [Analytic And Window Functions](#analytic-and-window-functions)\n14. [Set Operators](#set-operators)\n\n### Advanced Data Modification\n\n1. [Merge](#merge)\n2. [Temporary Tables](#temporary-tables)\n3. [Database Data Export/Import](#database-data-export-import)\n4. [Getting and Comparing Database Table Metadata](#getting-and-comparing-database-table-metadata)\n\n### Database Table Metadata\n\n1. [Retrieving Database Table Metadata](#retrieving-database-table-metadata)\n2. [Navigating Table References with TablesGraph](#navigating-table-references-with-tablesgraph)\n\n### Working with Expressions\n\n1. [T-SQL Parser (SqTSqlParser)](#t-sql-parser-sqtsqlparser)\n2. [Syntax Tree](#syntax-tree) (Traversal and Modification)\n3. [Serialization to XML](#serialization-to-xml)\n4. [Serialization to JSON](#serialization-to-json)\n5. [Serialization to Plain List](#serialization-to-plain-list)\n\n### Code-generation\n\n1. [Table Descriptors Scaffolding](#table-descriptors-scaffolding)\n2. [DTOs Scaffolding](#dtos-scaffolding)\n3. [Model Selection](#model-selection)\n\n### Usage\n\n1. [Parametrization Modes](#parametrization-modes)\n2. [Using in ASP.NET](#using-in-aspnet)\n3. [PostgreSQL](#postgresql)\n4. [MySQL](#mysql)\n5. [AutoMapper](#automapper)\n\n---\n---\n\n\n# Video Tutorials\n\n1. [Basics of SqExpress](https://www.youtube.com/watch?v=Zd-fCb8NimA)\n2. [Working with Database Metadata Using SqExpress](https://youtu.be/vGVpTCt4aqc?si=AWK8GzvoiVlX7vET)\n\n# Articles\n\n1. [\"Syntax Tree and Alternative to LINQ in Interaction with SQL Databases\"](https://itnext.io/syntax-tree-and-alternative-to-linq-in-interaction-with-sql-databases-656b78fe00dc?source=friends_link\u0026sk=f5f0587c08166d8824b96b48fe2cf33c) - explains the library principles;\n2. [\"Filtering by Dynamic Attributes\"](https://itnext.io/filtering-by-dynamic-attributes-90ada3504361?source=friends_link\u0026sk=35e273a9f499e6b62bacbac75873a7d2) - shows how to create dynamic queries using the library.\n\n# T-SQL to SqExpress Transpiler (Web Tool)\n\nSqExpress includes a dedicated transpiler tool that converts T-SQL into ready-to-use SqExpress C# code:\n\n- **Open the tool**: [https://0x1000000.github.io/SqExpress/](https://0x1000000.github.io/SqExpress/)\n\nWhy this tool is important:\n\n- It significantly reduces migration time from raw SQL or old stored-query code to SqExpress.\n- It generates both query code and declaration code (table descriptors and generated query helpers) so users can start from working scaffolding instead of a blank file.\n- It helps teams keep SQL-first workflows while still getting strongly typed C# output.\n\nHow to use it effectively:\n\n- Paste T-SQL into the editor.\n- Review generated query code and descriptor code.\n- Adjust naming/options (descriptor prefix/suffix, default schema, static builder usage) from the option bar.\n- For best type accuracy, pair transpiled output with the SqExpress table descriptor scaffolding workflow.\n\nThe tool runs entirely in the browser (WebAssembly). Your SQL is processed client-side.\n\n# Demo Application\n\nYou can find a realistic usage of the library in this AI-driven demo application - [SqDbAiAgent](https://github.com/0x1000000/SqDbAiAgent).\n\n`SqDbAiAgent` shows how SqExpress can act as a fail-closed safety layer for AI-generated T-SQL: the SQL is parsed, validated against the allowed schema, optionally rewritten with security predicates, and only then executed against SQL Server.\n\n# Get Started\n\nAdd a reference to [the library package on Nuget.org](https://www.nuget.org/packages/SqExpress/):\n\n```\nInstall-Package SqExpress\n```\n\nand start with \"Hello World\":\n\n```cs\nstatic void Main()\n{\n    var query = SqQueryBuilder.Select(\"Hello World!\").Done();\n\n    Console.WriteLine(query.ToSql(TSqlExporter.Default));\n}\n```\n\nThe result will be:\n\n```sql\nSELECT 'Hello World!'\n```\n\nTo avoid repeating **\"SqQueryBuilder.\"**, add:\n\n```cs\nusing static SqExpress.SqQueryBuilder;\n...\n    var query = /*SqQueryBuilder.*/Select(\"Hello World!\").Done();\n\n    Console.WriteLine(query.ToSql(TSqlExporter.Default));\n\n```\n\nAs a second quick example, you can parse existing T-SQL and then modify/export it:\n\n```cs\nstatic void Main()\n{\n    var expr = SqTSqlParser.Parse(\"SELECT 'Hi,' + @userName + '!'\", [])\n        .WithParams((\"userName\", \"John\"))\n        .AsQuery();\n\n    Console.WriteLine(expr.ToSql(TSqlExporter.Default));\n}\n```\n\nThe result will be:\n\n```sql\nSELECT 'Hi,'+'John'+'!'\n```\n\n*Note: SqExpress supports quite sophisticated queries, but it does not aim to cover the full T-SQL language. Because SqExpress is designed to stay database-agnostic, the parser focuses on broadly portable SQL constructs and intentionally supports only a fail-closed subset of T-SQL.*\n\nSqExpress also includes a built-in Roslyn analyzer for `SqTSqlParser.Parse(...)`. It validates raw SQL and checks referenced tables against discovered SqExpress descriptors, but when possible it is better to use the `Convert SQL to SqExpress` code fix and replace raw SQL with generated C#.\n\nFor an overview of the expression hierarchy behind SqExpress syntax nodes, see [AST Reference](Documentation/ast_reference.md).\n\n*Note: If your query references real tables, make sure the corresponding table descriptors already exist in your codebase, either handwritten or generated with [the table descriptors scaffolding tool](#table-descriptors-scaffolding). The analyzer relies on those descriptors and will report errors if the referenced tables cannot be resolved.*\n\n![Convert SQL to SqExpress](sql-to-sqexpress.gif)\n\nAnd finally, here is how to execute the query against SQL Server:\n\n```cs\nstatic async Task Main()\n{\n    var database = new SqDatabase\u003cSqlConnection\u003e(\n        new SqlConnection(\"Server=(local);Database=master;Integrated Security=True;TrustServerCertificate=True\"),\n        (connection, sqlText) =\u003e new SqlCommand(sqlText, connection),\n        TSqlExporter.Default /*Expressions will be converted to MS T-SQL*/,\n        ParametrizationMode.LiteralFallback /*Literals will be passed as parameters*/);\n\n    var userName = \"John\";\n\n    var result = (await Select(Literal(\"Hi,\") + userName + \"!\").QueryScalar(database))?.ToString();\n\n    Console.WriteLine(result);\n}\n```\n\nThe code executed by the MS SQL:\n\n```sql\nexec sp_executesql N'SELECT (@1)+(@2)+(@3)',N'@1 nvarchar(3),@2 nvarchar(4),@3 nvarchar(1)',@1=N'Hi,',@2=N'John',@3=N'!'\n```\n\n## When to Use SqExpress (and When Not)\n\nIf your project is SQL-heavy, SqExpress is usually the strongest choice.\n\nUse SqExpress when:\n\n- SQL is core to your business logic, not just persistence plumbing.\n- You need complex queries (CTE, window functions, set operations, MERGE-style workflows).\n- You want code to stay close to SQL while still getting strong typing and IntelliSense.\n- You want table descriptors, metadata comparison, and code generation in one workflow.\n- You need one query model that can export to MS SQL, PostgreSQL, and MySQL.\n\nSqExpress shines the most in two areas:\n\n1. **Reports and analytics**: dynamic SQL generation with access to native SQL features (analytic/window functions, CTEs, set operators, db-specific functions).\n2. **Mass updates/upserts**: large set-based data modification with `MERGE` semantics, including cross-dialect polyfills where native `MERGE` is unavailable.\n\n### SqExpress vs Entity Framework (EF Core)\n\nChoose **SqExpress** when:\n\n- You treat the database as a relational engine and optimize for set-based queries.\n- You care more about precise SQL shape than ORM abstractions.\n- You want full control over joins, projections, and query patterns.\n- Your bottlenecks are in query quality and SQL execution plans.\n- You need reporting queries that rely on native analytic/window functions and db-specific SQL features.\n- You need large set-based write workflows (upsert/sync) and dynamic SQL composition as first-class capabilities.\n- You need more flexibility than EF Core batch APIs for complex set-based writes (`UpdateData`, `MergeDataInto`, custom mappings, sync/upsert flows).\n\nChoose **EF Core** when:\n\n- You model your domain mainly as object graphs and treat the database primarily as persistence storage.\n- Your app is mostly CRUD with rich domain graph tracking.\n- You want unit-of-work/change tracking as the primary model.\n- Your set-based writes are relatively simple and are well covered by `ExecuteUpdate` / `ExecuteDelete`.\n\n### SqExpress vs SqlKata\n\nChoose **SqExpress** when:\n\n- You want a strongly typed SQL model (tables/columns as C# types), not mostly string-based query composition.\n- You need expression tree traversal/modification and deeper SQL tooling.\n- You want long-term maintainability in large SQL codebases.\n- You need robust dynamic query scenarios and `MERGE`-oriented update pipelines.\n\nChoose **SqlKata** when:\n\n- You prefer a lightweight fluent builder with minimal upfront structure.\n\n### SqExpress vs Dapper\n\nChoose **SqExpress** when:\n\n- You want SQL power without maintaining large amounts of raw SQL strings.\n- You want compile-time help for schema-level refactoring.\n- You want higher-level SQL composition, metadata tooling, and codegen.\n- You need expressive set-based update/upsert logic and reusable dynamic query builders.\n\nChoose **Dapper** when:\n\n- You prefer manual SQL strings and the thinnest possible data access layer.\n\n### SqExpress vs linq2db\n\nChoose **SqExpress** when:\n\n- Your team thinks in SQL first and prefers SQL-like C# over LINQ translation.\n- You want explicit SQL control and predictable output for every query.\n- You need to build/transform dynamic SQL expression trees and run large set-based data modifications.\n\nChoose **linq2db** when:\n\n- Your team prefers LINQ as the primary way of writing queries.\n\n### When Not to Use SqExpress\n\nSqExpress is not the best default if:\n\n- Your project is mostly simple CRUD and low SQL complexity.\n- Your team is not comfortable owning SQL design decisions.\n- You primarily want full ORM behavior (tracked entities, relationship graph lifecycle, etc.).\n- You treat the database mainly as an object store, rather than a relational engine for set-based facts and queries.\n\n### Rule of Thumb\n\nIf SQL is strategic in your system, SqExpress gives you the most leverage.  \nIf SQL is incidental, a higher-level ORM can be simpler.\n\n## Creating Table Descriptors\n\nNext, let's select some data from a real table, but first we need to describe the table.\n\nThe recommended way is to declare the table with attributes and let the built-in source generator produce the `TableBase` implementation for you:\n\nFor the full attribute reference, see [Table Description Reference](Documentation/table_description.md).\n\n```cs\nusing SqExpress.TableDeclarationAttributes;\n\n[TableDescriptor(\"dbo\", \"User\")]\n[Int32Column(\"UserId\", Pk = true, Identity = true)]\n[StringColumn(\"FirstName\", Unicode = true, MaxLength = 255)]\n[StringColumn(\"LastName\", Unicode = true, MaxLength = 255)]\n[Int32Column(\"Version\", DefaultValue = \"0\")]\n[DateTimeColumn(\"ModifiedAt\", DefaultValue = \"$utcNow\")]\n[Index(\"FirstName\")]\n[Index(\"LastName\")]\npublic partial class TableUser\n{\n}\n```\n\n*Note: Such classes can be auto-generated (and later updated) using information from an existing database. [See \"Table Descriptors Scaffolding\"](#table-descriptors-scaffolding)*\n\nPackage Manager Console:\n\n```powershell\nGen-Tables mssql -ConnectionString \"Server=(local);Database=YourDatabase;Integrated Security=True;TrustServerCertificate=True\" -UseTableDeclarationAttributes\n```\n\n*Note: Handwritten `TableBase` descriptors are still supported, but attribute-based declarations are now the recommended default.*\n\nIf the table does not exist yet, create it first:\n\n```cs\nstatic async Task Main()\n{\n    using var connection = new SqlConnection(\"connection_string\");\n    {\n        using (var database = new SqDatabase\u003cSqlConnection\u003e(\n            connection: connection,\n            commandFactory: (conn, sql) \n                =\u003e new SqlCommand(cmdText: sql, connection: conn),\n            sqlExporter: TSqlExporter.Default,\n            parametrizationMode: ParametrizationMode.LiteralFallback))\n        {\n            var tUser = new TableUser();\n\n            await database.Statement(tUser.Script.DropAndCreate());\n        }\n    }\n}\n```\n\n*Note: See [PostgreSQL](#postgresql) or [MySQL](#mysql)* sections if you need to work with these databases.\n\n*Actual T-SQL:*\n\n```sql\n\nIF EXISTS\n(\n    SELECT TOP 1 1 \n    FROM [INFORMATION_SCHEMA].[TABLES] \n    WHERE [TABLE_SCHEMA]='dbo' AND [TABLE_NAME]='User'\n) \n    DROP TABLE [dbo].[User];\n\nCREATE TABLE [dbo].[User]\n(\n    [UserId] int NOT NULL  IDENTITY (1, 1),\n    [FirstName] [nvarchar](255) NOT NULL,\n    [LastName] [nvarchar](255) NOT NULL,\n    [Version] int NOT NULL,\n    [ModifiedAt] datetime NOT NULL,\n    CONSTRAINT [PK_dbo_User] PRIMARY KEY ([UserId])\n);\n```\n\n## Inserting Data\n\nNow it is time to insert some data into the table:\n\n```cs\n...\nvar data = new[]\n{\n    new {FirstName = \"Francois\", LastName = \"Sturman\"},\n    new {FirstName = \"Allina\", LastName = \"Freeborne\"},\n    new {FirstName = \"Maye\", LastName = \"Maloy\"},\n};\n\nawait /*SqQueryBuilder.*/InsertDataInto(tUser, data)\n    .MapData(s =\u003e s\n        .Set(s.Target.FirstName, s.Source.FirstName)\n        .Set(s.Target.LastName, s.Source.LastName))\n    .AlsoInsert(s =\u003e s\n        .Set(s.Target.Version, 1)\n        .Set(s.Target.ModifiedAt, GetUtcDate()))\n    .Exec(database);\n...\n```\n\n*Actual T-SQL:*\n\n```sql\nINSERT INTO [dbo].[User]([FirstName],[LastName],[Version],[ModifiedAt]) \nSELECT [FirstName],[LastName],1,GETUTCDATE() \nFROM \n(VALUES \n    ('Francois','Sturman'),\n    ('Allina','Freeborne')\n    ,('Maye','Maloy')\n)[A0]([FirstName],[LastName])\n```\n\n## Selecting data\n\nand select it:\n\n```cs\nvar selectResult = await /*SqQueryBuilder.*/Select(tUser.UserId, tUser.FirstName, tUser.LastName)\n    .From(tUser)\n    .OrderBy(tUser.FirstName, tUser.LastName)\n    .QueryList(database,\n        r =\u003e (\n            Id: tUser.UserId.Read(r),\n            FirstName: tUser.FirstName.Read(r),\n            LastName: tUser.LastName.Read(r)));\nforeach (var record in selectResult)\n{\n    Console.WriteLine(record);\n}\n```\n\n*Actual T-SQL:*\n\n```sql\nSELECT [A0].[UserId],[A0].[FirstName],[A0].[LastName] \nFROM [dbo].[User] [A0] \nORDER BY [A0].[FirstName],[A0].[LastName]\n```\n\n*Result:*\n\n```\n(2, Allina, Freeborne)\n(1, Francois, Sturman)\n(3, Maye, Maloy)\n```\n\n## Updating data\n\nNow let's fix the typo:\n\n```cs\nawait /*SqQueryBuilder.*/Update(tUser)\n    .Set(tUser.LastName, \"Malloy\")\n    .Set(tUser.Version, tUser.Version+1)\n    .Set(tUser.ModifiedAt, GetUtcDate())\n    .Where(tUser.LastName == \"Maloy\")\n    .Exec(database);\n\n//Writing to console without storing data in memory\nawait /*SqQueryBuilder.*/Select(tUser.Columns)\n    .From(tUser)\n    .Query(database, record=\u003e\n    {\n        Console.Write(tUser.UserId.Read(record) + \",\");\n        Console.Write(tUser.FirstName.Read(record) + \" \");\n        Console.Write(tUser.LastName.Read(record) + \",\");\n        Console.Write(tUser.Version.Read(record) + \",\");\n        Console.WriteLine(tUser.ModifiedAt.Read(record).ToString(\"s\"));\n        return agg;\n    });\n```\n\n*Actual T-SQL:*\n\n```sql\nUPDATE [A0] SET \n    [A0].[LastName]='Malloy',\n    [A0].[Version]=[A0].[Version]+1,\n    [A0].[ModifiedAt]=GETUTCDATE() \nFROM [dbo].[User] [A0] \nWHERE [A0].[LastName]='Maloy'```\n```\n\n*Result:*\n\n```\n1,Francois Sturman,1,2020-10-12T11:32:16\n2,Allina Freeborne,1,2020-10-12T11:32:16\n3,Maye Malloy,2,2020-10-12T11:32:17\n```\n\n*Note: In addition to **Update** the library also has **Insert** and **IdentityInsert** helpers (see [Database Data Export/Import](#database-data-export-import) to find an example)*\n\n## Deleting data\n\nUnfortunately, regardless the fact the typo is fixed, we have to say \"Good Bye\" to May*:\n\n```cs\nawait /*SqQueryBuilder.*/Delete(tUser)\n    .Where(tUser.FirstName.Like(\"May%\"))\n    .Output(tUser.UserId)\n    .Query(database, (record)=\u003e\n    {\n        Console.WriteLine(\"Removed user id: \" + tUser.UserId.Read(record));\n    });\n```\n\n*Actual T-SQL:*\n\n```sql\nDELETE [A0] \nOUTPUT DELETED.[UserId] \nFROM [dbo].[User] [A0] \nWHERE [A0].[FirstName] LIKE 'May%'\n```\n\n*Result:*\n\n```\nRemoved user id: 3\n```\n\n## More Tables and foreign keys\n\nMore complex queries usually need more than one table. Let's add a couple more:\n\n*dbo.Company*\n\n```cs\nusing SqExpress.TableDeclarationAttributes;\n\n[TableDescriptor(\"dbo\", \"Company\")]\n[Int32Column(\"CompanyId\", Pk = true, Identity = true)]\n[StringColumn(\"CompanyName\", MaxLength = 250)]\n[Int32Column(\"Version\", DefaultValue = \"0\")]\n[DateTimeColumn(\"ModifiedAt\", DefaultValue = \"$utcNow\")]\npublic partial class TableCompany;\n```\n\n*dbo.Customer*\n\n```cs\nusing SqExpress.TableDeclarationAttributes;\n\n[TableDescriptor(\"dbo\", \"Customer\")]\n[Int32Column(\"CustomerId\", Pk = true, Identity = true)]\n[NullableInt32Column(\"UserId\", FkTable = \"User\", FkColumn = \"UserId\")]\n[NullableInt32Column(\"CompanyId\", FkTable = \"Company\", FkColumn = \"CompanyId\")]\n[Index(\"UserId\", \"CompanyId\", Unique = true)]\n[Index(\"CompanyId\", \"UserId\", Unique = true)]\npublic partial class TableCustomer;\n```\n\nPay attention to how the foreign keys are defined:\n\n```cs\n[NullableInt32Column(\"UserId\", FkTable = \"User\", FkColumn = \"UserId\")]\n```\n\nAnd indexes:\n\n```cs\n[Index(\"UserId\", \"CompanyId\", Unique = true)]\n[Index(\"CompanyId\", \"UserId\", Unique = true)]\n```\n\nNow that we have foreign keys, the tables must be dropped and created in a specific order:\n\n```cs\nvar tables = new TableBase[]{ new TableUser() , new TableCompany(), new TableCustomer() };\n\nforeach (var table in tables.Reverse())\n{\n    await database.Statement(table.Script.DropIfExist());\n}\nforeach (var table in tables)\n{\n    await database.Statement(table.Script.Create());\n}\n```\n\nNow we can insert a few companies:\n\n```cs\nvar tCompany = new TableCompany();\n\nConsole.WriteLine(\"Companies:\");\n\nawait /*SqQueryBuilder.*/InsertDataInto(tCompany, new[] {\"Microsoft\", \"Google\"})\n    .MapData(s =\u003e s.Set(s.Target.CompanyName, s.Source))\n    .AlsoInsert(s =\u003e s\n        .Set(s.Target.Version, 1)\n        .Set(s.Target.ModifiedAt, GetUtcDate()))\n    .Output(tCompany.CompanyId, tCompany.CompanyName)\n    .Query(database, (r) =\u003e\n    {\n        Console.WriteLine($\"Id: {tCompany.CompanyId.Read(r)}, Name: {tCompany.CompanyName.Read(r)}\");\n    });\n```\n\nand create \"Customers\":\n\n```cs\nvar tUser = new TableUser();\nvar tCompany = new TableCompany();\nvar tCustomer = new TableCustomer();\nvar tSubCustomer = new TableCustomer();\n\n//Users\nawait /*SqQueryBuilder.*/InsertInto(tCustomer, tCustomer.UserId)\n    .From(\n        Select(tUser.UserId)\n            .From(tUser)\n            .Where(!Exists(\n                SelectOne()\n                    .From(tSubCustomer)\n                    .Where(tSubCustomer.UserId == tUser.UserId))))\n    .Exec(database);\n\n//Companies\nawait InsertInto(tCustomer, tCustomer.CompanyId)\n    .From(\n        Select(tCompany.CompanyId)\n            .From(tCompany)\n            .Where(!Exists(\n                SelectOne()\n                    .From(tSubCustomer)\n                    .Where(tSubCustomer.CompanyId == tCompany.CompanyId))))\n    .Exec(database);\n```\n\n*Actual T-SQL:*\n\n```sql\nINSERT INTO [dbo].[Customer]([UserId]) \nSELECT [A0].[UserId] \nFROM [dbo].[User] [A0] WHERE NOT EXISTS\n(\n    SELECT 1 \n    FROM [dbo].[Customer] [A1] \n    WHERE [A1].[UserId]=[A0].[UserId]\n)\n\nINSERT INTO [dbo].[Customer]([CompanyId]) \nSELECT [A0].[CompanyId] \nFROM [dbo].[Company] [A0] \nWHERE NOT EXISTS(\n    SELECT 1 FROM [dbo].[Customer] [A1] \n    WHERE [A1].[CompanyId]=[A0].[CompanyId]\n)\n```\n\n_Note: SqExpress actively uses operator overloads. Therefore, operators \u003e, \u003e=, \u003c, \u003c=, ==, \u0026, |, !, /, +, -, *, and % are overloaded when applied to SqExpress syntax nodes, resulting in new syntax nodes.*\n\n# Data Selection\n\nThis chapter moves from straightforward reads to the query patterns that usually define real production workloads.\nHere, SqExpress shows its full power: composable joins, derived tables, subqueries, CTEs, analytic functions, and set operators.\nThe section walks step by step through `Joining Tables`, `Aliasing`, `Derived Tables`, `Subqueries`, `CTE`, `Analytic And Window Functions`, and `Set Operators`.\nEach example is designed to keep intent obvious in C# while preserving tight control over the resulting SQL shape.\nUse these patterns when query complexity, performance tuning, and long-term maintainability matter.\n\n## Joining Tables\n\nNow we can join all the tables:\n\n```cs\nvar tUser = new TableUser();\nvar tCompany = new TableCompany();\nvar tCustomer = new TableCustomer();\n\nvar cType = CustomColumnFactory.Int16(\"Type\");\nvar cName = CustomColumnFactory.String(\"Name\");\n\nvar customers = await /*SqQueryBuilder.*/Select(\n        tCustomer.CustomerId,\n        /*SqQueryBuilder.*/Case()\n            .When(IsNotNull(tUser.UserId))\n            .Then(Cast(Literal(1), SqlType.Int16))\n            .When(IsNotNull(tCompany.CompanyId))\n            .Then(Cast(Literal(2), SqlType.Int16))\n            .Else(Null)\n            .As(cType),\n        /*SqQueryBuilder.*/Case()\n            .When(IsNotNull(tUser.UserId))\n            .Then(tUser.FirstName + \" \" + tUser.LastName)\n            .When(IsNotNull(tCompany.CompanyId))\n            .Then(tCompany.CompanyName)\n            .Else(Null)\n            .As(cName)\n    )\n    .From(tCustomer)\n    .LeftJoin(tUser, on: tUser.UserId == tCustomer.UserId)\n    .LeftJoin(tCompany, on: tCompany.CompanyId == tCustomer.CompanyId)\n    .QueryList(database,\n        r =\u003e (Id: tCustomer.CustomerId.Read(r), CustomerType: cType.Read(r), Name: cName.Read(r)));\n\nforeach (var customer in customers)\n{\n    Console.WriteLine($\"Id: {customer.Id}, Name: {customer.Name}, Type: {customer.CustomerType}\");\n}\n```\n\n*Actual T-SQL:*\n\n```sql\nSELECT \n    [A0].[CustomerId],\n    CASE \n        WHEN [A1].[UserId] IS NOT NULL \n        THEN CAST(1 AS smallint) \n        WHEN [A2].[CompanyId] IS NOT NULL \n        THEN CAST(2 AS smallint) \n        ELSE NULL END \n    [Type],\n    CASE \n        WHEN [A1].[UserId] IS NOT NULL \n        THEN [A1].[FirstName]+' '+[A1].[LastName] \n        WHEN [A2].[CompanyId] IS NOT NULL \n        THEN [A2].[CompanyName] \n        ELSE NULL END \n    [Name] \nFROM [dbo].[Customer] [A0] \nLEFT JOIN [dbo].[User] [A1] \n    ON [A1].[UserId]=[A0].[UserId] \nLEFT JOIN [dbo].[Company] [A2] \n    ON [A2].[CompanyId]=[A0].[CompanyId]\n```\n\n*Result:*\n\n```\nId: 1, Name: Francois Sturman, Type: 1\nId: 2, Name: Allina Freeborne, Type: 1\nId: 3, Name: Microsoft, Type: 2\nId: 4, Name: Google, Type: 2\n```\n\n## Aliasing\n\nEvery time you create a table object, it is associated by default with an alias that will be used wherever you refer to the table. Each new instance will use a new alias. However you can explicitly specify your own alias or omit it:\n\n```cs\nvar tUser = new User(\"USR\");\nvar tUserNoAlias = new User(Alias.Empty);\n\nSelect(tUser.UserId).From(tUser);\nSelect(tUserNoAlias.UserId).From(tUserNoAlias);\n```\n\n*Actual T-SQL:*\n\n```sql\n--var tUser = new User(\"USR\");\nSELECT [USR].[UserId] FROM [dbo].[user] [USR]\n\n--var tUserNoAlias = new User(Alias.Empty);\nSELECT [UserId] FROM [dbo].[user]\n```\n\n## Derived Tables\n\nThe previous query is quite complex so it makes sense to store it as a derived table and reuse it in future:\n\n```cs\npublic class DerivedTableCustomer : DerivedTableBase\n{\n    public readonly Int32CustomColumn CustomerId;\n\n    public readonly Int16CustomColumn Type;\n\n    public readonly StringCustomColumn Name;\n\n    public DerivedTableCustomer(Alias alias = default) : base(alias)\n    {\n        this.CustomerId = this.CreateInt32Column(\"CustomerId\");\n        this.Type = this.CreateInt16Column(\"Type\");\n        this.Name = this.CreateStringColumn(\"Name\");\n    }\n\n    protected override IExprSubQuery CreateQuery()\n    {\n        var tUser = new TableUser();\n        var tCompany = new TableCompany();\n        var tCustomer = new TableCustomer();\n\n        return /*SqQueryBuilder.*/Select(\n                tCustomer.CustomerId.As(this.CustomerId),\n                /*SqQueryBuilder.*/Case()\n                    .When(IsNotNull(tUser.UserId))\n                    .Then(Cast(Literal(1), SqlType.Int16))\n                    .When(IsNotNull(tCompany.CompanyId))\n                    .Then(Cast(Literal(2), SqlType.Int16))\n                    .Else(Null)\n                    .As(this.Type),\n                /*SqQueryBuilder.*/Case()\n                    .When(IsNotNull(tUser.UserId))\n                    .Then(tUser.FirstName + \" \" + tUser.LastName)\n                    .When(IsNotNull(tCompany.CompanyId))\n                    .Then(tCompany.CompanyName)\n                    .Else(Null)\n                    .As(this.Name)\n            )\n            .From(tCustomer)\n            .LeftJoin(tUser, on: tUser.UserId == tCustomer.UserId)\n            .LeftJoin(tCompany, on: tCompany.CompanyId == tCustomer.CompanyId)\n            .Done();\n    }\n}\n```\n\n*Alternatively, derived tables can also be declared with `[DerivedTableDescriptor]` and `Derived...Column` attributes when you prefer descriptor-style declarations:*\n\n```cs\n[DerivedTableDescriptor(SqModel = \"CustomerData\")]\n[DerivedInt32Column(\"CustomerId\", SqModels = \"CustomerData.Id\")]\n[DerivedInt16Column(\"Type\", SqModels = \"CustomerData.CustomerType\")]\n[DerivedStringColumn(\"Name\")]\npublic partial class DerivedTableCustomer\n{\n    protected override IExprSubQuery CreateQuery()\n    {\n        // same query body as above\n    }\n}\n```\n\nand this is how it can be reused:\n\n```cs\nvar tCustomer = new DerivedTableCustomer(\"CUST\");\n\nvar customers = await /*SqQueryBuilder.*/Select(tCustomer.Columns)\n    .From(tCustomer)\n    .Where(tCustomer.Type == 2 | tCustomer.Name.Like(\"%Free%\"))\n    .OrderBy(Desc(tCustomer.Name))\n    .OffsetFetch(1, 2)\n    .QueryList(database,\n        r =\u003e (Id: tCustomer.CustomerId.Read(r), CustomerType: tCustomer.Type.Read(r), Name: tCustomer.Name.Read(r)));\n\nforeach (var customer in customers)\n{\n    Console.WriteLine($\"Id: {customer.Id}, Name: {customer.Name}, Type: {customer.CustomerType}\");\n}\n\n```\n\n*Actual T-SQL:*\n\n```sql\nSELECT \n    [CUST].[CustomerId],\n    [CUST].[Type],\n    [CUST].[Name] \nFROM \n(\n    SELECT \n        [A0].[CustomerId] [CustomerId],\n        CASE \n        WHEN [A1].[UserId] IS NOT NULL \n        THEN CAST(1 AS smallint) \n        WHEN [A2].[CompanyId] IS NOT NULL \n        THEN CAST(2 AS smallint) \n        ELSE NULL \n        END [Type],\n        CASE \n        WHEN [A1].[UserId] IS NOT NULL \n        THEN [A1].[FirstName]+' '+[A1].[LastName] \n        WHEN [A2].[CompanyId] IS NOT NULL \n        THEN [A2].[CompanyName] \n        ELSE NULL END [Name] \n    FROM [dbo].[Customer] [A0] \n    LEFT JOIN [dbo].[User] [A1] \n        ON [A1].[UserId]=[A0].[UserId] \n    LEFT JOIN [dbo].[Company] [A2] \n        ON [A2].[CompanyId]=[A0].[CompanyId]\n)[CUST] \nWHERE \n    [CUST].[Type]=2 OR [CUST].[Name] LIKE '%Free%' \nORDER BY [CUST].[Name] DESC \nOFFSET 1 ROW FETCH NEXT 2 ROW ONLY\n```\n\n*Result:*\n\n```\nId: 4, Name: Google, Type: 2\nId: 2, Name: Allina Freeborne, Type: 1\n```\n\n## Subqueries\n\nIt is not necessary to create a new class when you need a subquery. It can be described directly in the original expression. It is enough just to predefine the aliases for columns and tables:\n\n```cs\nvar num = CustomColumnFactory.Int32(\"3\");\n//Note: \"3\" (the first value) is for compatibility with MySql\n//which does not properly support values constructors\n\nvar sum = CustomColumnFactory.Int32(\"Sum\");\n\nvar numbers = Values(3, 1, 1, 7, 3, 7, 3, 7, 7, 8).AsColumns(num);\nvar numbersSubQuery = TableAlias();\n\nvar mostFrequentNum = (int) await\n    /*SqQueryBuilder.*/SelectTop(1, numbersSubQuery.Column(num))\n        .From(\n            /*SqQueryBuilder.*/Select(numbers.Column(num), CountOne().As(sum))\n                .From(numbers)\n                .GroupBy(numbers.Column(num))\n                .As(numbersSubQuery)\n        )\n        .OrderBy(/*SqQueryBuilder.*/Desc(numbersSubQuery.Column(sum)))\n        .QueryScalar(database);\n\nConsole.WriteLine(\"The most frequent number: \"  + mostFrequentNum);\n```\n\n*Actual T-SQL:*\n\n```sql\nSELECT \n    TOP 1 [A0].[3] \nFROM \n(\n    SELECT [A1].[3],COUNT(1) [Sum] \n    FROM (VALUES (3),(1),(1),(7),(3),(7),(3),(7),(7),(8))[A1]([3]) \n    GROUP BY [A1].[3]\n) [A0] \nORDER BY [A0].[Sum] DESC\n```\n\n*Note: In this example you can see how to use **Table Value Constructor***\n\n## CTE\n\nTo perform recursive (*actually \"incremental\"*) requests the library supports CTE (Common Table Expressions).\n\nThe typical scenario is traversing some hierarchical data stored in a table, for example the following query will return a tree closure table:\n\n```cs\nclass CteTreeClosure : CteBase\n{\n    public CteTreeClosure(Alias alias = default) : base(nameof(CteTreeClosure), alias)\n    {\n        this.Id = this.CreateInt32Column(nameof(this.Id));\n        this.ParentId = this.CreateNullableInt32Column(nameof(this.ParentId));\n        this.Depth = this.CreateInt32Column(nameof(this.Depth));\n    }\n\n    public Int32CustomColumn Id { get; }\n\n    public NullableInt32CustomColumn ParentId { get; }\n\n    public Int32CustomColumn Depth { get; }\n\n    public override IExprSubQuery CreateQuery()\n    {\n        var initial = new TreeData();\n        var current = new TreeData();\n\n        var previous = new CteTreeClosure();\n\n        return /*SqQueryBuilder.*/Select(initial.Id, initial.ParentId, /*SqQueryBuilder.*/Literal(1).As(this.Depth))\n            .From(initial)\n            .UnionAll(Select(\n                    previous.Id,\n                    current.ParentId,\n                    (previous.Depth + 1).As(this.Depth))\n                .From(current)\n                .InnerJoin(previous, on: previous.ParentId == current.Id))\n            .Done();\n    }\n}\n...\n\nvar result = await /*SqQueryBuilder.*/Select(treeClosure.Id, treeClosure.ParentId, treeClosure.Depth)\n    .From(treeClosure)\n    .QueryList(context.Database,\n        r =\u003e (\n            Id: treeClosure.Id.Read(r),\n            ParentId: treeClosure.ParentId.Read(r),\n            Depth: treeClosure.Depth.Read(r)));\n\n```\n\nWorking with CTEs in SqExpress is very similar to derived tables - you need to create a class derived from  **CteBase** abstract class, describe columns and implement **CreateQuery** method which will return actual CTE query where the class can be used as a table descriptor (to create recursion if it is required).\n\nThe example code will generate the following sql:\n\n```sql\nWITH [CteTreeClosure] AS(\n        SELECT [A1].[Id],[A1].[ParentId],1 [Depth] \n        FROM [#TreeData] [A1] \n    UNION ALL \n        SELECT [A2].[Id],[A3].[ParentId],[A2].[Depth]+1 [Depth] \n        FROM [#TreeData] [A3] \n        JOIN [CteTreeClosure] [A2] \n            ON [A2].[ParentId]=[A3].[Id]\n)\n                \nSELECT [A0].[Id],[A0].[ParentId],[A0].[Depth] FROM [CteTreeClosure] [A0]\n```\n\n*MySql*\n\n```sql\nWITH RECURSIVE `CteTreeClosure` AS(\n        SELECT `A0`.`Id`,`A0`.`ParentId`,1 `Depth` \n        FROM `TreeData` `A0` \n    UNION ALL \n        SELECT `A1`.`Id`,`A2`.`ParentId`,`A1`.`Depth`+1 `Depth` \n        FROM `TreeData` `A2` \n        JOIN `CteTreeClosure` `A1` \n            ON `A1`.`ParentId`=`A2`.`Id`\n) \n\nSELECT `A3`.`Id`,`A3`.`ParentId`,`A3`.`Depth` FROM `CteTreeClosure` `A3````\n```\n\n## Analytic And Window Functions\n\nSqExpress supports common analytic and window functions like **ROW_NUMBER**, **RANK**, **FIRST_VALUE**, **LAST_VALUE** etc.\n\n```cs\nvar cUserName = CustomColumnFactory.String(\"Name\");\nvar cNum = CustomColumnFactory.Int64(\"Num\");\nvar cFirst = CustomColumnFactory.String(\"First\");\nvar cLast = CustomColumnFactory.String(\"Last\");\n\nvar user = new TableUser();\n\nawait /*SqQueryBuilder.*/Select(\n        (user.FirstName + \" \" + user.LastName)\n        .As(cUserName),\n        /*SqQueryBuilder.*/RowNumber()\n            /*.OverPartitionBy(some fields)*/\n            .OverOrderBy(user.FirstName)\n            .As(cNum),\n        /*SqQueryBuilder.*/FirstValue(user.FirstName + \" \" + user.LastName)\n            /*.OverPartitionBy(some fields)*/\n            .OverOrderBy(user.FirstName)\n            .FrameClauseEmpty()\n            .As(cFirst),\n        /*SqQueryBuilder.*/LastValue(user.FirstName + \" \" + user.LastName)\n            /*.OverPartitionBy(some fields)*/\n            .OverOrderBy(user.FirstName)\n            .FrameClause(\n                FrameBorder.UnboundedPreceding,\n                FrameBorder.UnboundedFollowing)\n            .As(cLast))\n    .From(user)\n    .Query(database,\n        r =\u003e Console.WriteLine(\n            $\"Num: {cNum.Read(r)}, Name: {cUserName.Read(r)}, \" +\n            $\"First: {cFirst.Read(r)}, Last: {cLast.Read(r)}\"));\n```\n\n*Actual T-SQL:*\n\n```sql\nSELECT \n    [A0].[FirstName]+' '+[A0].[LastName] \n        [Name],\n    ROW_NUMBER()OVER(ORDER BY [A0].[FirstName]) \n        [Num],\n    FIRST_VALUE([A0].[FirstName]+' '+[A0].[LastName])\n        OVER(ORDER BY [A0].[FirstName]) \n        [First],\n    LAST_VALUE([A0].[FirstName]+' '+[A0].[LastName])\n        OVER(ORDER BY [A0].[FirstName] \n            ROWS BETWEEN \n            UNBOUNDED PRECEDING \n            AND UNBOUNDED FOLLOWING) \n        [Last] \nFROM [dbo].[User] [A0]\n```\n\n## Set Operators\n\nThe library supports all the SET operators:\n\n```cs\n//If you need to repeat one query several times \n// you can store it in a variable\nvar select1 = /*SqQueryBuilder.*/Select(1);\nvar select2 = /*SqQueryBuilder.*/Select(2);\n\nvar result = await select1\n    .Union(select2)\n    .UnionAll(select2)\n    .Except(select2)\n    .Intersect(select1.Union(select2))\n    .QueryList(database, r =\u003e r.GetInt32(0));\n\nConsole.WriteLine(\"Result Of Set Operators:\");\nConsole.WriteLine(result[0]);\n```\n\nAns actual SQL will be:\n\n```sql\n(\n    (\n        (\n            SELECT 1 \n            UNION \n            SELECT 2\n        ) \n        UNION ALL \n        SELECT 2\n    ) \n    EXCEPT \n    SELECT 2\n) \nINTERSECT \n(\n    SELECT 1 \n    UNION \n    SELECT 2\n)\n```\n\n## Merge\n\nAs a bonus, if you use MS SQL Server, you can use **Merge** statement:\n\n```cs\nvar data = new[]\n{\n    new {FirstName = \"Francois\", LastName = \"Sturman2\"},\n    new {FirstName = \"Allina\", LastName = \"Freeborne2\"},\n    new {FirstName = \"Maye\", LastName = \"Malloy\"},\n};\n\nvar action = CustomColumnFactory.String(\"Actions\");\nvar inserted = CustomColumnFactory.NullableInt32(\"Inserted\");\nvar deleted = CustomColumnFactory.NullableInt32(\"Deleted\");\n\nvar tableUser = new TableUser();\nawait /*SqQueryBuilder.*/MergeDataInto(tableUser, data)\n    .MapDataKeys(s =\u003e s\n        .Set(s.Target.FirstName, s.Source.FirstName))\n    .MapData(s =\u003e s\n        .Set(s.Target.LastName, s.Source.LastName))\n    .WhenMatchedThenUpdate()\n    .AlsoSet(s =\u003e s\n        .Set(s.Target.Version, s.Target.Version + 1)\n        .Set(s.Target.ModifiedAt, GetUtcDate()))\n    .WhenNotMatchedByTargetThenInsert()\n    .AlsoInsert(s =\u003e s\n        .Set(s.Target.Version, 1)\n        .Set(s.Target.ModifiedAt, GetUtcDate()))\n    .Output((t, s, m) =\u003e m.Inserted(t.UserId.As(inserted)).Deleted(t.UserId.As(deleted)).Action(action))\n    .Done()\n    .Query(database,\n        (r) =\u003e\n        {\n            Console.WriteLine($\"UserId Inserted: {inserted.Read(r)},UserId Deleted: {deleted.Read(r)} , Action: {action.Read(r)}\");\n        });\n```\n\n*Actual T-SQL:*\n\n```sql\nMERGE [dbo].[User] [A0] \nUSING (\n    VALUES \n    ('Francois','Sturman2'),\n    ('Allina','Freeborne2'),\n    ('Maye','Malloy'))[A1]([FirstName],[LastName]) \nON [A0].[FirstName]=[A1].[FirstName] \nWHEN MATCHED \nTHEN UPDATE SET [A0].[LastName]=[A1].[LastName],[A0].[Version]=[A0].[Version]+1,[A0].[ModifiedAt]=GETUTCDATE() \nWHEN NOT MATCHED \nTHEN INSERT([FirstName],[LastName],[Version],[ModifiedAt]) \nVALUES([A1].[FirstName],[A1].[LastName],1,GETUTCDATE()) \nOUTPUT INSERTED.[UserId] [Inserted],DELETED.[UserId] [Deleted],$ACTION [Actions];\n```\n\n*Result:*\n\n```\nUserId Inserted: 4,UserId Deleted:  , Action: INSERT\nUserId Inserted: 1,UserId Deleted: 1 , Action: UPDATE\nUserId Inserted: 2,UserId Deleted: 2 , Action: UPDATE\n```\n\nFor PostgresSQL or MySQL the library generates polyfills that use a temporary table to store passed data. For example the previous query will be converted into the following statements (OUTPUT is not supported):\n\n*Actual MYSQL:*\n\n```sql\nCREATE TEMPORARY TABLE `tmpMergeDataSource`(\n    `FirstName` varchar(8) character set utf8,\n    `LastName` varchar(10) character set utf8,\n    CONSTRAINT PRIMARY KEY (`FirstName`))\n;\nINSERT INTO `tmpMergeDataSource`(`FirstName`,`LastName`) \nVALUES ('Francois','Sturman2'),('Allina','Freeborne2'),('Maye','Malloy')\n;\nUPDATE `User` `A0`,`tmpMergeDataSource` `A1` \nSET \n    `A0`.`LastName`=`A1`.`LastName`,\n    `A0`.`Version`=`A0`.`Version`+1,\n    `A0`.`ModifiedAt`=UTC_TIMESTAMP()\nWHERE `A0`.`FirstName`=`A1`.`FirstName`\n;\nINSERT INTO `User`(`FirstName`,`LastName`,`Version`,`ModifiedAt`) \nSELECT `A1`.`FirstName`,`A1`.`LastName`,1,UTC_TIMESTAMP() \nFROM `tmpMergeDataSource` `A1` \nWHERE NOT EXISTS(SELECT 1 FROM `User` `A0` WHERE `A0`.`FirstName`=`A1`.`FirstName`)\n;\nDROP TABLE `tmpMergeDataSource`;\n```\n\n## Temporary Tables\n\nIn some scenarios temporary tables might be very useful. Just like normal tables, the recommended way is now to declare them with attributes and let the source generator produce the `TempTableBase` implementation:\n\nThe full attribute list is documented in [Table Description Reference](Documentation/table_description.md).\n\n```cs\nusing SqExpress.TableDeclarationAttributes;\n\n[TempTableDescriptor(\"tempTable\")]\n[Int32Column(\"Id\", Pk = true, Identity = true)]\n[StringColumn(\"Name\", MaxLength = 255)]\npublic partial class TempTable\n{\n}\n```\n\n*Note: Handwritten `TempTableBase` descriptors are still supported when you want full manual control.*\n\nand then use it:\n\n```cs\nvar tmp = new TempTable();\n\nvar tableUser = new TableUser();\nvar tableCompany = new TableCompany();\n\nawait database.Statement(tmp.Script.Create());\n\n//Users\nawait /*SqQueryBuilder.*/InsertInto(tmp, tmp.Name)\n    .From(Select(tableUser.FirstName + \" \"+ tableUser.LastName)\n    .From(tableUser))\n    .Exec(database);\n\n//Companies\nawait /*SqQueryBuilder.*/InsertInto(tmp, tmp.Name)\n    .From(Select(tableCompany.CompanyName)\n    .From(tableCompany))\n    .Exec(database);\n\nawait /*SqQueryBuilder.*/Select(tmp.Columns)\n    .From(tmp)\n    .OrderBy(tmp.Name)\n    .Query(database,\n        (r) =\u003e\n        {\n            Console.WriteLine($\"Id: {tmp.Id.Read(r)}, Name: {tmp.Name.Read(r)}\");\n        });\n\n//Dropping the temp table is optional\n//It will be automatically removed when\n//the connection is closed\nawait database.Statement(tmp.Script.Drop());\n```\n\nThe result will be:\n\n```\nId: 2, Name: Allina Freeborne\nId: 1, Name: Francois Sturman\nId: 4, Name: Google\nId: 3, Name: Microsoft\n```\n\n## Database Data Export Import\n\nHaving a list of table descriptors you can easily export all theirs data into any text format - JSON for example:\n\n```cs\nstatic async Task\u003cstring\u003e ToJsonString(ISqDatabase database, TableBase[] tableBases)\n{\n    using var ms = new MemoryStream();\n    using Utf8JsonWriter writer = new Utf8JsonWriter(ms);\n\n    writer.WriteStartObject();\n    foreach (var table in tableBases)\n    {\n        await ReadTableDataIntoJson(writer, database, table);\n    }\n\n    writer.WriteEndObject();\n    writer.Flush();\n\n    var s = Encoding.UTF8.GetString(ms.ToArray());\n    return s;\n}\n\nstatic async Task ReadTableDataIntoJson(Utf8JsonWriter writer, ISqDatabase database, TableBase table)\n{\n    writer.WriteStartArray(table.FullName.AsExprTableFullName().TableName.Name);\n\n    writer.WriteStartArray();\n    foreach (var column in table.Columns)\n    {\n        writer.WriteStringValue(column.ColumnName.Name);\n    }\n\n    writer.WriteEndArray();\n\n    await /*SqQueryBuilder.*/Select(table.Columns)\n        .From(table)\n        .Query(database,\n            r =\u003e\n            {\n                writer.WriteStartArray();\n                foreach (var column in table.Columns)\n                {\n                    var readAsString = column.ReadAsString(r);\n                    writer.WriteStringValue(readAsString);\n                }\n\n                writer.WriteEndArray();\n            });\n\n    writer.WriteEndArray();\n}\n```\n\nResult:\n\n```json\n{\n    \"User\": [\n [\"UserId\", \"FirstName\", \"LastName\", \"Version\", \"ModifiedAt\"], \n [\"1\", \"Francois\", \"Sturman2\", \"2\", \"2021-10-26T08:07:03.160\"], \n [\"2\", \"Allina\", \"Freeborne2\", \"2\", \"2021-10-26T08:07:03.160\"], \n [\"4\", \"Maye\", \"Malloy\", \"1\", \"2021-10-26T08:07:03.160\"]],\n    \"Company\": [\n [\"CompanyId\", \"CompanyName\", \"Version\", \"ModifiedAt\"], \n [\"1\", \"Microsoft\", \"1\", \"2021-10-26T08:07:03.080\"], \n [\"2\", \"Google\", \"1\", \"2021-10-26T08:07:03.080\"]],\n    \"Customer\": [\n [\"CustomerId\", \"UserId\", \"CompanyId\"], \n [\"3\", null, \"1\"], \n [\"4\", null, \"2\"], \n [\"1\", \"1\", null], \n [\"2\", \"2\", null]]\n}\n```\n\nImport from a text format is not difficult as well:\n\n```cs\nstatic async Task InsertTableData(ISqDatabase database, TableBase table, JsonElement element)\n{\n    var columnsDict = table.Columns.ToDictionary(i =\u003e i.ColumnName.Name, i =\u003e i);\n    var colIndexes = element.EnumerateArray().First().EnumerateArray().Select(c =\u003e c.GetString()).ToList();\n\n    var rowsEnumerable = element\n        .EnumerateArray()\n        .Skip(1)\n        .Select(e =\u003e\n            e.EnumerateArray()\n                .Select((c, i) =\u003e\n                    columnsDict[colIndexes[i]]\n                        .FromString(c.ValueKind == JsonValueKind.Null ? null : c.GetString()))\n                .ToList());\n\n    var insertExpr = /*SqQueryBuilder.*/IdentityInsertInto(table, table.Columns).Values(rowsEnumerable);\n    if (!insertExpr.Insert.Source.IsEmpty)\n    {\n        await insertExpr.Exec(database);\n    }\n}\n```\n\n## Getting and Comparing Database Table Metadata\n\nYou can a list of dynamic table descriptors directly from a database using ```GetTables()``` method of ```ISqDatabase``` object. For example, this how you can read a list of all tables with all columns:\n\n```cs\nasync Task ShowAllTablesWithColumns(ISqDatabase database)\n{\n    var actualTables = await database.GetTables();\n    foreach (var table in actualTables)\n    {\n        Console.WriteLine(table.FullName.TableName);\n        foreach (var tableColumn in table.Columns)\n        {\n            Console.WriteLine($\"   -{tableColumn.ColumnName.Name}:{TSqlExporter.Default.ToSql(tableColumn.SqlType)}\");\n        }\n    }\n}\n```\n\nYou also can compare 2 lists of table to find any kind of differences:\n\n```cs\nasync Task\u003cbool\u003e CheckDatabaseIsUpdated(ISqDatabase database, IReadOnlyList\u003cTableBase\u003e expectedTableList)\n{\n    var actualTables = await database.GetTables();\n\n    var comparison = expectedTableList.CompareWith(actualTables);\n\n    bool result = true;\n\n    if (comparison != null)\n    {\n        if (comparison.ExtraTables.Count \u003e 0)\n        {\n            Console.WriteLine($\"There are {comparison.ExtraTables.Count} extra tables\");\n        }\n        if (comparison.MissedTables.Count \u003e 0)\n        {\n            result = false;\n            Console.WriteLine($\"There are {comparison.MissedTables.Count} missed tables\");\n        }\n        if (comparison.DifferentTables.Count \u003e 0)\n        {\n            result = false;\n            Console.WriteLine($\"There are {comparison.DifferentTables.Count} different tables\");\n\n            foreach (var differentTable in comparison.DifferentTables)\n            {\n                Console.WriteLine($\"Table {differentTable.Table.FullName.TableName}\");\n                foreach (var extra in differentTable.TableComparison.ExtraColumns)\n                {\n                    Console.WriteLine($\"Extra column: {extra.ColumnName.Name}\");\n                }\n                foreach (var missed in differentTable.TableComparison.MissedColumns)\n                {\n                    Console.WriteLine($\"Extra column: {missed.ColumnName.Name}\");\n                }\n                foreach (var differentColumns in differentTable.TableComparison.DifferentColumns)\n                {\n                    Console.WriteLine($\"Different column: {differentColumns.Column.ColumnName.Name} - {differentColumns.ColumnComparison}\");\n                }\n\n            }\n\n        }\n    }\n    return result;\n}\n```\n\nYou cane also create new table dynamic descriptors and modify existing ones:\n\n```cs\nvar tbl = SqTable.Create(\n    \"schema\",\n    \"table\",\n    b =\u003e b\n        .AppendInt32Column(\"Id\", ColumnMeta.PrimaryKey().Identity())\n        .AppendStringColumn(\"Value\", 255, true)\n        .AppendBooleanColumn(\"IsActive\", ColumnMeta.DefaultValue(false)),\n    i =\u003e i\n        .AppendIndex(i.Asc(\"Id\"), i.Desc(\"Value\"))\n        .AppendIndex(i.Asc(\"Value\"))\n);\n\ntbl = tbl.With(\n    tbl.FullName.WithSchemaName(\"schema2\").WithTableName(\"table2\"),\n    (cols, app) =\u003e app\n        .AppendColumns(cols.Where(c =\u003e c.ColumnName.Name != \"IsActive\"))\n        .AppendDateTimeOffsetColumn(\"modifyDate\"),\n    (indexes, app) =\u003e app\n        .AppendIndexes(indexes.Where(i=\u003ei.Columns.Count \u003e 1))\n        .AddUniqueIndex(app.Desc(\"modifyDate\"))\n);\n```\n\n## T-SQL Parser (SqTSqlParser)\n\nSqExpress can parse a T-SQL statement into `IExpr` and then you can export it to any supported dialect or modify the AST.\n\n```cs\nusing SqExpress.SqlParser;\n\nvar expr = SqTSqlParser.Parse(\n    \"SELECT 'Hi,' + @userName + '!'\",\n    existingTables: []);\n\nvar query = expr.WithParams((\"userName\", \"John\")).AsQuery();\n\nConsole.WriteLine(query.ToSql(TSqlExporter.Default));\n// SELECT 'Hi,'+'John'+'!'\n```\n\nFor data modification statements, bind parameters and then narrow to `IExprExec`:\n\n```cs\nvar delete = SqTSqlParser.Parse(\n    \"DELETE [User] WHERE UserId = @userId\",\n    existingTables: [new TableUser()])\n    .WithParams((\"userId\", 1))\n    .AsNonQuery();\n\nawait delete.Exec(database);\n```\n\nValidation overloads are also available:\n\n```cs\nif (SqTSqlParser.TryParse(sqlText, out IExpr? expr, out var tables, out var error))\n{\n    Console.WriteLine($\"Parsed tables: {tables.Count}\");\n}\nelse\n{\n    Console.WriteLine(error);\n}\n```\n\n`tables` (the `out` argument) contains table artifacts extracted from the parsed SQL.  \nYou can use it for diagnostics, metadata checks, or custom validation.\n\nIf you already know which tables should be present, use the overload with `existingTables` (`in`) for strict validation.\nIn practice, these known table descriptors usually come from the `Gen-Tables` utility output:\n\n```cs\nIReadOnlyList\u003cTableBase\u003e expectedTables = new TableBase[]\n{\n    new TableUser(),\n    new TableCustomer()\n};\n\nif (SqTSqlParser.TryParse(sqlText, expectedTables, out IExpr? expr, out var error))\n{\n    Console.WriteLine(\"SQL tables match expected descriptors\");\n}\nelse\n{\n    // error includes details about missing/extra tables and column differences\n    Console.WriteLine(error);\n}\n```\n\nIf you prefer exception-based flow, use `Parse(sqlText, expectedTables)`.  \nIt throws `SqExpressTSqlParserException` when SQL references missing tables/columns (relative to provided descriptors):\n\n```cs\ntry\n{\n    var expr = SqTSqlParser.Parse(sqlText, expectedTables);\n    Console.WriteLine(\"Parsed successfully\");\n}\ncatch (SqExpressTSqlParserException ex)\n{\n    Console.WriteLine(ex.Message);\n}\n```\n\nNotes:\n- `SqTSqlParser` parses one statement at a time.\n- Named parameters like `@userName` are represented as `ExprParameter` and can be replaced with `WithParams(...)`.\n- After replacing parameters, use `AsQuery()` when the parsed expression is a `SELECT`.\n- After replacing parameters, use `AsNonQuery()` for `INSERT` / `UPDATE` / `DELETE` / `MERGE`.\n- In parameter replacement helpers, use parameter names without `@` (for example, `\"userName\"`).\n\n## Syntax Tree\n\nYou can go through an existing syntax tree object and modify if it is required:\n\nReference: [AST Reference](Documentation/ast_reference.md)\n\n```cs\n//Var some external filter..\nExprBoolean filter = CustomColumnFactory.Int16(\"Type\") == 2 /*Company*/;\n\nvar tableCustomer = new TableCustomer();\n\nvar baseSelect = /*SqQueryBuilder.*/Select(tableCustomer.CustomerId)\n    .From(tableCustomer)\n    .Where(filter)\n    .Done();\n\n//Checking that filter has \"Type\" column\nvar hasVirtualColumn = filter.SyntaxTree()\n    .FirstOrDefault\u003cExprColumnName\u003e(e =\u003e e.Name == \"Type\") != null;\n\nif (hasVirtualColumn)\n{\n    baseSelect = (ExprQuerySpecification) baseSelect.SyntaxTree()\n        .Modify(e =\u003e\n        {\n            var result = e;\n            //Joining with the sub query\n            if (e is TableCustomer table)\n            {\n                var derivedTable = new DerivedTableCustomer();\n\n                result = new ExprJoinedTable(\n                    table,\n                    ExprJoinedTable.ExprJoinType.Inner,\n                    derivedTable,\n                    table.CustomerId == derivedTable.CustomerId);\n            }\n\n            return result;\n        });\n}\n\nawait baseSelect!\n    .Query(database,\n        (r) =\u003e\n        {\n            Console.WriteLine($\"Id: {tableCustomer.CustomerId.Read(r)}\");\n        });\n```\n\nFor simpler scenarios, you can use `With...` functions:\n\n```cs\nvar tUser = new TableUser();\n\nConsole.WriteLine(\"Original expression:\");\nvar expression = SelectTop(1, tUser.FirstName).From(tUser).Done();\n\nawait expression.QueryScalar(database);\n\nexpression = expression\n    .WithTop(null)\n    .WithSelectList(tUser.UserId, tUser.FirstName + \" \" + tUser.LastName)\n    .WithWhere(tUser.UserId == 7);\n\nConsole.WriteLine(\"With changed selection list and filter:\");\nawait expression.QueryScalar(database);\n\nvar tCustomer = new TableCustomer();\nexpression = expression\n    .WithInnerJoin(tCustomer, on: tCustomer.UserId == tUser.UserId);\n\nConsole.WriteLine(\"With joined table\");\nawait expression.QueryScalar(database);\n```\n\nFor read-only traversal and analysis, `ExprVisitorBase` can be easier than `Modify(...)`:\n\n```cs\npublic sealed class ColumnNameCollector : ExprVisitorBase\n{\n    public HashSet\u003cstring\u003e ColumnNames { get; } = new HashSet\u003cstring\u003e();\n\n    public override void VisitExprColumnName(ExprColumnName expr)\n    {\n        this.ColumnNames.Add(expr.Name);\n        base.VisitExprColumnName(expr); // keep default traversal\n    }\n}\n\nvar collector = new ColumnNameCollector();\nbaseSelect.Accept(collector);\n```\n\nRemarks:\n- During visitor callbacks you can inspect `CurrentPath`, `CurrentNode`, and `Depth`.\n- If you override a `Visit...` method and still need children traversal, call `base.Visit...(...)`.\n\n*Actual T-SQL:*\n\n```sql\n--Original expression:\nSELECT TOP 1 \n    [A0].[FirstName] \nFROM [dbo].[User] [A0]\n\n--With changed selection list  and filter:\nSELECT \n    [A0].[UserId],\n    [A0].[FirstName]+' '+[A0].[LastName] \nFROM [dbo].[User] \n    [A0] \nWHERE \n    [A0].[UserId]=7\n\n--With joined table\nSELECT \n    [A0].[UserId],\n    [A0].[FirstName]+' '+[A0].[LastName] \nFROM [dbo].[User] \n    [A0] \nJOIN [dbo].[Customer] \n    [A1] ON \n    [A1].[UserId]=[A0].[UserId] \nWHERE \n    [A0].[UserId]=7\n```\n\n## Serialization to XML\n\nEach expression can be exported to a xml string and then restored back. It can be useful to pass expressions over network:\n\n```cs\nvar tableUser = new TableUser(Alias.Empty);\n\nvar selectExpr = Select(tableUser.FirstName, tableUser.LastName)\n    .From(tableUser)\n    .Where(tableUser.LastName == \"Sturman\")\n    .Done();\n\n//Exporting\nvar stringBuilder = new StringBuilder();\nusing XmlWriter writer = XmlWriter.Create(stringBuilder);\nselectExpr.SyntaxTree().ExportToXml(writer);\n\n//Importing\nXmlDocument document = new XmlDocument();\ndocument.LoadXml(stringBuilder.ToString());\nvar restored = (ExprQuerySpecification)ExprDeserializer\n    .DeserializeFormXml(document.DocumentElement!);\n\nvar result = await restored\n    .QueryList(database, r =\u003e (tableUser.FirstName.Read(r), tableUser.LastName.Read(r)));\n\nforeach (var name in result)\n{\n    Console.WriteLine(name);\n}\n```\n\nThis an example of the XML text:\n\n```xml\n\u003cExpr typeTag=\"QuerySpecification\"\u003e\n   \u003cSelectList\u003e\n      \u003cSelectList0 typeTag=\"Column\"\u003e\n         \u003cColumnName typeTag=\"ColumnName\"\u003e\n            \u003cName\u003eFirstName\u003c/Name\u003e\n         \u003c/ColumnName\u003e\n      \u003c/SelectList0\u003e\n      \u003cSelectList1 typeTag=\"Column\"\u003e\n         \u003cColumnName typeTag=\"ColumnName\"\u003e\n            \u003cName\u003eLastName\u003c/Name\u003e\n         \u003c/ColumnName\u003e\n      \u003c/SelectList1\u003e\n   \u003c/SelectList\u003e\n   \u003cFrom typeTag=\"Table\"\u003e\n      \u003cFullName typeTag=\"TableFullName\"\u003e\n         \u003cDbSchema typeTag=\"DbSchema\"\u003e\n            \u003cSchema typeTag=\"SchemaName\"\u003e\n               \u003cName\u003edbo\u003c/Name\u003e\n            \u003c/Schema\u003e\n         \u003c/DbSchema\u003e\n         \u003cTableName typeTag=\"TableName\"\u003e\n            \u003cName\u003eUser\u003c/Name\u003e\n         \u003c/TableName\u003e\n      \u003c/FullName\u003e\n   \u003c/From\u003e\n   \u003cWhere typeTag=\"BooleanEq\"\u003e\n      \u003cLeft typeTag=\"Column\"\u003e\n         \u003cColumnName typeTag=\"ColumnName\"\u003e\n            \u003cName\u003eLastName\u003c/Name\u003e\n         \u003c/ColumnName\u003e\n      \u003c/Left\u003e\n      \u003cRight typeTag=\"StringLiteral\"\u003e\n         \u003cValue\u003eSturman\u003c/Value\u003e\n      \u003c/Right\u003e\n   \u003c/Where\u003e\n   \u003cDistinct\u003efalse\u003c/Distinct\u003e\n\u003c/Expr\u003e\n```\n\n## Serialization to JSON\n\nThe similar functionality exists for JSON (.Net Core 3.1+)\n\n```cs\nvar tableUser = new TableUser(Alias.Empty);\n\nvar selectExpr = Select(tableUser.FirstName, tableUser.LastName)\n    .From(tableUser)\n    .Where(tableUser.LastName == \"Sturman\")\n    .Done();\n\n//Exporting\nvar memoryStream = new MemoryStream();\nvar jsonWriter = new Utf8JsonWriter(memoryStream);\nselectExpr.SyntaxTree().ExportToJson(jsonWriter);\n\nstring json = Encoding.UTF8.GetString(memoryStream.ToArray());\n\n//Importing\nvar restored = (ExprQuerySpecification)ExprDeserializer\n    .DeserializeFormJson(JsonDocument.Parse(json).RootElement);\n\nvar result = await restored\n    .QueryList(database, r =\u003e (tableUser.FirstName.Read(r), tableUser.LastName.Read(r)));\n\nforeach (var name in result)\n{\n    Console.WriteLine(name);\n}\n```\n\nThis an example of the JSON text:\n\n```json\n{\n   \"$type\":\"QuerySpecification\",\n   \"SelectList\":[\n      {\n         \"$type\":\"Column\",\n         \"ColumnName\":{\n            \"$type\":\"ColumnName\",\n            \"Name\":\"FirstName\"\n         }\n      },\n      {\n         \"$type\":\"Column\",\n         \"ColumnName\":{\n            \"$type\":\"ColumnName\",\n            \"Name\":\"LastName\"\n         }\n      }\n   ],\n   \"From\":{\n      \"$type\":\"Table\",\n      \"FullName\":{\n         \"$type\":\"TableFullName\",\n         \"DbSchema\":{\n            \"$type\":\"DbSchema\",\n            \"Schema\":{\n               \"$type\":\"SchemaName\",\n               \"Name\":\"dbo\"\n            }\n         },\n         \"TableName\":{\n            \"$type\":\"TableName\",\n            \"Name\":\"User\"\n         }\n      }\n   },\n   \"Where\":{\n      \"$type\":\"BooleanEq\",\n      \"Left\":{\n         \"$type\":\"Column\",\n         \"ColumnName\":{\n            \"$type\":\"ColumnName\",\n            \"Name\":\"LastName\"\n         }\n      },\n      \"Right\":{\n         \"$type\":\"StringLiteral\",\n         \"Value\":\"Sturman\"\n      }\n   },\n   \"Distinct\":false\n}\n```\n\n## Serialization to Plain List\n\nAlso an expression can be exported into a list of plain entities. It might be useful if you want to store some expressions (e.g. \"Favorites Filters\") in a plain structure:\n\n```cs\nvar tableUser = new TableUser(Alias.Empty);\n\nExprBoolean filter1 = tableUser.LastName == \"Sturman\";\nExprBoolean filter2 = tableUser.LastName == \"Freeborne\";\n\nvar tableFavoriteFilter = new TableFavoriteFilter();\nvar tableFavoriteFilterItem = new TableFavoriteFilterItem();\n\nvar filterIds = await InsertDataInto(tableFavoriteFilter, new[] {\"Filter 1\", \"Filter 2\"})\n    .MapData(s =\u003e s.Set(s.Target.Name, s.Source))\n    .Output(tableFavoriteFilter.FavoriteFilterId)\n    .QueryList(database, r =\u003e tableFavoriteFilterItem.FavoriteFilterId.Read(r));\n\nvar filter1Items = \n    filter1.SyntaxTree().ExportToPlainList((i, id, index, b, s, value) =\u003e\n    FilterPlainItem.Create(filterIds[0], i, id, index, b, s, value));\n\nvar filter2Items = \n    filter2.SyntaxTree().ExportToPlainList((i, id, index, b, s, value) =\u003e\n    FilterPlainItem.Create(filterIds[1], i, id, index, b, s, value));\n\nawait /*SqQueryBuilder.*/InsertDataInto(tableFavoriteFilterItem, filter1Items.Concat(filter2Items))\n    .MapData(s =\u003e s\n        .Set(s.Target.FavoriteFilterId, s.Source.FavoriteFilterId)\n        .Set(s.Target.Id, s.Source.Id)\n        .Set(s.Target.ParentId, s.Source.ParentId)\n        .Set(s.Target.IsTypeTag, s.Source.IsTypeTag)\n        .Set(s.Target.ArrayIndex, s.Source.ArrayIndex)\n        .Set(s.Target.Tag, s.Source.Tag)\n        .Set(s.Target.Value, s.Source.Value)\n    )\n    .Exec(database);\n\n//Restoring\nvar restoredFilterItems = await /*SqQueryBuilder.*/Select(tableFavoriteFilterItem.Columns)\n    .From(tableFavoriteFilterItem)\n    .Where(tableFavoriteFilterItem.FavoriteFilterId.In(filterIds))\n    .QueryList(\n        database,\n        r =\u003e new FilterPlainItem(\n        favoriteFilterId: tableFavoriteFilterItem.FavoriteFilterId.Read(r),\n        id: tableFavoriteFilterItem.Id.Read(r),\n        parentId: tableFavoriteFilterItem.ParentId.Read(r),\n        isTypeTag: tableFavoriteFilterItem.IsTypeTag.Read(r),\n        arrayIndex: tableFavoriteFilterItem.ArrayIndex.Read(r),\n        tag: tableFavoriteFilterItem.Tag.Read(r),\n        value: tableFavoriteFilterItem.Value.Read(r)));\n\nvar restoredFilter1 = (ExprBoolean)ExprDeserializer\n    .DeserializeFormPlainList(restoredFilterItems.Where(fi =\u003e\n        fi.FavoriteFilterId == filterIds[0]));\n\nvar restoredFilter2 = (ExprBoolean)ExprDeserializer\n    .DeserializeFormPlainList(restoredFilterItems.Where(fi =\u003e\n        fi.FavoriteFilterId == filterIds[1]));\n\nConsole.WriteLine(\"Filter 1\");\nawait /*SqQueryBuilder.*/Select(tableUser.FirstName, tableUser.LastName)\n    .From(tableUser)\n    .Where(restoredFilter1)\n    .Query(database,\n        (r) =\u003e\n        {\n            Console.WriteLine($\"{tableUser.FirstName.Read(r)} {tableUser.LastName.Read(r)}\");\n        });\n\nConsole.WriteLine(\"Filter 2\");\nawait /*SqQueryBuilder.*/Select(tableUser.FirstName, tableUser.LastName)\n    .From(tableUser)\n    .Where(restoredFilter2)\n    .Query(database,\n        (r) =\u003e\n        {\n            Console.WriteLine($\"{tableUser.FirstName.Read(r)} {tableUser.LastName.Read(r)}\");\n        });\n```\n\n## Retrieving Database Table Metadata\n\nThe **ISqDatabase** interface includes a method called **GetTables()** that retrieves all table descriptors from a database defined in the connection string:\n\n```cs\nISqDatabase database = ...;\n\nvar allTables = await database.GetTables();\n\nforeach (var table in allTables)\n{\n    Console.WriteLine($\"{table.FullName.TableName}\");\n    foreach (var column in table.Columns)\n    {\n        Console.WriteLine(\n            $\"   *{column.ColumnName.Name} {column.SqlType.ToSql(TSqlExporter.Default)}\");\n    }\n}\n\n```\n\nResult:\n\n```\nUser\n   *UserId int\n   *FirstName [nvarchar](255)\n   *LastName [nvarchar](255)\n   *Version int\n   *ModifiedAt datetime\nCustomer\n   *CustomerId int\n   *UserId int\n   *CompanyId int\n\netc...\n```\n\n*Note: The list of tables is sorted in such a way that dependent tables appear last. Therefore, if the list is reversed, tables can be safely deleted:*\n\n```cs\nvar allTables = await database.GetTables();\n\nforeach (var table in allTables.Reverse())\n{\n    await database.Statement(table.Script.Drop());\n}\n```\n\nThe list of tables can be compared with each other:\n\n```cs\nvar declaredTables = AllTables.BuildAllTableList();\nvar actualTables = await database.GetTables();\n\nvar comparison = declaredTables.CompareWith(actualTables);\n\nif (comparison != null)\n{\n    if (comparison.ExtraTables.Count \u003e 0)\n    {\n        Console.WriteLine($\"There are {comparison.ExtraTables.Count} extra tables\");\n    }\n    if (comparison.MissedTables.Count \u003e 0)\n    {\n        Console.WriteLine($\"There are {comparison.MissedTables.Count} missed tables\");\n    }\n    if (comparison.DifferentTables.Count \u003e 0)\n    {\n        Console.WriteLine($\"There are {comparison.MissedTables.Count} different tables\");\n    }\n}\n```\n\n## Navigating Table References with TablesGraph\n\nIf your table descriptors contain foreign keys, SqExpress can build a navigation graph for them:\n\n```cs\nvar graph = TablesGraph.Create(AllTables.BuildAllAliasedTableList());\n```\n\n`TablesGraph` treats foreign keys as table references:\n\n- referenced table = foreign-key target\n- referenced-by table = table containing the foreign key\n\nThe graph models the real foreign-key structure:\n\n- a table can reference many tables\n- a table can be referenced by many tables\n- cycles are rejected during graph creation\n\nBasic navigation:\n\n```cs\nvar tCustomer = new TableCustomer();\nvar tCompany = new TableCompany();\n\nbool isInGraph = graph.Contains(tCustomer);\nbool referencesCompany = graph.References(tCustomer, tCompany);\n\nvar directReferences = graph.GetReferences(tCustomer);\nvar allReferences = graph.GetAllReferences(tCustomer).ToArray();\nvar referencedBy = graph.GetReferencedBy(tCompany);\nvar allReferencedBy = graph.GetAllReferencedBy(tCompany).ToArray();\n```\n\nImportant behavior:\n\n- table identity is based on full table name, not object reference\n- another `TableBase` instance with the same full name is treated as the same table\n- `Contains(...)` and `References(...)` return `false` for tables outside the graph\n- `GetReferences(...)`, `GetAllReferences(...)`, `GetReferencedBy(...)`, and `GetAllReferencedBy(...)` throw if the table does not belong to the graph\n\nThis is useful when you need to reason about descriptor relationships for features such as automatic security filters or join-path discovery.\n\nIt can also build a joinable table source for two tables connected by foreign keys:\n\n```cs\nvar tCustomer = new TableCustomer();\nvar tUser = new TableUser();\n\nif (graph.TryToJoinTables(tCustomer, tUser, out var joinedSource))\n{\n    var query = Select(AllColumns())\n        .From(joinedSource)\n        .Done();\n}\n```\n\n`TryToJoinTables(...)` returns:\n\n- `false` if either table is outside the graph\n- `false` if no foreign-key path exists between the tables\n- `true` with a joined `IExprTableSource` when a path can be built\n\nWhen several paths exist, `TablesGraph` chooses the shortest path. If multiple shortest paths exist, the first one discovered from the original table/reference order is used.\n\nThe returned value is a table source, not a complete `SELECT`, so it can be inserted into a bigger request.\n\n## Table Descriptors Scaffolding\n\n**SqExpress** comes with the code-gen utility (it is located in the NuGet package cache). It can read metadata from a database and create table descriptor classes in your code. It requires .NET Core 3.1+\n\n```Package Manager Console```\n\n```powershell\nGen-Tables -DbType {mssql | mysql | pgsql} -ConnectionString \u003cstring\u003e [-OutputDir \u003cstring\u003e] [-TableClassPrefix \u003cstring\u003e] [-Namespace \u003cstring\u003e] [-Verbosity {Quiet | Minimal | Normal | Detailed}] [-UseTableDeclarationAttributes] [-SkipUnknownColumnTypes]\n```\n\nParameters:\n\n- `-DbType`\n  Values: `mssql`, `mysql`, `pgsql`\n  Required.\n- `-ConnectionString`\n  Required.\n- `-OutputDir`\n  Optional. Output directory for generated `.cs` files.\n- `-TableClassPrefix`\n  Optional. Prefix for generated table descriptor class names. Default: `Table`.\n- `-Namespace`\n  Optional. Namespace for newly created files.\n- `-Verbosity`\n  Optional. Values: `Quiet`, `Minimal`, `Normal`, `Detailed`. Default: `Minimal`.\n- `-UseTableDeclarationAttributes`\n  Optional switch. Generates attribute-based partial declarations instead of direct `TableBase` descriptor classes.\n- `-SkipUnknownColumnTypes`\n  Optional switch. Skips unsupported database column types and generates descriptors from the remaining supported columns.\n\n```GenerateTables.cmd```\n\n```cmd\n@echo off\nset root=%userprofile%\\.nuget\\packages\\sqexpress\n\nfor /F \"tokens=*\" %%a in ('dir \"%root%\" /b /a:d /o:n') do set \"lib=%root%\\%%a\"\n\nset lib=%lib%\\tools\\codegen\\SqExpress.CodeGenUtil.dll\n\ndotnet \"%lib%\" gentables mssql \"MyConnectionString\" --table-class-prefix \"Tbl\" -o \".\\Tables\" -n \"MyCompany.MyProject.Tables\" --use-table-declaration-attributes\n```\n\n```GenerateTables.sh```\n\n```sh\n#!/bin/bash\n\nlib=~/.nuget/packages/sqexpress/$(ls ~/.nuget/packages/sqexpress -r|head -n 1)/tools/codegen/SqExpress.CodeGenUtil.dll\n\ndotnet $lib gentables mssql \"MyConnectionString\" --table-class-prefix \"Tbl\" -o \"./Tables\" -n \"MyCompany.MyProject.Tables\" --use-table-declaration-attributes\n```\n\nIt uses Roslyn compiler so it does not overwrite existing files - it patches them with actual columns/attributes. All kinds of changes like attributes, namespaces, interfaces, and helper methods will remain after next runs.\n\n## DTOs Scaffolding\n\nThe primary way to generate DTO models is now directly from attribute-based table declarations. You can declare one model for the whole table with `SqModel`, and add extra per-column model memberships with `SqModels`.\n\nFor the full attribute reference, see [Table Description Reference](Documentation/table_description.md).\n\n```cs\n[TableDescriptor(\"dbo\", \"User\", SqModel = \"UserDto\")]\n[Int32Column(\"UserId\", Pk = true, Identity = true, SqModels = \"UserName.Id\")]\n[StringColumn(\"FirstName\", Unicode = true, MaxLength = 255, SqModels = \"UserName\")]\n[StringColumn(\"LastName\", Unicode = true, MaxLength = 255, SqModels = \"UserName\")]\n[Int32Column(\"Version\", DefaultValue = \"0\", SqModels = \"AuditData\")]\n[DateTimeColumn(\"ModifiedAt\", DefaultValue = \"$utcNow\", SqModels = \"AuditData\")]\npublic partial class TableUser\n{\n}\n```\n\nRules:\n\n- `SqModel = \"UserDto\"` on the table declaration means every declared column participates in `UserDto`.\n- `SqModels = \"UserName.Id\"` means the column participates in `UserName`, and the generated property name becomes `Id`.\n- `SqModelCast = typeof(SomeType)` can be used when the generated model should cast the read value to another CLR type.\n\nThe built-in analyzer and source generator respect:\n\n- `SqModelGenNamespace`\n- `SqModelGenType`\n\nCurrent default:\n\n- generated models default to `record`\n- `ImmutableClass` is still supported for backward compatibility\n- `With...` methods are omitted for records\n\nThe result will look like:\n\n```cs\npublic record UserName\n{\n    public static UserName Read(ISqDataRecordReader record, TableUser table)\n    {\n        return new UserName(id: table.UserId.Read(record), firstName: table.FirstName.Read(record), lastName: table.LastName.Read(record));\n    }\n\n    public int Id { get; }\n\n    public string FirstName { get; }\n\n    public string LastName { get; }\n\n    public static TableColumn[] GetColumns(TableUser table)\n    {\n        return new TableColumn[]{table.UserId, table.FirstName, table.LastName};\n    }\n\n    public static IRecordSetterNext GetMapping(IDataMapSetter\u003cTableUser, UserName\u003e s)\n    {\n        return s.Set(s.Target.FirstName, s.Source.FirstName).Set(s.Target.LastName, s.Source.LastName);\n    }\n\n    public static IRecordSetterNext GetUpdateKeyMapping(IDataMapSetter\u003cTableUser, UserName\u003e s)\n    {\n        return s.Set(s.Target.UserId, s.Source.Id);\n    }\n\n    public static IRecordSetterNext GetUpdateMapping(IDataMapSetter\u003cTableUser, UserName\u003e s)\n    {\n        return s.Set(s.Target.FirstName, s.Source.FirstName).Set(s.Target.LastName, s.Source.LastName);\n    }\n}\n```\n\nLegacy note:\n\n- the old file-based `genmodels` flow and property-level `[SqModel]` attributes still work for now\n- that path is deprecated and planned for removal in `2.0`\n- new work should prefer attribute-based table declarations plus source-generated DTOs\n\n*Note: attribute-based `SqModel` generation works for both `TableDescriptor` and `TempTableDescriptor`.*\n\n## Model Selection\n\nThe library contains a fluent api that helps selecting tuples of models inner or left joined.\n\n```\nSqModelSelectBuilder\n    .Select(Model1.GetReader())\n    .InnerJoin(\n        Model2.GetReader(), \n        on: t=\u003e t.Table.Id1 == t.JoinedTable1.Id1)\n    .InnerJoin(\n        Model3.GetReader(), \n        on: t=\u003e t.JoinedTable2.Id2 == t.JoinedTable1.Id2)\n    ...\n    .InnerJoin(\n        ModelN.GetReader(), \n        on: t=\u003e t.JoinedTable(N-1).Id(N-1) == t.JoinedTable(N-2).Id(N-1)))\n    .LeftJoin(\n        Model(N+1).GetReader(), \n        on: t=\u003e t.JoinedTableN.IdN == t.JoinedTable(N-1).IdN))\n    ...\n    .Get(\n        filter: t=\u003e \u003cBoolean Expression\u003e,\n        order: t=\u003e\u003cOrder Expression\u003e,\n        tuple=\u003e \u003cResult Mapping\u003e)\n    .QueryList(database);\n\n    ... or\n    .Find(\n        offset, pageSize,\n        filter: t=\u003e \u003cBoolean Expression\u003e,\n        order: t=\u003e\u003cOrder Expression\u003e,\n        tuple=\u003e \u003cResult Mapping\u003e)\n    .QueryPage(database);\n```\n\nExample:\n\n```cs\nvar page = await SqModelSelectBuilder\n    .Select(ModelEmptyReader.Get\u003cTableCustomer\u003e())\n    .LeftJoin(\n        UserName.GetReader(), \n        on: t =\u003e t.Table.UserId == t.JoinedTable1.UserId)\n    .LeftJoin(\n        CompanyName.GetReader(), \n        on: t =\u003e t.Table.CompanyId == t.JoinedTable2.CompanyId)\n    .Find(0,10,\n        filter: null,\n        order: t =\u003e Asc(\n            IsNull(\n                t.JoinedTable1.FirstName + t.JoinedTable1.LastName,\n                t.JoinedTable2.CompanyName)\n            ),\n        r =\u003e (r.JoinedModel1 != null \n                ? r.JoinedModel1.FirstName + \" \"+ r.JoinedModel1.LastName \n                : null) \n            ??\n            r.JoinedModel2?.Name ?? \"Unknown\")\n    .QueryPage(database);\n\nforeach (var name in page.Items)\n{\n    Console.WriteLine(name);\n}\n\n```\n\n## Parametrization Modes\n\n`SqDatabase` supports parametrization modes for expression execution:\n\n```cs\nusing var database = new SqDatabase\u003cSqlConnection\u003e(\n    connection: connection,\n    commandFactory: (conn, sql) =\u003e new SqlCommand(sql, conn),\n    sqlExporter: TSqlExporter.Default,\n    parametrizationMode: ParametrizationMode.LiteralFallback\n);\n```\n\nModes:\n\n- `ParametrizationMode.None` - keep all literals inline.\n- `ParametrizationMode.ThrowOnLimit` - parametrize literals and throw if parameter limit is exceeded.\n- `ParametrizationMode.LiteralFallback` - parametrize literals, and when limit is exceeded keep remaining values as literals.\n\nCurrent exporter parameter limits:\n\n- MS SQL (`TSqlExporter`): `2000`\n- PostgreSQL (`PgSqlExporter`): `65535`\n- MySQL (`MySqlExporter`): `65535`\n\nPerformance notes:\n\n- Parametrization usually improves plan cache reuse and can reduce SQL text size for repeated queries.\n- It also adds overhead to create/bind parameters, so very small one-off queries can be slightly faster with inline literals.\n- Large parameter lists increase client and server work (binding/parsing), and can hit dialect parameter limits.\n- On MS SQL, heavy parametrization can expose parameter-sniffing behavior on some workloads.\n- Cached plans can also hurt performance when first-execution parameters are not representative (for example, highly variable input size/cardinality such as TVP-like workloads), because the same plan is reused for very different cases.\n- `LiteralFallback` is a practical default because it keeps most cache benefits while avoiding hard failures when a limit is exceeded.\n\n## Using in ASP.NET\n\nThere is a demo application, [SqDbAiAgent](https://github.com/0x1000000/SqDbAiAgent), that shows how SqExpress can be used as a fail-closed safety and validation layer for AI-generated T-SQL in a real SQL Server-backed workflow, so only validated and secured queries from the supported parser surface are allowed to reach execution.\n\nThe ideas:\n\n1. Each API request uses only one SQL connection which is stored in [a connection storage](https://github.com/0x1000000/SqGoods/blob/main/SqGoods.DomainLogic/DataAccess/MsSqlConnectionStorage.cs);\n2. The connection storage [can create an instance of SqDatabase](https://github.com/0x1000000/SqGoods/blob/main/SqGoods.DomainLogic/DataAccess/MsSqlConnectionStorage.cs#L18);\n3. The connection storage and SqDatabase [have \"Scoped\" lifecycle](https://github.com/0x1000000/SqGoods/blob/main/SqGoods.DomainLogic/DomainLogicRegistration.cs#L17);\n4. SqDatabase is used in [entity repositories that are responsible for \"Domain Logic\"](https://github.com/0x1000000/SqGoods/blob/main/SqGoods.DomainLogic/Repositories/SgCategoryRepository.cs).\n\n## PostgreSQL\n\nYou can run all the scenarios using Postgres SQL (of course the actual sql will be different):\n\n```Cs\nDbCommand NpgsqlCommandFactory(NpgsqlConnection connection, string sqlText)\n{\n    return new NpgsqlCommand(sqlText, connection);\n}\n\nconst string connectionString = \n    \"Host=localhost;Port=5432;Username=postgres;Password=test;Database=test\";\n\nusing (var connection = new NpgsqlConnection(connectionString))\n{\n    using (var database = new SqDatabase\u003cNpgsqlConnection\u003e(\n        connection: connection,\n        commandFactory: NpgsqlCommandFactory,\n        sqlExporter: new PgSqlExporter(builderOptions: SqlBuilderOptions.Default\n            .WithSchemaMap(schemaMap: new[] {\n                new SchemaMap(@from: \"dbo\", to: \"public\")})),\n        parametrizationMode: ParametrizationMode.LiteralFallback))\n    {\n        ...\n    }\n}\n```\n\n*Note: You need to add **Npgsql** package to your project.*\n\n## MySQL\n\nYou can also run all the scenarios using MySQL:\n\n```Cs\nDbCommand MySqlCommandFactory(MySqlConnection connection, string sqlText)\n{\n    return new MySqlCommand(sqlText, connection);\n}\n\nconst string connectionString = \n    \"server=127.0.0.1;uid=test;pwd=test;database=test\";\n\nusing (var connection = new MySqlConnection(connectionString))\n{\n    using (var database = new SqDatabase\u003cMySqlConnection\u003e(\n        connection: connection,\n        commandFactory: MySqlCommandFactory,\n        sqlExporter: new MySqlExporter(\n            builderOptions: SqlBuilderOptions.Default),\n        parametrizationMode: ParametrizationMode.LiteralFallback))\n    {\n        ...\n    }\n}\n```\n\n*Note: You need to add **MySql.Data** or **MySqlConnector** package to your project.*\n\n## AutoMapper\n\nSince the DAL works on top of ADO.NET, you can use AutoMapper (if you like it):\n\n```cs\nvar mapper = new Mapper(new MapperConfiguration(cfg =\u003e\n{\n    cfg.AddDataReaderMapping();\n    var map = cfg.CreateMap\u003cIDataRecord, AllColumnTypesDto\u003e();\n\n    if (context.IsPostgresSql)\n    {\n        map\n            .ForMember(nameof(table.ColByte), c =\u003e c.Ignore())\n            .ForMember(nameof(table.ColNullableByte), c =\u003e c.Ignore());\n    }\n}));\n\nvar result = await Select(table.Columns)\n    .From(table)\n    .QueryList(context.Database, r =\u003e mapper.Map\u003cIDataRecord, AllColumnTypesDto\u003e(r));\n```\n\n[(taken from \"Test/SqExpress.IntTest/Scenarios/ScAllColumnTypes.cs\")](https://github.com/0x1000000/SqExpress/blob/main/Test/SqExpress.IntTest/Scenarios/ScAllColumnTypes.cs#L26)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0x1000000%2Fsqexpress","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0x1000000%2Fsqexpress","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0x1000000%2Fsqexpress/lists"}