Class InsertBuilder<TEntity>

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Fluent builder for an INSERT statement over a mapped entity, started with CreateInsertBuilder<TEntity>(IDataContext, Action<EntityMetadataBuilder<TEntity>>?). It collects the columns and values, renders them as a parameterised statement through the active dialect and executes it on the context.

There is deliberately no change tracking: every terminal (Insert(), Returning(), ReturningIdentity<TKey>(), ReturningKey<TKey>()) issues one explicit command, as with linq2db or ExecuteNonQuery. The builder is single-use: values accumulate until a terminal runs.

public sealed class InsertBuilder<TEntity>

Type Parameters

TEntity

The mapped entity type inserted.

Inheritance

object

InsertBuilder<TEntity>

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

IgnoreFilters()

Disables all global query filters declared for the target entity type, so the insert is not validated against them. Repeatable: a later call accumulates with the earlier scope.

public InsertBuilder<TEntity> IgnoreFilters()

Returns

InsertBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(IEnumerable<string>)

Disables the named global query filters identified by filterKeys on the target entity type, so the insert is not validated against them. An empty or null filterKeys disables nothing. Repeatable: a later call accumulates (union) with the earlier scope.

public InsertBuilder<TEntity> IgnoreFilters(IEnumerable<string> filterKeys)

Parameters

filterKeys IEnumerable<string>

The filter keys to disable.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(IEnumerable<string>, params Type[])

Disables the named global query filters identified by filterKeys only on the given entityTypes (the intersection of keys and types); an empty entityTypes means any entity type. The key list is the gate: an empty or null filterKeys disables nothing even when entity types are supplied. Repeatable: a later call accumulates (union) with the earlier scope.

public InsertBuilder<TEntity> IgnoreFilters(IEnumerable<string> filterKeys, params Type[] entityTypes)

Parameters

filterKeys IEnumerable<string>

The filter keys to disable.

entityTypes Type[]

The entity types the disable is scoped to; empty means any entity type.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(params Type[])

Disables every global query filter declared for the given entity types, so the insert is not validated against them. An empty or null entityTypes disables nothing. Repeatable: a later call accumulates (union) with the earlier scope.

public InsertBuilder<TEntity> IgnoreFilters(params Type[] entityTypes)

Parameters

entityTypes Type[]

The entity types whose filters are disabled.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Insert()

Executes the insert and returns the number of affected rows.

public int Insert()

Returns

int

The number of rows inserted, as reported by the provider.

InsertAsync(CancellationToken)

Asynchronously executes the insert and returns the number of affected rows.

public Task<int> InsertAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<int>

A task producing the number of rows inserted.

Returning()

Switches the builder to a row-returning terminal that materialises the whole inserted entity through the provider's RETURNING/OUTPUT form (the equivalent of RETURNING * over the mapped columns).

public InsertReturningBuilder<TEntity, TEntity> Returning()

Returns

InsertReturningBuilder<TEntity, TEntity>

A returning builder whose terminals produce TEntity.

ReturningIdentity<TKey>()

Switches the builder to a row-returning terminal that materialises the last generated identity read through the provider's scalar identity function (SCOPE_IDENTITY(), lastval(), LAST_INSERT_ID(), last_insert_rowid()), without naming the column. Useful when the identity is not mapped or the provider has no RETURNING/OUTPUT.

public InsertReturningBuilder<TEntity, TKey> ReturningIdentity<TKey>()

Returns

InsertReturningBuilder<TEntity, TKey>

A returning builder whose terminals produce the generated key.

Type Parameters

TKey

The generated key's CLR type.

Exceptions

NotSupportedException

The provider has no identity function (ClickHouse).

ReturningIdentity<TKey>(Expression<Func<TEntity, TKey>>)

Switches the builder to a row-returning terminal that materialises the generated identity of selector through the provider's RETURNING, OUTPUT or LAST_INSERT_ID form.

public InsertReturningBuilder<TEntity, TKey> ReturningIdentity<TKey>(Expression<Func<TEntity, TKey>> selector)

Parameters

selector Expression<Func<TEntity, TKey>>

Selects the declared identity column.

Returns

InsertReturningBuilder<TEntity, TKey>

