Class BatchBuilder

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Collects the statements of a batch: side-effecting statements (materialisations and DML) followed by one or more result-bearing queries. A single result can be added with the terminal Query<TResult>(QueryCommand<TResult>); several results can be added with AddQuery<TResult>(QueryCommand<TResult>) and then materialised together with Execute() (one network round trip, every result set read eagerly). Every statement is rendered with one shared parameter sequence (captured variables are prefixed per statement), so placeholder names never collide.

public sealed class BatchBuilder

Inheritance

object

BatchBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

EntityBuilderExtensions.AsEntityBuilder<T>(object?)

Methods

AddQuery<TResult>(QueryCommand<TResult>)

Adds a result-bearing query without ending the batch, so several result sets can be carried by one batch and materialised together by Execute(). May be called repeatedly; every result query must be added after all side-effecting statements.

public BatchBuilder AddQuery<TResult>(QueryCommand<TResult> query)

Parameters

query QueryCommand<TResult>

The query whose rows form the next result set.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TResult

The projected row type of the added query.

Exceptions

ArgumentNullException

query is null.

InvalidOperationException

The batch was ended with Query<TResult>(QueryCommand<TResult>); a single-result terminal cannot be combined with AddQuery<TResult>(QueryCommand<TResult>).

ArgumentException

The query is bound to a different data context.

CreateTable(string, QueryCommand, CreateTableOptions?)

Adds a persistent CREATE TABLE ... AS SELECT materialisation to the batch.

public BatchBuilder CreateTable(string name, QueryCommand source, CreateTableOptions? options = null)

Parameters

name string

The raw (unquoted) target table name; the naming convention is not applied.

source QueryCommand

The query whose rows fill the table.

options CreateTableOptions

Optional statement options.

Returns

BatchBuilder

This builder, for chaining.

Exceptions

InvalidOperationException

The result-bearing query has already been added.

NotSupportedException

The dialect cannot express the materialisation or one of the requested options.

CreateTable(string, QueryCommand, Func<CreateTableOptionsBuilder, CreateTableOptionsBuilder>)

Adds a persistent CREATE TABLE ... AS SELECT materialisation to the batch, configuring the options fluently.

public BatchBuilder CreateTable(string name, QueryCommand source, Func<CreateTableOptionsBuilder, CreateTableOptionsBuilder> configure)

Parameters

name string

The raw (unquoted) target table name; the naming convention is not applied.

source QueryCommand

The query whose rows fill the table.

configure Func<CreateTableOptionsBuilder, CreateTableOptionsBuilder>

Configures the statement options through CreateTableOptionsBuilder; its return value is ignored.

Returns

BatchBuilder

This builder, for chaining.

Exceptions

ArgumentNullException

configure is null.

InvalidOperationException

The result-bearing query has already been added.

NotSupportedException

The dialect cannot express the materialisation or one of the requested options.

CreateTempTable(string, QueryCommand, CreateTableOptions?)

Adds a temporary CREATE TEMPORARY TABLE ... AS SELECT materialisation to the batch. The table is session-scoped: reading it in the same batch is exactly what the batch guarantees.

public BatchBuilder CreateTempTable(string name, QueryCommand source, CreateTableOptions? options = null)

Parameters

name string

The raw (unquoted) target table name; the naming convention is not applied.

source QueryCommand

The query whose rows fill the table.

options CreateTableOptions

Optional statement options.

Returns

BatchBuilder

This builder, for chaining.

Exceptions

InvalidOperationException

The result-bearing query has already been added.

NotSupportedException

The dialect cannot express a temporary materialisation or one of the requested options.

CreateTempTable(string, QueryCommand, Func<CreateTableOptionsBuilder, CreateTableOptionsBuilder>)

Adds a temporary CREATE TEMPORARY TABLE ... AS SELECT materialisation to the batch, configuring the options fluently.

public BatchBuilder CreateTempTable(string name, QueryCommand source, Func<CreateTableOptionsBuilder, CreateTableOptionsBuilder> configure)

Parameters

name string

The raw (unquoted) target table name; the naming convention is not applied.

source QueryCommand

The query whose rows fill the table.

configure Func<CreateTableOptionsBuilder, CreateTableOptionsBuilder>

