Class QueryCommand

Namespace

NextORM.Core

Assembly

nextorm.core.dll

Clone and copy support for QueryCommand: the live clone used by prepared commands and the trimmed clone kept as the plan-cache key.

public class QueryCommand : IQueryRegistry, ICloneable

Inheritance

object

QueryCommand

Implements

IQueryRegistry

ICloneable

Derived

QueryCommand<TResult>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

EntityBuilderExtensions.AsEntityBuilder<T>(object?)

Constructors

QueryCommand(IDataContext?, QueryDefinition)

Initializes a command from a query shape, copying each collaborator and leaving the command unprepared. The shape's arrays are defensively copied: a definition can be supplied by a caller (the public CreateCommand) and its Joins array is caller-owned.

protected QueryCommand(IDataContext? dataProvider, QueryDefinition definition)

Parameters

dataProvider IDataContext

The context that executes the command, or null for an unbound clone.

definition QueryDefinition

The shape to copy from.

Fields

Paging

The paging state (LIMIT/OFFSET) applied to the query.

public Paging Paging

Field Value

Paging

_arrayJoins

The ClickHouse ARRAY JOIN expressions before preparation, or null when the clause is absent.

protected LambdaExpression[]? _arrayJoins

Field Value

LambdaExpression[]

_condition

The WHERE predicate lambda before preparation, or null when there is none.

protected LambdaExpression? _condition

Field Value

LambdaExpression

_dataContext

The context that executes the command, or null for an unbound cached clone.

protected IDataContext? _dataContext

Field Value

IDataContext

_exp

The original projection lambda, or null for a command without an explicit projection.

protected LambdaExpression? _exp

Field Value

LambdaExpression

_from

The prepared FROM source (physical table, subquery, CTE or set-operation operand), or null before preparation.

protected FromExpression? _from

Field Value

FromExpression

_groupExp

The GROUP BY key selector before preparation, or null when there is no grouping.

protected LambdaExpression? _groupExp

Field Value

LambdaExpression

_having

The HAVING predicate before preparation, or null when there is none.

protected LambdaExpression? _having

Field Value

LambdaExpression

_isPrepared

Whether the command has been prepared and its cached plan hashes are current.

protected bool _isPrepared

Field Value

bool

_preWhere

The ClickHouse PREWHERE predicate before preparation, or null when there is none.

protected LambdaExpression? _preWhere

Field Value

LambdaExpression

_selectList

The prepared projection columns after PrepareCommand, or null before preparation.

protected SelectExpression[]? _selectList

Field Value

SelectExpression[]

_sorting

The sort columns before preparation, or null when the query has no ORDER BY.

protected Sorting[]? _sorting

Field Value

Sorting[]

_srcType

The entity type the command reads from, or null for a command without a source type.

protected Type? _srcType

Field Value

Type

Properties

ArrayJoinKind

The ARRAY JOIN kind (plain or LEFT) shared by NextORM.Core.QueryCommand.ArrayJoinExpressions.

public ArrayJoinKind ArrayJoinKind { get; }

Property Value

ArrayJoinKind

Cache

Whether the prepared plan may be stored in and reused from the plan cache; set to false for commands that must not be cached.

public bool Cache { get; set; }

Property Value

bool

CommandTimeout

Per-query override of the command timeout in seconds: null inherits the context default (DataContextBuilder.UseCommandTimeout), and a value of zero or less means the provider default. Set through WithCommandTimeout.

public int? CommandTimeout { get; }

Property Value

int?

Components

The query components attached to this command, or null when there are none. Assigning a different list is an identity change: the memoized plan key is dropped together with the prepared descriptors computed under it, so a caller can never leave a stale prepared identity attached. The returned list is a read-only view over the shared backing list, so a downcast cannot mutate the list every clone sees; a single component is exposed through a one-item view object, never a one-element array.

public IReadOnlyList<IQueryComponent>? Components { get; set; }

Property Value

IReadOnlyList<IQueryComponent>

Condition

The WHERE predicate lambda, or null when there is none.

public Expression? Condition { get; }

Property Value

Expression

Ctes

Common table expressions declared for this command, in declaration order, or null when the command has none. The list renders as a with clause ahead of the outer select and participates in the plan cache key.

public IReadOnlyList<CteDefinition>? Ctes { get; }

Property Value

IReadOnlyList<CteDefinition>

CustomData

An extension slot for provider- or consumer-specific data; the core engine never reads or writes it.

public object? CustomData { get; set; }

Property Value

object

DataContext

The context that executes the command, or null for an unbound cached clone.

public IDataContext? DataContext { get; set; }

Property Value

IDataContext

EagerLoadMode