A returning builder whose terminals produce the generated key.

Type Parameters

TKey

The generated key's CLR type.

Exceptions

InvalidOperationException

The selected property is not declared as an identity.

ReturningKey<TKey>()

Switches the builder to a row-returning terminal that materialises the entity's key column, resolved from metadata ([Key], the fluent .Key() or the Id/<Type>Id convention) through RETURNING, OUTPUT or the identity-function fallback, without a selector.

public InsertReturningBuilder<TEntity, TKey> ReturningKey<TKey>()

Returns

InsertReturningBuilder<TEntity, TKey>

A returning builder whose terminals produce the key value.

Type Parameters

TKey

The key column's CLR type.

Exceptions

InvalidOperationException

The entity has no key, or TKey does not match it.

Returning<TResult>(Expression<Func<TEntity, TResult>>)

Switches the builder to a row-returning terminal that materialises a projection of the inserted row through the provider's RETURNING/OUTPUT form. The projection may be the identity, a single mapped property, an anonymous type, a positional constructor or a member-init; it may only reference mapped properties.

public InsertReturningBuilder<TEntity, TResult> Returning<TResult>(Expression<Func<TEntity, TResult>> projection)

Parameters

projection Expression<Func<TEntity, TResult>>

Selects the mapped columns to return.

Returns

InsertReturningBuilder<TEntity, TResult>

A returning builder whose terminals produce TResult.

Type Parameters

TResult

The projected row shape.

Exceptions

NotSupportedException

The projection references something other than mapped properties.

ToSql()

Renders the parameterised SQL this builder would execute for a plain insert, without executing it. Useful for diagnostics and for verifying SQL generation without a database.

public string ToSql()

Returns

string

The rendered SQL text.

Value<TValue>(Expression<Func<TEntity, TValue>>, SqlDefault)

Adds a column and writes its database DEFAULT instead of a value, for a single-row insert. A provider whose dialect cannot render the DEFAULT keyword rejects it with NotSupportedException; omit the column then to obtain the same default.

public InsertBuilder<TEntity> Value<TValue>(Expression<Func<TEntity, TValue>> column, SqlDefault value)

Parameters

column Expression<Func<TEntity, TValue>>

Selects the mapped column whose default is written.

value SqlDefault

The Value marker; it carries no data.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TValue

The column's CLR type.

Exceptions

InvalidOperationException

The builder already uses another values form.

NotSupportedException

The provider cannot render the DEFAULT keyword.

Value<TValue>(Expression<Func<TEntity, TValue>>, Expression<Func<TEntity, TValue>>)

Adds a column and copies the value of another mapped column of the same entity into it, or writes a parameter-free expression (for example x => DateTime.Now) folded into a parameter.

public InsertBuilder<TEntity> Value<TValue>(Expression<Func<TEntity, TValue>> column, Expression<Func<TEntity, TValue>> value)

Parameters

column Expression<Func<TEntity, TValue>>

Selects the mapped column to write.

value Expression<Func<TEntity, TValue>>

Selects the mapped column to read the value from.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TValue

The column's CLR type.

Exceptions

InvalidOperationException

The builder already uses Values(TEntity).

NotSupportedException

The value expression is neither a mapped property nor a constant.

Value<TValue>(Expression<Func<TEntity, TValue>>, TValue)

Adds a column and its constant value. Chain one call per column for a single-row insert. The value is always bound as a parameter, never inlined into the SQL.

public InsertBuilder<TEntity> Value<TValue>(Expression<Func<TEntity, TValue>> column, TValue value)

Parameters

column Expression<Func<TEntity, TValue>>

Selects the mapped column to write.

value TValue

The value to write, or null for SQL NULL.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TValue

The column's CLR type.

Exceptions

InvalidOperationException

The builder already uses Values(TEntity).

Value<TScalar>(TScalar)

Writes a single scalar value into the entity's only writable column (the one that is neither identity nor computed), without a projection.

public InsertBuilder<TEntity> Value<TScalar>(TScalar value)

Parameters

value TScalar

The value to write.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TScalar

The scalar value type.

Exceptions

InvalidOperationException

The entity does not have exactly one writable column.

