Skip to main content

QueryPlanOptions

  • Namespace: PPDS.Dataverse.Query.Planning
  • Assembly: PPDS.Dataverse
  • Kind: Class

Summary​

Options for query plan construction.

Members​

Properties​

AggregateRecordLimit​

int AggregateRecordLimit { get; set; }

Maximum records per partition for aggregate partitioning. Default is 40,000 to stay safely below the Dataverse 50K AggregateQueryRecordLimit.

CteBindings​

Dictionary<string, IQueryPlanNode> CteBindings { get; set; }

CTE name-to-node bindings for recursive CTE planning. When the planner encounters a table matching a CTE name in this dictionary, it returns the bound node instead of generating FetchXML.

DmlRowCap​

Nullable<int> DmlRowCap { get; set; }

Row cap for DML operations. null = unlimited, default comes from DmlSafetyGuard (10,000).

EnablePrefetch​

bool EnablePrefetch { get; set; }

Whether to wrap scan nodes with PrefetchScanNode for page-ahead buffering. Default false (opt-in).

EstimatedRecordCount​

Nullable<long> EstimatedRecordCount { get; set; }

Estimated total record count for the query's entity. When set for aggregate queries and the count exceeds PPDS.Dataverse.Query.Planning.QueryPlanOptions.AggregateRecordLimit, the planner partitions the query by date range and executes partitions in parallel across the connection pool. Obtained from PPDS.Dataverse.Query.IQueryExecutor.GetTotalRecordCountAsync(System.String,System.Threading.CancellationToken) by the caller.

ExplainOnly​

bool ExplainOnly { get; set; }

If true, build plan for explanation only — don't execute.

ForceClientAggregation​

bool ForceClientAggregation { get; set; }

When true, forces client-side hash grouping instead of Dataverse-side aggregation. Set by the -- ppds:HASH_GROUP query hint.

IncludeCount​

bool IncludeCount { get; set; }

Whether to include total record count in the result.

MaxDate​

Nullable<DateTime> MaxDate { get; set; }

Latest createdon date in the target entity. Required for aggregate partitioning.

MaxRecordsPerPartition​

int MaxRecordsPerPartition { get; set; }

Maximum records per partition. Default is 40,000 to provide headroom below the 50K limit.

MaxRows​

Nullable<int> MaxRows { get; set; }

Global row limit, if any.

MinDate​

Nullable<DateTime> MinDate { get; set; }

Earliest createdon date in the target entity. Required for aggregate partitioning.

NoLock​

bool NoLock { get; set; }

When true, signals FetchXmlScanNode to inject no-lock="true" into FetchXML. Set by the -- ppds:NOLOCK query hint.

OriginalSql​

string OriginalSql { get; set; }

The original SQL text, needed for TDS Endpoint routing. When PPDS.Dataverse.Query.Planning.QueryPlanOptions.UseTdsEndpoint is true, this SQL is passed directly to the TDS Endpoint instead of being transpiled to FetchXML.

PageNumber​

Nullable<int> PageNumber { get; set; }

Page number for caller-controlled paging (1-based). When set, the plan fetches only this single page instead of auto-paging.

PagingCookie​

string PagingCookie { get; set; }

Paging cookie from a previous result for continuation. Used with PPDS.Dataverse.Query.Planning.QueryPlanOptions.PageNumber for caller-controlled paging.

PoolCapacity​

int PoolCapacity { get; set; }

Pool capacity from pool.GetTotalRecommendedParallelism().

PrefetchBufferSize​

int PrefetchBufferSize { get; set; }

Number of rows to buffer ahead for prefetch. Default 5000 (~3 FetchXML pages).

RemoteExecutorFactory​

Func<string, IQueryExecutor> RemoteExecutorFactory { get; set; }

Factory for creating IQueryExecutor instances for remote environments. Takes a profile label (e.g., "UAT"), returns an IQueryExecutor for that environment, or null if the label is not found. Combines profile resolution and executor creation. Set by the caller.

TdsQueryExecutor​

ITdsQueryExecutor TdsQueryExecutor { get; set; }

The TDS query executor for direct SQL execution (Phase 3.5). Required when PPDS.Dataverse.Query.Planning.QueryPlanOptions.UseTdsEndpoint is true.

UseTdsEndpoint​

bool UseTdsEndpoint { get; set; }

Whether to use the TDS Endpoint (Phase 3.5).

VariableScope​

VariableScope VariableScope { get; set; }

Optional variable scope for substituting @variable references in WHERE conditions with literal values before FetchXML transpilation.