Per-command eager-load override: a concrete strategy set by an explicit LoadWith(..., mode), or null to inherit the context default (DataContextBuilder.UseEagerLoadMode). It follows the same override/default pattern as QuoteIdentifiers and KeywordCase. A command with no eager loads leaves it null and carries no resolved strategy.

public EagerLoadMode? EagerLoadMode { get; }

Property Value

EagerLoadMode?

EntityType

The entity type the command reads from, or null for a command without a source type.

public Type? EntityType { get; }

Property Value

Type

Final

Whether the query carries the ClickHouse FINAL modifier.

public bool Final { get; }

Property Value

bool

ForJsonClause

The trailing FOR JSON clause (SQL Server), or null when the result set is returned as rows. A dialect that does not implement it rejects a command that carries it.

public ForJsonClause? ForJsonClause { get; }

Property Value

ForJsonClause?

ForXmlClause

The trailing FOR XML clause (SQL Server), or null when the result set is returned as rows. Mutually exclusive with ForJsonClause.

public ForXmlClause? ForXmlClause { get; }

Property Value

ForXmlClause?

From

The prepared FROM source, or null before preparation.

public FromExpression? From { get; set; }

Property Value

FromExpression

GroupBy

The GROUP BY key selector, or null when the query has no grouping.

public LambdaExpression? GroupBy { get; }

Property Value

LambdaExpression

GroupByWithTotals

Whether the projection was declared through SelectGroup: the grouping keys are inferred from the projection's scalar outputs instead of a GroupBy lambda. Part of the plan key, so a SelectGroup plan never shares an entry with an equivalent explicit form.

public bool GroupByWithTotals { get; }

Property Value

bool

GroupingList

The prepared GROUP BY columns, or null when the query has no grouping.

public SelectExpression[]? GroupingList { get; }

Property Value

SelectExpression[]

GroupingSets

The explicit grouping sets (0-based indices into the grouping list) used when GroupingType is GroupingSets, or null otherwise. An empty set yields the grand total.

public IReadOnlyList<int[]>? GroupingSets { get; }

Property Value

IReadOnlyList<int[]>

GroupingType

The super-aggregate modifier applied to the grouping list (ROLLUP/CUBE), or None for a plain GROUP BY. Only meaningful when a grouping list is present.

public GroupingType GroupingType { get; }

Property Value

GroupingType

Having

The HAVING predicate lambda, or null when there is none.

public LambdaExpression? Having { get; }

Property Value

LambdaExpression

Hints

Statement-level query hints attached to this command (for example SQL Server RECOMPILE), or null when the command has none. How they are rendered is provider specific; a dialect that does not implement query hints rejects a command that carries them.

public IReadOnlyList<string>? Hints { get; }

Property Value

IReadOnlyList<string>

IgnoreFilters

Whether the command disables any global query filter declared for its entity type: true both when every filter is disabled (the all-or-nothing form) and when a selective scope disables only some filters. Setting it is all-or-nothing — true disables every filter and false clears the scope — because a bool cannot express a selective disable; use the builder's selective IgnoreFilters overloads for that. The authoritative state is NextORM.Core.QueryCommand.FilterScope. Assigning a different value discards the current preparation, because the injected filters and the prepared condition change.

public bool IgnoreFilters { get; set; }

Property Value

bool

IndexHintKind

The intent of IndexHints (USE, FORCE or IGNORE).

public IndexHintKind IndexHintKind { get; }

Property Value

IndexHintKind

IndexHints

Index hints attached to the command's physical FROM table (MySQL/MariaDB USE|FORCE|IGNORE INDEX, SQLite INDEXED BY/NOT INDEXED, SQL Server WITH (INDEX(...))), or null when there are none. A dialect without a native form (see IndexHints) rejects a command that carries them.

public IReadOnlyList<string>? IndexHints { get; }

Property Value

IReadOnlyList<string>

IsDistinct

Whether the command was marked with DISTINCT. Named IsDistinct rather than Distinct so the fluent Distinct() method does not hide the property on the generic command type.

public bool IsDistinct { get; }

Property Value

bool

IsPrepared

Whether the command has been prepared and its cached plan hashes are current.

public bool IsPrepared { get; }

Property Value

bool

Joins

The join clauses declared for the query, or null when there are none.

public JoinExpression[]? Joins { get; }

Property Value

JoinExpression[]

KeywordCase

Per-command override of the letter case in which SQL keywords are emitted: null inherits the context default (DataContextBuilder.UseKeywordCase). Set through WithKeywordCase.

public KeywordCase? KeywordCase { get; }

Property Value

KeywordCase?

Logger

The logger that receives command-preparation diagnostics, or null when logging is disabled.

public ILogger? Logger { get; }

Property Value

ILogger

NamingConvention

Per-command override of the naming convention applied to auto-derived table/column names: null inherits the context default (DataContextBuilder.UseNamingConvention). Set through WithNamingConvention.

