Class BulkInsertOptions

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Options for a bulk insert started with CreateBulkInsertBuilder. Immutable and safe to reuse; build one with BulkInsertOptionsBuilder or set the properties directly. Providers that cannot express a requested option reject it with NotSupportedException when the write runs, and invalid values are rejected as soon as the options are attached to a builder.

public sealed record BulkInsertOptions : IEquatable<BulkInsertOptions>

Inheritance

object

BulkInsertOptions

Implements

IEquatable<BulkInsertOptions>

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?)

Properties

CheckConstraints

Whether CHECK and FOREIGN KEY constraints are checked by the destination while the rows are written. true is honoured everywhere: a path that always checks constraints accepts it by its default behaviour, and SQL Server maps it to SqlBulkCopyOptions.CheckConstraints. false asks for unchecked rows, which only the SQL Server native path can express (MariaDB and SQLite honour it through their scoped session controls); every other path always checks and rejects it with NotSupportedException. Defaults to null (the provider default).

public bool? CheckConstraints { get; init; }

Property Value

bool?

ClickHouse

ClickHouse-specific native InsertBinaryAsync options, or null (nothing requested). A group with every value unset creates no request; a supplied value on another provider is rejected when the target provider is known.

public ClickHouseBulkInsertOptions? ClickHouse { get; init; }

Property Value

ClickHouseBulkInsertOptions

DatabaseName

The database part of an independently qualified destination, or null to take it from the mapping/context. Provider support is validated when the target provider is known; not every provider can address another database.

public string? DatabaseName { get; init; }

Property Value

string

FireTriggers

Whether INSERT triggers fire for the written rows. Only the SQL Server native SqlBulkCopy path can express it (SqlBulkCopyOptions.FireTriggers), so true is rejected elsewhere. false requests no firing and is honoured by every path by not asking for it. Defaults to null (triggers do not fire on the native path).

public bool? FireTriggers { get; init; }

Property Value

bool?

IgnoreDuplicates

Whether rows that violate a unique constraint are skipped instead of failing the whole write. Uses the provider's ignore form on whichever path can express it: the native MySQL/MariaDB load (ConflictOption.Ignore) or the portable statement (ON CONFLICT DO NOTHING, INSERT OR IGNORE, INSERT IGNORE). A provider where neither path can express it (for example SQL Server) refuses the request with NotSupportedException before any row is read. Defaults to false.

public bool IgnoreDuplicates { get; init; }

Property Value

bool

KeepIdentity

Whether explicit values are written to identity columns. The path decision stays capability based: the native path writes the explicit values where the provider can (MySQL/MariaDB through their explicit-column load, SQL Server through SqlBulkCopyOptions.KeepIdentity, PostgreSQL through the explicit COPY column list), and the portable path renders the provider's overriding form (SQL Server wraps the insert with SET IDENTITY_INSERT, PostgreSQL adds OVERRIDING SYSTEM VALUE). Silently ignored when the entity's mapping declares no identity column (matching linq2db), so it never surfaces SQL Server error 8106 on a non-identity table and does not change the selected path there. Defaults to false.

public bool KeepIdentity { get; init; }

Property Value

bool

KeepNulls

Whether explicit null values are written instead of the destination column's DEFAULT. Every path writes the caller's values, so true is honoured everywhere (SQL Server maps it to SqlBulkCopyOptions.KeepNulls). false asks the destination to apply the column DEFAULT instead of an explicit null; it is accepted where the written shape is default-equivalent and rejected otherwise when the target provider is known. Defaults to null (the provider default).

public bool? KeepNulls { get; init; }

Property Value

bool?

MaxBatchSize

The maximum rows per statement on the portable path; the native path treats it as a batch hint (SQL Server SqlBulkCopy.BatchSize) or ignores it (PostgreSQL COPY streams). Defaults to null (one statement, or the provider default).

public int? MaxBatchSize { get; init; }

Property Value

int?

MaxParameters

The maximum bound parameters per statement on the portable path. Defaults to null.

public int? MaxParameters { get; init; }

Property Value

int?

MaxSqlLength

The approximate maximum SQL text length per statement on the portable path. Defaults to null.

public int? MaxSqlLength { get; init; }

Property Value

int?

Mode

The requested execution path. Auto is the default: the provider prefers its native path when every request is compatible and otherwise uses the portable path only when that path honours every request.

public BulkInsertMode Mode { get; init; }

Property Value

BulkInsertMode

NotifyEvery

The progress reporting interval in rows. Defaults to 1.

public int NotifyEvery { get; init; }

Property Value

int

Progress

Called with the cumulative written-row count every NotifyEvery rows, or null. The callback runs inline after a committed batch (portable) or on the provider's native progress tick; nextorm opens no implicit transaction, so a throwing callback propagates and leaves the already-written rows committed. The second argument is the token from ProgressCancellationTokenSource (or None); the write aborts with OperationCanceledException if the token is cancelled when the callback returns — arm it with CancelAfter(TimeSpan) to time-limit the callback cooperatively.

public Action<int, CancellationToken>? Progress { get; init; }

Property Value

Action<int, CancellationToken>

ProgressCancellationTokenSource

The source whose Token is passed to Progress, or null for None. Owned by the caller: nextorm never cancels or disposes it. Cancelling it (for example through CancelAfter(TimeSpan)) makes the writer throw OperationCanceledException once the in-flight callback returns.

public CancellationTokenSource? ProgressCancellationTokenSource { get; init; }

Property Value

CancellationTokenSource

SchemaName

The schema part of an independently qualified destination, or null to take it from the mapping/context. Unlike TableSchema it does not require TableName: schema-only targeting keeps the mapped table and overrides only its schema.

public string? SchemaName { get; init; }

Property Value

string

ServerName

The server part of an independently qualified destination, or null. This is an identifier qualification only where the provider/path supports it, never connection rerouting; an unsupported server qualification is rejected when the target provider is known.

public string? ServerName { get; init; }

Property Value

string

SqlServer

SQL Server-specific native SqlBulkCopy options, or null (nothing requested). A group with every value unset creates no request; a supplied value on another provider is rejected when the target provider is known.

public SqlServerBulkInsertOptions? SqlServer { get; init; }

Property Value

SqlServerBulkInsertOptions

TableLock

Whether a table-level bulk-update lock is taken for the duration of the write. Only the SQL Server native SqlBulkCopy path can express it (SqlBulkCopyOptions.TableLock), so true is rejected elsewhere. false requests no such lock and is honoured by every path by not asking for one. Defaults to null (row locks).

public bool? TableLock { get; init; }

Property Value

bool?

TableName

Overrides the entity's mapped table for this write, without requiring a second [SqlTable] mapping. When set, the naming convention is not applied to the target; TableSchema optionally qualifies it. Defaults to null (the mapped table name is used).

public string? TableName { get; init; }

Property Value

string

TableSchema

The schema (or database) that qualifies TableName, or null for an unqualified target. Only meaningful together with TableName. Kept for compatibility; the independent destination part is SchemaName.

public string? TableSchema { get; init; }

Property Value

string

TargetKind

The kind of destination table. Regular is the default; a local temporary target uses the context's existing connection and session and never creates or drops the table.

public BulkInsertTargetKind TargetKind { get; init; }

Property Value

BulkInsertTargetKind

Timeout

The whole-invocation timeout budget, measured from the moment the bulk operation starts, or null for no additional nextorm deadline. Spans connection acquisition, setup, asynchronous enumeration, batching, driver work and progress work, and never resets per batch. Zero and negative values are rejected.

public TimeSpan? Timeout { get; init; }

Property Value

TimeSpan?