Package version:

Interface FeedOptions

The feed options and query methods.

interface FeedOptions {
    abortSignal?: AbortSignal;
    accessCondition?: {
        condition: string;
        type: string;
    };
    allowUnboundedNonStreamingQueries?: boolean;
    bufferItems?: boolean;
    bypassIntegratedCache?: boolean;
    continuation?: string;
    continuationToken?: string;
    continuationTokenLimitInKB?: number;
    disableNonStreamingOrderByQuery?: boolean;
    enableScanInQuery?: boolean;
    forceQueryPlan?: boolean;
    initialHeaders?: CosmosHeaders;
    maxDegreeOfParallelism?: number;
    maxIntegratedCacheStalenessInMs?: number;
    maxItemCount?: number;
    partitionKey?: PartitionKey;
    populateIndexMetrics?: boolean;
    populateQueryMetrics?: boolean;
    priorityLevel?: PriorityLevel;
    sessionToken?: string;
    useIncrementalFeed?: boolean;
    vectorSearchBufferSize?: number;
}

Hierarchy (view full)

Properties

abortSignal? accessCondition? allowUnboundedNonStreamingQueries? bufferItems? bypassIntegratedCache? continuation? continuationToken? continuationTokenLimitInKB? disableNonStreamingOrderByQuery? enableScanInQuery? forceQueryPlan? initialHeaders? maxDegreeOfParallelism? maxIntegratedCacheStalenessInMs? maxItemCount? partitionKey? populateIndexMetrics? populateQueryMetrics? priorityLevel? sessionToken? useIncrementalFeed? vectorSearchBufferSize?

Properties

OptionalabortSignal

abortSignal?: AbortSignal

abortSignal to pass to all underlying network requests created by this method call. See https://developer.mozilla.org/en-US/docs/Web/API/AbortController

Example: Cancel a read request

const controller = new AbortController()
const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
controller.abort()

OptionalaccessCondition

accessCondition?: {
    condition: string;
    type: string;
}

Conditions Associated with the request.

Type declaration

  • condition: string

    Conditional HTTP method header value (the _etag field from the last version you read).

  • type: string

    Conditional HTTP method header type (IfMatch or IfNoneMatch).

OptionalallowUnboundedNonStreamingQueries

allowUnboundedNonStreamingQueries?: boolean

Valid only for non streaming order by query. Default: false; When set to true, it allows queries to bypass the default behavior that blocks nonStreaming queries without top or limit clauses.

OptionalbufferItems

bufferItems?: boolean

Enable buffering additional items during queries. Default: false

This will buffer an additional page at a time (multiplied by maxDegreeOfParallelism) from the server in the background. This improves latency by fetching pages before they are needed by the client. If you're draining all of the results from the server, like .fetchAll, you should usually enable this. If you're only fetching one page at a time via continuation token, you should avoid this. If you're draining more than one page, but not the entire result set, it may help improve latency, but it will increase the total amount of RU/s use to serve the entire query (as some pages will be fetched more than once).

OptionalbypassIntegratedCache

bypassIntegratedCache?: boolean

Sets if integrated cache should be bypassed or enabled for the request in Azure CosmosDB service.

Default value is false. By default integrated cache is enabled

Optionalcontinuation

continuation?: string

Opaque token for continuing the enumeration. Default: undefined

Deprecated

Use continuationToken instead.

OptionalcontinuationToken

continuationToken?: string

Opaque token for continuing the enumeration. Default: undefined

OptionalcontinuationTokenLimitInKB

continuationTokenLimitInKB?: number

Limits the size of the continuation token in the response. Default: undefined

Continuation Tokens contain optional data that can be removed from the serialization before writing it out to a header. By default we are capping this to 1kb to avoid long headers (Node.js has a global header size limit). A user may set this field to allow for longer headers, which can help the backend optimize query execution."

OptionaldisableNonStreamingOrderByQuery

disableNonStreamingOrderByQuery?: boolean