public INamingConvention? NamingConvention { get; }

Property Value

INamingConvention

OuterReferences

The expressions registered as correlated outer references during preparation, or null when there are none.

public IReadOnlyList<Expression>? OuterReferences { get; }

Property Value

IReadOnlyList<Expression>

PreWhere

The ClickHouse PREWHERE predicate, or null when there is none.

public LambdaExpression? PreWhere { get; }

Property Value

LambdaExpression

PreparedComponents

The prepared query-component descriptors, or null when there are none. The engine owns the list; assigning it re-keys the command because the descriptors are part of the plan identity. The returned list is a read-only view over the shared backing list.

public IReadOnlyList<IQueryComponentDescriptor>? PreparedComponents { get; set; }

Property Value

IReadOnlyList<IQueryComponentDescriptor>

QuoteIdentifiers

Per-command override of identifier quoting: true quotes physical table/column names with the provider's delimiter, false emits them verbatim, and null inherits the context default (DataContextBuilder.UseQuotedIdentifiers). Set through WithQuotedIdentifiers.

public bool? QuoteIdentifiers { get; }

Property Value

bool?

ReferencedQueries

The commands referenced by correlated subqueries in this command's expressions, in registration order; empty until preparation registers one.

public IReadOnlyList<QueryCommand> ReferencedQueries { get; }

Property Value

IReadOnlyList<QueryCommand>

SampleOffset

The ClickHouse SAMPLE ... OFFSET value; zero when absent.

public double SampleOffset { get; }

Property Value

double

SampleRatio

The ClickHouse SAMPLE ratio (a value in [0, 1]), or null when absent.

public double? SampleRatio { get; }

Property Value

double?

SelectList

The prepared projection columns, or null before preparation.

public SelectExpression[]? SelectList { get; }

Property Value

SelectExpression[]

Settings

The trailing ClickHouse SETTINGS entries, or null when there are none.

public IReadOnlyList<KeyValuePair<string, string>>? Settings { get; }

Property Value

IReadOnlyList<KeyValuePair<string, string>>

SingleRow

Whether the command is shaped to return at most a single row (set by the First/Single terminals).

public bool SingleRow { get; set; }

Property Value

bool

Sorting

The sort columns declared for the query, or null when the query has no ORDER BY.

public Sorting[]? Sorting { get; }

Property Value

Sorting[]

TableHints

Table-level hints attached to the command's physical FROM table (for example SQL Server nolock), or null when there are none. How they are rendered is provider specific; a dialect that does not implement table hints rejects a command that carries them.

public IReadOnlyList<string>? TableHints { get; }

Property Value

IReadOnlyList<string>

TablesInScopeHints

Hints applied to every physical table in this command's scope (for example SQL Server WITH (...) on the primary and joined tables, or a pg_hint_plan/MySQL optimizer comment listing the participating aliases), or null when there are none. Set through the fluent WithTablesInScopeHint modifier. A dialect that supports neither form rejects the command when its SQL is built.

public IReadOnlyList<string>? TablesInScopeHints { get; }

Property Value

IReadOnlyList<string>

Tag

An optional query tag rendered as a block comment (/* tag */) immediately after the SELECT keyword, so the statement can be identified in logs, profilers and server-side query stores. Set through WithTag. When null no comment is emitted and the plan key is unchanged. The tag is part of the plan key, so two commands that differ only in their tag never share a cached plan.

public string? Tag { get; }

Property Value

string

UnionQuery

The second operand of the command's set operation, or null when the command carries none.

public QueryCommand? UnionQuery { get; }

Property Value

QueryCommand

UnionType

The set operation (UNION/INTERSECT/EXCEPT and their ALL variants) applied to the query.

public UnionType UnionType { get; }

Property Value

UnionType

Windows

The named window definitions declared for this query (WINDOW w AS (...)), or null when the query declares none. A dialect that does not support the clause rejects a command that carries them when its SQL is built.

public IReadOnlyList<WindowDefinition>? Windows { get; }

Property Value

IReadOnlyList<WindowDefinition>

Methods

AddOuterReference(Expression)

Registers an expression as a correlated outer reference and returns its index.

public int AddOuterReference(Expression node)

Parameters

node Expression

The expression that references an outer query.

Returns

int

The zero-based index of the reference in the command's outer-reference list.

Clone()

Returns a deep, independently mutable copy of this command.

public QueryCommand Clone()

Returns

QueryCommand

The cloned command.

CloneForCache()

Returns the detached clone that is stored in the plan cache and used as the cache key.

public QueryCommand CloneForCache()

Returns

QueryCommand

The cache clone.

CloneForCache(JoinExpression[]?)

Deep-clones the join expressions so a cached plan cannot observe later mutations.

protected static JoinExpression[]? CloneForCache(JoinExpression[]? joins)

