FeedOptions interface

Package:

@azure/cosmos

The feed options and query methods.

Extends

SharedOptions

Properties

accessCondition	Conditions Associated with the request.
allowUnboundedNonStreamingQueries	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.
bufferItems	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).
continuation	Opaque token for continuing the enumeration. Default: undefined
continuationToken	Opaque token for continuing the enumeration. Default: undefined
continuationTokenLimitInKB	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."
disableNonStreamingOrderByQuery	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.
enableScanInQuery	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.
forceQueryPlan	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.
maxDegreeOfParallelism	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)
maxItemCount	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.)
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.
populateIndexMetrics	Enable returning index metrics in response headers. Default: false
populateQueryMetrics	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.
useIncrementalFeed	Note: consider using changeFeed instead. Indicates a change feed request. Must be set to "Incremental feed", or omitted otherwise. Default: false
vectorSearchBufferSize	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.

Inherited Properties

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()
bypassIntegratedCache	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
initialHeaders	(Advanced use case) Initial headers to start with when sending requests to Cosmos
maxIntegratedCacheStalenessInMs	Sets the staleness value associated with the request in the Azure CosmosDB service. For requests where the <xref:com.azure.cosmos.ConsistencyLevel> is <xref:com.azure.cosmos.ConsistencyLevel%23EVENTUAL> or <xref:com.azure.cosmos.ConsistencyLevel%23SESSION>, 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.
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
sessionToken	Enables/disables getting document container quota related stats for document container read requests.

Property Details

accessCondition

Conditions Associated with the request.

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

Property Value

{ condition: string, type: string }

allowUnboundedNonStreamingQueries

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.

allowUnboundedNonStreamingQueries?: boolean

Property Value

boolean

bufferItems

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

bufferItems?: boolean

Property Value

boolean

continuation

Warning

This API is now deprecated.

Use continuationToken instead.

Opaque token for continuing the enumeration. Default: undefined

continuation?: string

Property Value

string

continuationToken

Opaque token for continuing the enumeration. Default: undefined

continuationToken?: string

Property Value

string

continuationTokenLimitInKB

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."

continuationTokenLimitInKB?: number

Property Value

number

disableNonStreamingOrderByQuery

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.

disableNonStreamingOrderByQuery?: boolean

Property Value

boolean

enableScanInQuery

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.

enableScanInQuery?: boolean

Property Value

boolean

forceQueryPlan

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.

forceQueryPlan?: boolean

Property Value

boolean

maxDegreeOfParallelism

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)

maxDegreeOfParallelism?: number

Property Value

number

maxItemCount

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

maxItemCount?: number

Property Value

number

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.

partitionKey?: PartitionKey

Property Value

PartitionKey

populateIndexMetrics

Enable returning index metrics in response headers. Default: false

populateIndexMetrics?: boolean

Property Value

boolean

populateQueryMetrics

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.

populateQueryMetrics?: boolean

Property Value

boolean

useIncrementalFeed

Note: consider using changeFeed instead.

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

useIncrementalFeed?: boolean

Property Value

boolean

vectorSearchBufferSize

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.

vectorSearchBufferSize?: number

Property Value

number

Inherited Property Details

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

abortSignal?: AbortSignal

Property Value

AbortSignal

Inherited From SharedOptions.abortSignal

bypassIntegratedCache

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

bypassIntegratedCache?: boolean

Property Value

boolean

Inherited From SharedOptions.bypassIntegratedCache

initialHeaders

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

initialHeaders?: CosmosHeaders

Property Value

CosmosHeaders

Inherited From SharedOptions.initialHeaders

maxIntegratedCacheStalenessInMs

Sets the staleness value associated with the request in the Azure CosmosDB service. For requests where the <xref:com.azure.cosmos.ConsistencyLevel> is <xref:com.azure.cosmos.ConsistencyLevel%23EVENTUAL> or <xref:com.azure.cosmos.ConsistencyLevel%23SESSION>, 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.

maxIntegratedCacheStalenessInMs?: number

Property Value

number

Inherited From SharedOptions.maxIntegratedCacheStalenessInMs

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

priorityLevel?: PriorityLevel

Property Value

PriorityLevel

Inherited From SharedOptions.priorityLevel

sessionToken

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

sessionToken?: string

Property Value

string

Inherited From SharedOptions.sessionToken