Disable the nonStreamingOrderBy query feature in supported query features. Default: false. Set to true to avoid error from an old gateway that doesn't support this feature.

OptionalenableScanInQuery

enableScanInQuery?: boolean

Allow scan on the queries which couldn't be served as indexing was opted out on the requested paths. Default: false

In general, it is best to avoid using this setting. Scans are relatively expensive and take a long time to serve.

OptionalforceQueryPlan

forceQueryPlan?: boolean

This setting forces the query to use a query plan. Default: false

Note: this will disable continuation token support, even for single partition queries.

For queries like aggregates and most cross partition queries, this happens anyway. However, since the library doesn't know what type of query it is until we get back the first response, some optimization can't happen until later.

If this setting is enabled, it will force query plan for the query, which will save some network requests and ensure parallelism can happen. Useful for when you know you're doing cross-partition or aggregate queries.

OptionalinitialHeaders

initialHeaders?: CosmosHeaders

(Advanced use case) Initial headers to start with when sending requests to Cosmos

OptionalmaxDegreeOfParallelism

maxDegreeOfParallelism?: number

The maximum number of concurrent operations that run client side during parallel query execution in the Azure Cosmos DB database service. Negative values make the system automatically decides the number of concurrent operations to run. Default: 0 (no parallelism)

OptionalmaxIntegratedCacheStalenessInMs

maxIntegratedCacheStalenessInMs?: number

Sets the staleness value associated with the request in the Azure CosmosDB service. For requests where the com.azure.cosmos.ConsistencyLevel is com.azure.cosmos.ConsistencyLevel#EVENTUAL or com.azure.cosmos.ConsistencyLevel#SESSION, responses from the integrated cache are guaranteed to be no staler than value indicated by this maxIntegratedCacheStaleness. When the consistency level is not set, this property is ignored.

Default value is null

Cache Staleness is supported in milliseconds granularity. Anything smaller than milliseconds will be ignored.

OptionalmaxItemCount

maxItemCount?: number

Max number of items to be returned in the enumeration operation. Default: undefined (server will defined payload)

Expirimenting with this value can usually result in the biggest performance changes to the query.

The smaller the item count, the faster the first result will be delivered (for non-aggregates). For larger amounts, it will take longer to serve the request, but you'll usually get better throughput for large queries (i.e. if you need 1000 items before you can do any other actions, set maxItemCount to 1000. If you can start doing work after the first 100, set maxItemCount to 100.)

OptionalpartitionKey

partitionKey?: PartitionKey

Limits the query to a specific partition key. Default: undefined

Scoping a query to a single partition can be accomplished two ways:

container.items.query('SELECT * from c', { partitionKey: "foo" }).toArray() container.items.query('SELECT * from c WHERE c.yourPartitionKey = "foo"').toArray()

The former is useful when the query body is out of your control but you still want to restrict it to a single partition. Example: an end user specified query.

OptionalpopulateIndexMetrics

populateIndexMetrics?: boolean

Enable returning index metrics in response headers. Default: false

OptionalpopulateQueryMetrics

populateQueryMetrics?: boolean

Enable returning query metrics in response headers. Default: false

Used for debugging slow or expensive queries. Also increases response size and if you're using a low max header size in Node.js, you can run into issues faster.

OptionalpriorityLevel

priorityLevel?: PriorityLevel

Priority Level (Low/High) for each request. Low priority requests are always throttled before any high priority requests.

Default value is null. By default all requests are of High priority

OptionalsessionToken

sessionToken?: string

Enables/disables getting document container quota related stats for document container read requests.

OptionaluseIncrementalFeed

useIncrementalFeed?: boolean

Note: consider using changeFeed instead.

Indicates a change feed request. Must be set to "Incremental feed", or omitted otherwise. Default: false

OptionalvectorSearchBufferSize

vectorSearchBufferSize?: number

Specifies a custom maximum buffer size for storing final results for nonStreamingOrderBy queries. This value is ignored if the query includes top/offset+limit clauses.

Settings

Member Visibility