Parameters

joins JoinExpression[]

The joins to clone, or null.

Returns

JoinExpression[]

The cloned joins, or null when joins is null.

CopyTo(QueryCommand, bool)

Copies the shared plan state of this command into dst. When copyAll is true the mutable query state (custom data, referenced queries, union, from and CTEs) is copied by reference for a live clone; otherwise those parts are deep-cloned so the plan-cache key cannot observe later mutations.

protected virtual void CopyTo(QueryCommand dst, bool copyAll)

Parameters

dst QueryCommand

The target command.

copyAll bool

Whether to copy all state by reference instead of cloning the mutable parts.

CreateSelf()

Creates an empty command of the same concrete type for a live clone.

protected virtual QueryCommand CreateSelf()

Returns

QueryCommand

A new command bound to this command's data context.

CreateSelfForClone()

Creates an empty command of the same type for a plan-cache key, detached from the data context.

protected virtual QueryCommand CreateSelfForClone()

Returns

QueryCommand

A new command with the mutable expressions cleared for later copying.

GetComponentPreparedCondition()

Gets the prepared WHERE predicate. Engine-owned structural primitive for query components.

public Expression? GetComponentPreparedCondition()

Returns

Expression

GetExpressionPlanEqualityComparer()

Returns the comparer used to compare expression plans, creating it on first use.

public ExpressionPlanEqualityComparer GetExpressionPlanEqualityComparer()

Returns

ExpressionPlanEqualityComparer

The expression-plan comparer.

GetFromExpressionPlanEqualityComparer()

Returns the comparer used to compare FROM-source plans, creating it on first use.

public FromExpressionPlanEqualityComparer GetFromExpressionPlanEqualityComparer()

Returns

FromExpressionPlanEqualityComparer

The FROM-source comparer.

GetJoinExpressionPlanEqualityComparer()

Returns the comparer used to compare join-expression plans, creating it on first use.

public JoinExpressionPlanEqualityComparer GetJoinExpressionPlanEqualityComparer()

Returns

JoinExpressionPlanEqualityComparer

The join-expression comparer.

GetQueryPlanEqualityComparer()

Returns the comparer used to key whole query plans, creating it on first use.

public QueryPlanEqualityComparer GetQueryPlanEqualityComparer()

Returns

QueryPlanEqualityComparer

The query-plan comparer.

GetSelectExpressionPlanEqualityComparer()

Returns the comparer used to compare select-list plans, creating it on first use.

public SelectExpressionPlanEqualityComparer GetSelectExpressionPlanEqualityComparer()

Returns

SelectExpressionPlanEqualityComparer

The select-list comparer.

GetSortingExpressionPlanEqualityComparer()

Returns the comparer used to compare sorting-expression plans, creating it on first use.

public SortingExpressionPlanEqualityComparer GetSortingExpressionPlanEqualityComparer()

Returns

SortingExpressionPlanEqualityComparer

The sorting-expression comparer.

PrepareCommand(bool, CancellationToken)

Builds the prepared pieces and plan-cache hashes for this command, optionally skipping the hash computation when the hash is already known.

public virtual void PrepareCommand(bool dontCalculateHash, CancellationToken cancellationToken)

Parameters

dontCalculateHash bool

Whether to skip recomputing the plan hashes.

cancellationToken CancellationToken

A token that cancels preparation.

PrepareCommand(CancellationToken)

Builds the prepared pieces (from/joins/columns/where/grouping/sorting, CTEs, set operations) and the plan-cache hashes for this command. The pipeline itself lives in QueryCommand.QueryPreparer; QueryCommand<TResult> extends it with the result hash.

public void PrepareCommand(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

ResetPreparation()

Discards every prepared piece (from, columns, grouping, conditions, array joins and hashes) so the command is prepared again on its next execution. Called after a clone is mutated.

public virtual void ResetPreparation()

SetComponentPreparedCondition(Expression?)

Sets the prepared WHERE predicate. Engine-owned structural primitive for query components.

public void SetComponentPreparedCondition(Expression? value)

Parameters

value Expression

SetComponentSelectList(SelectExpression[]?)

Sets the prepared projection columns. Engine-owned structural primitive for query components.

public void SetComponentSelectList(SelectExpression[]? value)

Parameters

value SelectExpression[]

SetComponentSorting(Sorting[]?)

Sets the ORDER BY columns. Engine-owned structural primitive for query components.

public void SetComponentSorting(Sorting[]? value)

Parameters

value Sorting[]

SetOperation(QueryCommand, UnionType)

Attaches a set operation to this command, chaining it onto an existing operation when one is present.

protected void SetOperation(QueryCommand queryCommand, UnionType unionType)

Parameters

queryCommand QueryCommand

The second operand of the set operation.

unionType UnionType

The kind of set operation to apply.