Configures the statement options through CreateTableOptionsBuilder; its return value is ignored.

Returns

BatchBuilder

This builder, for chaining.

Exceptions

ArgumentNullException

configure is null.

InvalidOperationException

The result-bearing query has already been added.

NotSupportedException

The dialect cannot express a temporary materialisation or one of the requested options.

Delete<TEntity>(DeleteBuilder<TEntity>)

Adds a side-effecting DELETE to the batch. It runs before the result-bearing query, on the same session, so the query observes the deletion.

public BatchBuilder Delete<TEntity>(DeleteBuilder<TEntity> delete)

Parameters

delete DeleteBuilder<TEntity>

The delete builder whose predicate defines the statement.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type whose rows are removed.

Exceptions

ArgumentNullException

delete is null.

InvalidOperationException

The result-bearing query has already been added.

ArgumentException

The statement is bound to a different data context.

Execute()

Executes the batch and eagerly materialises every result set added with AddQuery<TResult>(QueryCommand<TResult>). The whole batch — all side-effecting statements and all result queries — runs as one network round trip; the result sets are fully buffered before this method returns.

public BatchResult Execute()

Returns

BatchResult

The eagerly materialised result sets, readable in the order the queries were added.

Exceptions

InvalidOperationException

No result-bearing query was added, or the batch was ended with Query<TResult>(QueryCommand<TResult>).

NotSupportedException

The dialect cannot express the batch or one of its statements.

ExecuteAsync(CancellationToken)

Asynchronously executes the batch and eagerly materialises every result set added with AddQuery<TResult>(QueryCommand<TResult>). The whole batch runs as one network round trip and the result sets are fully buffered before the returned task completes.

public Task<BatchResult> ExecuteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<BatchResult>

A task producing the eagerly materialised result sets.

Exceptions

InvalidOperationException

No result-bearing query was added, or the batch was ended with Query<TResult>(QueryCommand<TResult>).

NotSupportedException

The dialect cannot express the batch or one of its statements.

FromOutputTable(string)

Starts a query over the rows a capture step of this batch wrote into a table variable, reading its columns through TableAlias accessors (for example t["id"].AsInt). Useful for joins and for aggregating over the captured rows.

public EntityBuilder<TableAlias> FromOutputTable(string variableName)

Parameters

variableName string

The table-variable name of an earlier capture of this batch.

Returns

EntityBuilder<TableAlias>

A builder over the captured rows.

Exceptions

ArgumentException

variableName is not a valid table-variable identifier.

InvalidOperationException

variableName is not a capture registered earlier on this batch.

FromOutput<TResult>(string)

Starts a typed query over the rows a capture step of this batch wrote into a table variable. The returned builder projects the captured row shape, so the rows can be filtered, ordered, joined, paged and aggregated with the ordinary operator set; the source renders as the bare table-variable identifier and is never quoted.

public EntityBuilder<TResult> FromOutput<TResult>(string variableName)

Parameters

variableName string

The table-variable name of an earlier capture of this batch.

Returns

EntityBuilder<TResult>

A typed builder over the captured rows.

Type Parameters

TResult

The captured row shape; it must match the capture's projection.

Exceptions

ArgumentException

variableName is not a valid table-variable identifier.

InvalidOperationException

variableName is not a capture registered earlier on this batch, or its projection is not TResult.

Insert<TEntity>(InsertBuilder<TEntity>)

Adds a side-effecting INSERT to the batch. It runs before the result-bearing query, on the same session, so the query can observe the inserted rows.

public BatchBuilder Insert<TEntity>(InsertBuilder<TEntity> insert)

Parameters

insert InsertBuilder<TEntity>

The insert builder whose values define the statement.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type written by the statement.

Exceptions

ArgumentNullException

insert is null.

InvalidOperationException

The result-bearing query has already been added.

ArgumentException

The statement is bound to a different data context.

OutputIntoTableVariable<TEntity, TResult>(DeleteReturningBuilder<TEntity, TResult>, string, string)

Adds a side-effecting DELETE whose removed rows are captured into a same-batch table variable (read through the deleted alias), mirroring OutputIntoTableVariable<TEntity, TResult>(InsertReturningBuilder<TEntity, TResult>, string, string).