Values(IEnumerable<TEntity>)

Writes all mapped, writable columns of every entity in a multi-row insert. Identity and computed columns are excluded automatically.

public InsertBuilder<TEntity> Values(IEnumerable<TEntity> entities)

Parameters

entities IEnumerable<TEntity>

The entities whose column values are written.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Exceptions

InvalidOperationException

The builder already uses Value<TValue>(Expression<Func<TEntity, TValue>>, TValue).

Values(TEntity)

Writes all mapped, writable columns of entity. Identity and computed columns are excluded automatically.

public InsertBuilder<TEntity> Values(TEntity entity)

Parameters

entity TEntity

The entity whose column values are written.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Exceptions

InvalidOperationException

The builder already uses Value<TValue>(Expression<Func<TEntity, TValue>>, TValue).

Values<TScalar>(IEnumerable<TScalar>)

Writes one row per value into the entity's only writable column (the one that is neither identity nor computed), without a projection.

public InsertBuilder<TEntity> Values<TScalar>(IEnumerable<TScalar> values)

Parameters

values IEnumerable<TScalar>

The values to write, one per row.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TScalar

The scalar value type.

Exceptions

InvalidOperationException

The entity does not have exactly one writable column.

Values<TValue>(Expression<Func<TEntity, TValue>>, IEnumerable<TValue>)

Adds one column's values to a multi-row insert, one value per row. Chain one call per column; every column must supply the same number of values. Use this when the entity has more than one writable column and the values are already column-oriented.

public InsertBuilder<TEntity> Values<TValue>(Expression<Func<TEntity, TValue>> column, IEnumerable<TValue> values)

Parameters

column Expression<Func<TEntity, TValue>>

Selects the mapped column to write.

values IEnumerable<TValue>

The values to write, one per row.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TValue

The column's CLR type.

Exceptions

InvalidOperationException

The builder already uses another values form, or the column is repeated.

ArgumentException

The value count differs from the other columns.

Values<TSource, TResult>(EntityBuilder<TSource>, Expression<Func<TSource, TResult>>)

Writes the rows produced by a server-side query (INSERT ... SELECT). The mapping selects the target columns by member name exactly like Values<TSource, TResult>(IEnumerable<TSource>, Expression<Func<TSource, TResult>>), but the rows are read by the database rather than the client: the query's SELECT is embedded after the target column list. A concrete entity uses an object initializer (new Order { Name = d.Name }); an interface-mapped entity uses an anonymous type (new { Name = d.Name }).

public InsertBuilder<TEntity> Values<TSource, TResult>(EntityBuilder<TSource> source, Expression<Func<TSource, TResult>> mapping)

Parameters

source EntityBuilder<TSource>

The query whose rows are inserted.

mapping Expression<Func<TSource, TResult>>

An object initializer or anonymous type selecting the written columns.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TSource

The source element type of the query.

TResult

The mapping shape: the entity or an anonymous type.

Exceptions

InvalidOperationException

The builder already uses another values form, or a member is duplicated.

NotSupportedException

A member is computed, writes DEFAULT, or the query uses runtime SqlFunctions.Parameter placeholders.

Values<TSource, TResult>(IEnumerable<TSource>, Expression<Func<TSource, TResult>>)

Writes one row per element of source, mapping each row's columns through mapping. A concrete entity uses an object initializer (new Order { Id = d.Id, Name = d.Name }); an interface-mapped entity uses an anonymous type (new { Id = d.Id, Name = d.Name }). Every mapped member's name must match a mapped property of TEntity.

public InsertBuilder<TEntity> Values<TSource, TResult>(IEnumerable<TSource> source, Expression<Func<TSource, TResult>> mapping)

Parameters

source IEnumerable<TSource>

The rows to insert; iterated once.

mapping Expression<Func<TSource, TResult>>

An object initializer or anonymous type selecting the written columns.

Returns

InsertBuilder<TEntity>

This builder, for chaining.

Type Parameters

TSource

The source element type.

TResult

The mapping shape: the entity or an anonymous type.

Exceptions

InvalidOperationException

The builder already uses another values form, or a member is duplicated.

NotSupportedException

A member is not a mapped write, or is a computed column.