@azure/cosmos 4.8.0 → 4.9.0

package/dist/browser/queryExecutionContext/parallelQueryExecutionContextBase.d.ts

@@ -1,10 +1,12 @@
-import type { ClientContext } from "../ClientContext.js";
 import type { FeedOptions, Response } from "../request/index.js";
 import type { PartitionedQueryExecutionInfo } from "../request/ErrorResponse.js";
-import { DocumentProducer } from "./documentProducer.js";
 import type { ExecutionContext } from "./ExecutionContext.js";
 import type { SqlQuerySpec } from "./SqlQuerySpec.js";
+import { DocumentProducer } from "./documentProducer.js";
+import { TargetPartitionRangeManager } from "./queryFilteringStrategy/TargetPartitionRangeManager.js";
+import type { QueryProcessingStrategy } from "./queryProcessingStrategy/QueryProcessingStrategy.js";
 import { DiagnosticNodeInternal } from "../diagnostics/DiagnosticNodeInternal.js";
+import type { ClientContext } from "../ClientContext.js";
 /** @hidden */
 export declare enum ParallelQueryExecutionContextBaseStates {
     started = "started",
@@ -13,24 +15,29 @@ export declare enum ParallelQueryExecutionContextBaseStates {
 }
 /** @hidden */
 export declare abstract class ParallelQueryExecutionContextBase implements ExecutionContext {
-    private clientContext;
-    private collectionLink;
-    private query;
-    private options;
-    private partitionedQueryExecutionInfo;
-    private correlatedActivityId;
+    private readonly clientContext;
+    private readonly collectionLink;
+    private readonly query;
+    private readonly options;
+    private readonly partitionedQueryExecutionInfo;
+    private readonly correlatedActivityId;
+    private readonly rangeManager;
+    private readonly queryProcessingStrategy;
+    private readonly documentProducerComparator;
     private err;
     private state;
-    private static STATES;
+    private static readonly STATES;
     private routingProvider;
-    protected sortOrders: any;
-    private requestContinuation;
+    private readonly requestContinuation;
     private respHeaders;
-    private unfilledDocumentProducersQueue;
-    private bufferedDocumentProducersQueue;
+    private readonly unfilledDocumentProducersQueue;
+    private readonly bufferedDocumentProducersQueue;
     private buffer;
-    private sem;
-    private diagnosticNodeWrapper;
+    private partitionDataPatchMap;
+    private patchCounter;
+    private readonly updatedContinuationRanges;
+    private readonly sem;
+    private readonly diagnosticNodeWrapper;
     /**
      * Provides the ParallelQueryExecutionContextBase.
      * This is the base class that ParallelQueryExecutionContext and OrderByQueryExecutionContext will derive from.
@@ -44,8 +51,133 @@ export declare abstract class ParallelQueryExecutionContextBase implements Execu
      * @param partitionedQueryExecutionInfo - PartitionedQueryExecutionInfo
      * @hidden
      */
-    constructor(clientContext: ClientContext, collectionLink: string, query: string | SqlQuerySpec, options: FeedOptions, partitionedQueryExecutionInfo: PartitionedQueryExecutionInfo, correlatedActivityId: string);
-    protected abstract documentProducerComparator(dp1: DocumentProducer, dp2: DocumentProducer): number;
+    constructor(clientContext: ClientContext, collectionLink: string, query: string | SqlQuerySpec, options: FeedOptions, partitionedQueryExecutionInfo: PartitionedQueryExecutionInfo, correlatedActivityId: string, rangeManager: TargetPartitionRangeManager, queryProcessingStrategy: QueryProcessingStrategy, documentProducerComparator: (dp1: DocumentProducer, dp2: DocumentProducer) => number);
+    /**
+     * Determine if there are still remaining resources to processs based on the value of the continuation
+     * token or the elements remaining on the current batch in the QueryIterator.
+     * @returns true if there is other elements to process in the ParallelQueryExecutionContextBase.
+     */
+    hasMoreResults(): boolean;
+    /**
+     * Fetches more results from the query execution context.
+     * @param diagnosticNode - Optional diagnostic node for tracing.
+     * @returns A promise that resolves to the fetched results.
+     * @hidden
+     */
+    fetchMore(diagnosticNode?: DiagnosticNodeInternal): Promise<Response<any>>;
+    /**
+     * Processes buffered document producers
+     * @returns A promise that resolves when processing is complete.
+     */
+    private processBufferedDocumentProducers;
+    /**
+     * Processes a single document producer using template method pattern.
+     * Common structure with query-specific processing delegated to subclasses.
+     */
+    private processDocumentProducer;
+    /**
+     * Fetches data from a document producer - implemented by subclasses.
+     */
+    protected abstract fetchFromProducer(producer: DocumentProducer): Promise<Response<any>>;
+    /**
+     * Handles partition mapping updates - implemented in base class using template method pattern.
+     * Child classes provide query-specific parameters through abstract methods.
+     */
+    private handlePartitionMapping;
+    /**
+     * Gets the continuation token to use - implemented by subclasses.
+     */
+    private getContinuationToken;
+    /**
+     * Determines if buffered producers should continue to be processed based on query-specific rules.
+     * @param isUnfilledQueueEmpty - Whether the unfilled queue is empty
+     */
+    protected abstract shouldProcessBufferedProducers(isUnfilledQueueEmpty: boolean): boolean;
+    /**
+     * Updates partition mapping - creates new entry or merges with existing for ORDER BY queries.
+     */
+    private updatePartitionMapping;
+    /**
+     * Checks if the unfilled queue is empty (used by ORDER BY for processing control).
+     */
+    protected isUnfilledQueueEmpty(): boolean;
+    /**
+     * Initializes document producers and fills the priority queue.
+     * Handles both continuation token and fresh query scenarios.
+     */
+    private _initializeDocumentProducers;
+    /**
+     * Creates document producers from continuation token scenario.
+     */
+    private _createDocumentProducersFromContinuation;
+    /**
+     * Creates document producers from fresh query scenario (no continuation token).
+     */
+    private _createDocumentProducersFromFresh;
+    /**
+     * Creates a document producer from a range token pair (continuation token scenario).
+     */
+    private _createDocumentProducerFromRangeTokenPair;
+    /**
+     * Enqueues document producers into the unfilled queue.
+     */
+    private _enqueueDocumentProducers;
+    /**
+     * Checks if there are buffered document producers ready for processing.
+     * Encapsulates queue size checking.
+     */
+    private hasBufferedProducers;
+    /**
+     * Gets the next buffered document producer for processing.
+     * Encapsulates queue dequeuing logic.
+     */
+    private getNextBufferedProducer;
+    /**
+     * Adds items to the result buffer. Handles both single items and arrays.
+     */
+    private addToBuffer;
+    /**
+     * Moves a producer to the unfilled queue for later processing.
+     */
+    private moveToUnfilledQueue;
+    /**
+     * Re-queues a producer to the buffered queue for further processing.
+     */
+    private requeueProducer;
+    /**
+     * Compares two document producers based on their partition key ranges and EPK values.
+     * Primary comparison: minInclusive values for left-to-right range traversal
+     * Secondary comparison: EPK ranges when minInclusive values are identical
+     * @param a - First document producer
+     * @param b - Second document producer
+     * @returns Comparison result for priority queue ordering
+     * @hidden
+     */
+    private compareDocumentProducersByRange;
+    /**
+     * Detects partition splits/merges by analyzing parsed continuation token ranges and comparing with current topology
+     * @param parsed - The continuation token containing range mappings to analyze
+     * @returns Array of processed ranges with EPK info
+     */
+    private _handlePartitionRangeChanges;
+    /**
+     * Parses the continuation token based on query type
+     * @param continuationToken - The continuation token string to parse
+     * @returns Parsed continuation token object (ORDER BY or Parallel query token)
+     * @throws ErrorResponse when continuation token is malformed or cannot be parsed
+     */
+    private _parseContinuationToken;
+    /**
+     * Handles partition merge scenario for continuation token ranges
+     */
+    private _handleContinuationTokenMerge;
+    /**
+     * Handles partition split scenario for continuation token ranges
+     */
+    private _handleContinuationTokenSplit;
+    /**
+     * Handles partition merge scenario for continuation token ranges
+     */
     private _mergeWithActiveResponseHeaders;
     private _getAndResetActiveResponseHeaders;
     private getDiagnosticNode;
@@ -55,31 +187,33 @@ export declare abstract class ParallelQueryExecutionContextBase implements Execu
      */
     private _getReplacementPartitionKeyRanges;
     private _enqueueReplacementDocumentProducers;
-    private static _needPartitionKeyRangeCacheRefresh;
+    private _updateContinuationTokenOnPartitionChange;
     /**
-     * Determine if there are still remaining resources to processs based on the value of the continuation
-     * token or the elements remaining on the current batch in the QueryIterator.
-     * @returns true if there is other elements to process in the ParallelQueryExecutionContextBase.
+     * Creates a QueryRangeWithContinuationToken object from a DocumentProducer.
+     * Uses the DocumentProducer's target partition key range and continuation token.
+     * @param documentProducer - The DocumentProducer to convert
+     * @returns QueryRangeWithContinuationToken object for token operations
      */
-    hasMoreResults(): boolean;
+    private _createQueryRangeWithContinuationToken;
+    private static _needPartitionKeyRangeCacheRefresh;
     /**
      * Creates target partition range Query Execution Context
      */
     private _createTargetPartitionQueryExecutionContext;
-    protected drainBufferedItems(): Promise<Response<any>>;
+    private drainBufferedItems;
     /**
      * Buffers document producers based on the maximum degree of parallelism.
      * Moves document producers from the unfilled queue to the buffered queue.
      * @param diagnosticNode - The diagnostic node for logging and tracing.
      * @returns A promise that resolves when buffering is complete.
      */
-    protected bufferDocumentProducers(diagnosticNode?: DiagnosticNodeInternal): Promise<void>;
+    private bufferDocumentProducers;
     /**
      * Drains the buffer of filled document producers and appends their items to the main buffer.
-     * @param isOrderBy - Indicates if the query is an order by query.
+     * Uses template method pattern - delegates actual processing to subclasses.
      * @returns A promise that resolves when the buffer is filled.
      */
-    protected fillBufferFromBufferQueue(isOrderBy?: boolean): Promise<void>;
+    private fillBufferFromBufferQueue;
     private updateStates;
 }
 //# sourceMappingURL=parallelQueryExecutionContextBase.d.ts.map

package/dist/browser/queryExecutionContext/parallelQueryExecutionContextBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parallelQueryExecutionContextBase.d.ts","sourceRoot":"","sources":["../../../src/queryExecutionContext/parallelQueryExecutionContextBase.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAIjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EACL,sBAAsB,EAEvB,MAAM,0CAA0C,CAAC;AAKlD,cAAc;AACd,oBAAY,uCAAuC;IACjD,OAAO,YAAY;IACnB,UAAU,eAAe;IACzB,KAAK,UAAU;CAChB;AAED,cAAc;AACd,8BAAsB,iCAAkC,YAAW,gBAAgB;IA+B/E,OAAO,CAAC,aAAa;IACrB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,6BAA6B;IACrC,OAAO,CAAC,oBAAoB;IAnC9B,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,MAAM,CAAC,MAAM,CAA2C;IAChE,OAAO,CAAC,eAAe,CAA0B;IACjD,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC;IAC1B,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,8BAA8B,CAAkC;IACxE,OAAO,CAAC,8BAA8B,CAAkC;IAExE,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,qBAAqB,CAG3B;IACF;;;;;;;;;;;;OAYG;gBAEO,aAAa,EAAE,aAAa,EAC5B,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,MAAM,GAAG,YAAY,EAC5B,OAAO,EAAE,WAAW,EACpB,6BAA6B,EAAE,6BAA6B,EAC5D,oBAAoB,EAAE,MAAM;IA4FtC,SAAS,CAAC,QAAQ,CAAC,0BAA0B,CAC3C,GAAG,EAAE,gBAAgB,EACrB,GAAG,EAAE,gBAAgB,GACpB,MAAM;IAET,OAAO,CAAC,+BAA+B;IAIvC,OAAO,CAAC,iCAAiC;IAMzC,OAAO,CAAC,iBAAiB;YAIX,wBAAwB;IAWtC;;OAEG;YACW,iCAAiC;YAgBjC,oCAAoC;IAkDlD,OAAO,CAAC,MAAM,CAAC,kCAAkC;IASjD;;;;OAIG;IACI,cAAc,IAAI,OAAO;IAOhC;;OAEG;IACH,OAAO,CAAC,2CAA2C;cAuCnC,kBAAkB,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAkC5D;;;;;OAKG;cACa,uBAAuB,CAAC,cAAc,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsG/F;;;;OAIG;cACa,yBAAyB,CAAC,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqEpF,OAAO,CAAC,YAAY;CAmBrB"}
+{"version":3,"file":"parallelQueryExecutionContextBase.d.ts","sourceRoot":"","sources":["../../../src/queryExecutionContext/parallelQueryExecutionContextBase.ts"],"names":[],"mappings":"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"}