public BatchBuilder OutputIntoTableVariable<TEntity, TResult>(DeleteReturningBuilder<TEntity, TResult> mutation, string variableName, string columnDefinitions)

Parameters

mutation DeleteReturningBuilder<TEntity, TResult>

The delete terminal whose returned columns are captured.

variableName string

The table-variable name, with or without the leading @.

columnDefinitions string

The trusted column-definition text of the DECLARE @t TABLE (...) declaration.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type deleted.

TResult

The row shape the returning builder projects.

Exceptions

ArgumentNullException

mutation is null.

ArgumentException

variableName is not a bare table-variable identifier, or columnDefinitions is null, empty or whitespace.

InvalidOperationException

The capture is duplicated on this batch, or a result-bearing query was already added.

NotSupportedException

The provider has no OUTPUT INTO form (only SQL Server supports the capture), or the projection yields no output columns.

OutputIntoTableVariable<TEntity, TResult>(InsertReturningBuilder<TEntity, TResult>, string, string)

Adds a side-effecting INSERT whose returned rows are captured into a same-batch table variable (SQL Server OUTPUT ... INTO @t) instead of being returned to the client. The batch renders DECLARE @t TABLE (...); INSERT ... OUTPUT ... INTO @t (...) as one statement; a later FromOutput<TResult>(string) or FromOutputTable(string) step of the same batch reads the captured rows, so the whole operation stays one round trip.

The table-variable name is one identifier with an optional leading @, normalised to @name; it is never quoted. columnDefinitions is trusted caller SQL that is embedded verbatim in the DECLARE text and never parameterised.

public BatchBuilder OutputIntoTableVariable<TEntity, TResult>(InsertReturningBuilder<TEntity, TResult> mutation, string variableName, string columnDefinitions)

Parameters

mutation InsertReturningBuilder<TEntity, TResult>

The insert terminal whose returned columns are captured.

variableName string

The table-variable name, with or without the leading @.

columnDefinitions string

The trusted column-definition text of the DECLARE @t TABLE (...) declaration.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type inserted.

TResult

The row shape the returning builder projects.

Exceptions

ArgumentNullException

mutation is null.

ArgumentException

variableName is not a bare table-variable identifier, or columnDefinitions is null, empty or whitespace.

InvalidOperationException

The capture is duplicated on this batch, or a result-bearing query was already added.

NotSupportedException

The provider has no OUTPUT INTO form (only SQL Server supports the capture), or the projection yields no output columns.

OutputIntoTableVariable<TEntity, TResult>(MergeReturningBuilder<TEntity, TResult>, string, string)

Adds a side-effecting MERGE whose output rows are captured into a same-batch table variable. The captured output always leads with $action (written into the first column declared by columnDefinitions), followed by the returned columns written into the remaining declared columns; this is the batch-only MERGE OUTPUT-INTO form, not a new MERGE fluent terminal.

public BatchBuilder OutputIntoTableVariable<TEntity, TResult>(MergeReturningBuilder<TEntity, TResult> mutation, string variableName, string columnDefinitions)

Parameters

mutation MergeReturningBuilder<TEntity, TResult>

The merge terminal whose returned columns are captured.

variableName string

The table-variable name, with or without the leading @.

columnDefinitions string

The trusted column-definition text of the DECLARE @t TABLE (...) declaration; its first column receives $action.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type merged.

TResult

The row shape the returning builder projects.

Exceptions

ArgumentNullException

mutation is null.

ArgumentException

variableName is not a bare table-variable identifier, or columnDefinitions is null, empty or whitespace.

InvalidOperationException

The capture is duplicated on this batch, or a result-bearing query was already added.

NotSupportedException

The provider has no OUTPUT INTO form (only SQL Server supports the capture), or the projection yields no output columns.

OutputIntoTableVariable<TEntity, TResult>(UpdateReturningBuilder<TEntity, TResult>, string, string)

Adds a side-effecting UPDATE whose returned rows are captured into a same-batch table variable, mirroring OutputIntoTableVariable<TEntity, TResult>(InsertReturningBuilder<TEntity, TResult>, string, string).

