Class BulkInsertBuilder<TEntity>

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Builder for a bulk insert over a mapped entity, started with CreateBulkInsertBuilder<TEntity> (passing a BulkInsertOptions or a BulkInsertOptionsBuilder callback). Supply the rows with Values(IEnumerable<TEntity>) and finish with a terminal. It writes through the provider's native bulk API where one exists, and through a chunked parameterised INSERT ... VALUES otherwise; the write shape is configured through BulkInsertOptions.

There is deliberately no change tracking: every terminal issues one explicit bulk write, as with linq2db BulkCopy. The builder is single-use and the source is read once. Unlike InsertBuilder<TEntity>, the native path does not return generated keys — request ReturningKey<TKey>() or Returning<TResult>(Expression<Func<TEntity, TResult>>) for that (it forces the portable, RETURNING/OUTPUT-capable path).

public sealed class BulkInsertBuilder<TEntity>

Type Parameters

TEntity

The mapped entity type written.

Inheritance

object

BulkInsertBuilder<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

BulkInsert()

Writes every row and returns the number written.

public int BulkInsert()

Returns

int

The number of rows written (0 for an empty source).

Exceptions

InvalidOperationException

No Values source was supplied, or the source is async.

NotSupportedException

The context is read-only, or the provider cannot express a requested form.

BulkInsertAsync(CancellationToken)

Asynchronously writes every row and returns the number written.

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

Parameters

cancellationToken CancellationToken

Cancels execution.

Returns

Task<int>

A task producing the number of rows written (0 for an empty source).

Exceptions

InvalidOperationException

No Values source was supplied.

NotSupportedException

The context is read-only, or the provider cannot express a requested form.

IgnoreFilters()

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

public BulkInsertBuilder<TEntity> IgnoreFilters()

Returns

BulkInsertBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(IEnumerable<string>)

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

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

Parameters

filterKeys IEnumerable<string>

The filter keys to disable.

Returns

BulkInsertBuilder<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 BulkInsertBuilder<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

BulkInsertBuilder<TEntity>

This builder, for chaining.

IgnoreFilters(params Type[])

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

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

Parameters

entityTypes Type[]

The entity types whose filters are disabled.

Returns

BulkInsertBuilder<TEntity>

This builder, for chaining.

ReturningKey<TKey>()

Switches the builder to a row-returning terminal that materialises the entity's key column from metadata through the provider's RETURNING/OUTPUT form. Forces the portable path and requires the provider to support RETURNING/OUTPUT.

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

Returns

BulkInsertReturningBuilder<TEntity, TKey>

A returning builder whose terminals produce the generated keys.

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 every written row through the provider's RETURNING/OUTPUT form. Forces the portable path and requires the provider to support RETURNING/OUTPUT.

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

Parameters

projection Expression<Func<TEntity, TResult>>

Selects the mapped columns to return.

Returns

BulkInsertReturningBuilder<TEntity, TResult>

A returning builder whose terminals produce the projected rows.

Type Parameters

TResult

The projected row shape.

Exceptions

ArgumentNullException

projection is null.

NotSupportedException

The projection references something other than mapped properties.

ToSql()

Renders the parameterised SQL this builder would execute for the first batch on the portable path, without executing it. Useful for diagnostics and for verifying SQL generation without a database; the native path has no SQL and is still rendered as the portable INSERT ... VALUES form.

public string ToSql()

Returns

string

The rendered SQL text.

Exceptions

InvalidOperationException

No Values source was supplied, the source is empty, or it is async.

NotSupportedException

The context is not database-backed.

Values(IAsyncEnumerable<TEntity>)

Sets the entities to write from an asynchronous sequence. The sequence is streamed once.

public BulkInsertBuilder<TEntity> Values(IAsyncEnumerable<TEntity> entities)

Parameters

entities IAsyncEnumerable<TEntity>

The entities to write.

Returns

BulkInsertBuilder<TEntity>

This builder, for chaining.

Exceptions

ArgumentNullException

entities is null.

InvalidOperationException

A value source was already assigned.

Values(IEnumerable<TEntity>)

Sets the entities to write from a synchronous sequence. The sequence is iterated once; an empty sequence writes nothing and returns 0.

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

Parameters

entities IEnumerable<TEntity>

The entities to write.

Returns

BulkInsertBuilder<TEntity>

This builder, for chaining.

Exceptions

ArgumentNullException

entities is null.

InvalidOperationException

A value source was already assigned.