public BatchBuilder OutputIntoTableVariable<TEntity, TResult>(UpdateReturningBuilder<TEntity, TResult> mutation, string variableName, string columnDefinitions)

Parameters

mutation UpdateReturningBuilder<TEntity, TResult>

The update terminal whose returned columns are captured.

variableName string

The table-variable name, with or without the leading @.

columnDefinitions string

The trusted column-definition text of the DECLARE @t TABLE (...) declaration.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type updated.

TResult

The row shape the returning builder projects.

Exceptions

ArgumentNullException

mutation is null.

ArgumentException

variableName is not a bare table-variable identifier, or columnDefinitions is null, empty or whitespace.

InvalidOperationException

The capture is duplicated on this batch, or a result-bearing query was already added.

NotSupportedException

The provider has no OUTPUT INTO form (only SQL Server supports the capture), or the projection yields no output columns.

Query<TResult>(QueryCommand<TResult>)

Adds the sole result-bearing query and returns the batch terminal. It must be the last statement: any further statement would throw. To carry more than one result use AddQuery<TResult>(QueryCommand<TResult>) and Execute() instead.

public BatchQuery<TResult> Query<TResult>(QueryCommand<TResult> query)

Parameters

query QueryCommand<TResult>

The query whose rows are materialised.

Returns

BatchQuery<TResult>

The batch terminal.

Type Parameters

TResult

The projected row type.

Exceptions

ArgumentNullException

query is null.

InvalidOperationException

A result-bearing query has already been added.

ArgumentException

The query is bound to a different data context.

Raw(string)

Adds a verbatim, side-effecting raw SQL statement to the batch. The text is rendered exactly as given — placeholders are not rewritten — and carries no parameters, so a value that must vary cannot be captured from an expression tree. Useful for statements the command model does not cover, such as SQL Server INSERT ... EXEC or scripts touching a session-scoped #temp table. It must be added before the result-bearing queries. The text is executed verbatim and binds no parameters, so pass only trusted SQL — never concatenate untrusted user input into a raw statement.

public BatchBuilder Raw(string sql)

Parameters

sql string

The statement text; it runs before the result-bearing queries.

Returns

BatchBuilder

This builder, for chaining.

Remarks

The batch must still end with at least one result-bearing query.

Exceptions

ArgumentException

sql is null, empty or whitespace.

InvalidOperationException

A result-bearing query has already been added; add raw statements before Query<TResult>(QueryCommand<TResult>)/AddQuery<TResult>(QueryCommand<TResult>).

ToSql()

Renders the whole batch (every added statement joined with ;) without executing it. The rendered text is exactly what Execute() runs; this is the inspection counterpart of execution for a batch built with AddQuery<TResult>(QueryCommand<TResult>), mirroring ToSql() for the single-result terminal.

public string ToSql()

Returns

string

The rendered SQL text.

Exceptions

InvalidOperationException

No result-bearing query was added, or the batch was ended with Query<TResult>(QueryCommand<TResult>).

NotSupportedException

The dialect cannot express the batch or one of its statements.

Truncate<TEntity>(TruncateBuilder<TEntity>)

Adds a side-effecting TRUNCATE to the batch. It runs before the result-bearing query. Providers without TRUNCATE (SQLite) reject it when the batch renders.

public BatchBuilder Truncate<TEntity>(TruncateBuilder<TEntity> truncate)

Parameters

truncate TruncateBuilder<TEntity>

The truncate builder for the target table.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type whose table is truncated.

Exceptions

ArgumentNullException

truncate is null.

InvalidOperationException

The result-bearing query has already been added.

ArgumentException

The statement is bound to a different data context.

Update<TEntity>(UpdateBuilder<TEntity>)

Adds a side-effecting UPDATE to the batch. It runs before the result-bearing query, on the same session, so the query can observe the updated rows.

public BatchBuilder Update<TEntity>(UpdateBuilder<TEntity> update)

Parameters

update UpdateBuilder<TEntity>

The update builder whose assignments and predicate define the statement.

Returns

BatchBuilder

This builder, for chaining.

Type Parameters

TEntity

The mapped entity type whose rows are updated.

Exceptions

ArgumentNullException

update is null.

InvalidOperationException

The result-bearing query has already been added.

ArgumentException

The statement is bound to a different data context.