Class RequestOptions
Encapsulates options that can be specified for different requests issued to the Azure Cosmos DB service.
public sealed class RequestOptions- Inheritance
-
RequestOptions
- Inherited Members
- Extension Methods
Remarks
Some of these options are valid for specific operations only. For example,
PreTriggerInclude can be used only on create, replace and delete operations on a Document or Attachment.
ETag, while valid on Replace* and Delete* operations, would have no impact on a Read*, CreateQuery* or Create* operations.
Constructors
RequestOptions()
public RequestOptions()Properties
AccessCondition
Gets or sets the condition (ETag) associated with the request in the Azure Cosmos DB service.
public AccessCondition AccessCondition { get; set; }Property Value
- AccessCondition
The condition (ETag) associated with the request.
Examples
The following example shows how to use RequestOptions with ReplaceDocumentAsync(string, object, RequestOptions, CancellationToken) to specify the set of AccessCondition to be used when updating a document
// If ETag is current, then this will succeed. Otherwise the request will fail with HTTP 412 Precondition Failure
await client.ReplaceDocumentAsync(
readCopyOfBook.SelfLink,
new Book { Title = "Moby Dick", Price = 14.99 },
new RequestOptions
{
AccessCondition = new AccessCondition
{
Condition = readCopyOfBook.ETag,
Type = AccessConditionType.IfMatch
}
});Remarks
Most commonly used with the Delete* and Replace* methods of DocumentClient such as ReplaceDocumentAsync(Document, RequestOptions, CancellationToken) or ReplaceDocumentAsync(string, object, RequestOptions, CancellationToken) methods, but can be used with other methods like ReadDocumentAsync(string, RequestOptions, CancellationToken) for caching scenarios.
ConsistencyLevel
Gets or sets the consistency level required for the request in the Azure Cosmos DB service.
public ConsistencyLevel? ConsistencyLevel { get; set; }Property Value
- ConsistencyLevel?
The consistency level required for the request.
Examples
This example uses RequestOptions to override the consistency level to Eventual for this single Read operation.
Document doc = client.ReadDocumentAsync(documentLink, new RequestOptions { ConsistencyLevel = ConsistencyLevel.Eventual });Remarks
Azure Cosmos DB offers 5 different consistency levels. Strong, Bounded Staleness, Session, Consistent Prefix and Eventual - in order of strongest to weakest consistency. ConnectionPolicy
While this is set at a database account level, Azure Cosmos DB allows a developer to override the default consistency level for each individual request.
- See Also
DisableRUPerMinuteUsage
Gets or sets the DisableRUPerMinuteUsage for the current request in the Azure Cosmos DB service.
public bool DisableRUPerMinuteUsage { get; set; }Property Value
Remarks
DisableRUPerMinuteUsage is used to enable/disable Request Units(RUs)/minute capacity to serve the request if regular provisioned RUs/second is exhausted.
EnableScriptLogging
Gets or sets the EnableScriptLogging for the current request in the Azure Cosmos DB service.
public bool EnableScriptLogging { get; set; }Property Value
Examples
The following example shows how to enable logging in stored procedures using EnableScriptLogging.
var response = await client.ExecuteStoredProcedureAsync(
document.SelfLink,
new RequestOptions { EnableScriptLogging = true } );
Console.WriteLine(response.ScriptLog);To log, use the following in store procedure:
console.log("This is trace log");Remarks
EnableScriptLogging is used to enable/disable logging in JavaScript stored procedures. By default script logging is disabled. The log can also be accessible in response header (x-ms-documentdb-script-log-results).
- See Also
IndexingDirective
Gets or sets the indexing directive (Include or Exclude) for the request in the Azure Cosmos DB service.
public IndexingDirective? IndexingDirective { get; set; }Property Value
- IndexingDirective?
The indexing directive to use with a request.
Examples
The following example shows how to explicitly index a document in a collection with automatic indexing turned off.
client.CreateDocumentAsync(defaultCollection.SelfLink,
new { id = "AndersenFamily", isRegistered = true },
new RequestOptions { IndexingDirective = IndexingDirective.Include });- See Also
JsonSerializerSettings
Gets or sets the JsonSerializerSettings for the current request used to deserialize the document. If null, uses the default serializer settings set up in the DocumentClient.
public JsonSerializerSettings JsonSerializerSettings { get; set; }Property Value
- JsonSerializerSettings
OfferEnableRUPerMinuteThroughput
Gets or sets the OfferEnableRUPerMinuteThroughput for a collection in the Azure Cosmos DB service
public bool OfferEnableRUPerMinuteThroughput { get; set; }Property Value
- bool
Represents Request Units(RU)/Minute throughput is enabled/disabled for a collection in the Azure Cosmos DB service.
Examples
The followng example shows how to create a collection with RU/Minute throughput offer.
await client.CreateDocumentCollectionAsync(
database.SelfLink,
new DocumentCollection { Id = "newcoll" },
new RequestOptions { OfferThroughput = 4000, OfferEnableRUPerMinuteThroughput = true });Remarks
This option is only valid when creating a document collection.
- See Also
OfferThroughput
Gets or sets the offer throughput provisioned for a collection in measurement of Requests-per-Unit in the Azure Cosmos DB service.
public int? OfferThroughput { get; set; }Property Value
- int?
The provisioned throughtput for this offer.
Examples
The followng example shows how to create a collection with offer throughtput.
await client.CreateDocumentCollectionAsync(
database.SelfLink,
new DocumentCollection { Id = "newcoll" },
new RequestOptions { OfferThroughput = 50000 });Remarks
This option is only valid when creating a document collection.
Refer to http://azure.microsoft.com/documentation/articles/documentdb-performance-levels/ for details on provision offer throughput.
- See Also
OfferType
Gets or sets the offer type for the resource in the Azure Cosmos DB service.
public string OfferType { get; set; }Property Value
- string
The offer type value.
Examples
The followng example shows how to create a collection with the S2 offer.
await client.CreateDocumentCollectionAsync(
database.SelfLink,
new DocumentCollection { Id = "newcoll" },
new RequestOptions { OfferType = "S2" });Remarks
This option is only valid when creating a document collection.
Refer to http://azure.microsoft.comdocumentation/articles/documentdb-performance-levels/ for the list of valid offer types.
- See Also
PartitionKey
Gets or sets the PartitionKey for the current request in the Azure Cosmos DB service.
public PartitionKey PartitionKey { get; set; }Property Value
Examples
The following example shows how to read a document in a partitioned collection using PartitionKey. The example assumes the collection is created with a PartitionKeyDefinition of the 'id' property in all the documents.
await client.ReadDocumentAsync(
document.SelfLink,
new RequestOptions { PartitionKey = new PartitionKey(document.Id) } );Remarks
Partition key is used to identify the target partition for this request. It must be set on read and delete operations for all document requests; create, read, update and delete operations for all document attachment requests; and execute operation on stored producedures.
For create and update operations on documents, the partition key is optional. When absent, the client library will
extract the partition key from the document before sending the request to the server.
</p>
- See Also
PopulatePartitionKeyRangeStatistics
Gets or sets the PopulatePartitionKeyRangeStatistics for document collection read requests in the Azure Cosmos DB service.
public bool PopulatePartitionKeyRangeStatistics { get; set; }Property Value
Examples
For usage, please refer to the example in PartitionKeyRangeStatistics.
Remarks
PopulatePartitionKeyRangeStatistics is used to enable/disable getting partition key range statistics.
PopulateQuotaInfo
Gets or sets the PopulateQuotaInfo for document collection read requests in the Azure Cosmos DB service.
public bool PopulateQuotaInfo { get; set; }Property Value
Remarks
PopulateQuotaInfo is used to enable/disable getting document collection quota related stats for document collection read requests.
PostTriggerInclude
Gets or sets the trigger to be invoked after the operation in the Azure Cosmos DB service.
public IList<string> PostTriggerInclude { get; set; }Property Value
Examples
The following example shows how to use RequestOptions to include a PostTrigger to execute after persisting the document.
client.CreateDocumentAsync(collection.SelfLink,
new { id = "AndersenFamily", isRegistered = true },
new RequestOptions { PostTriggerInclude = new List<string> { "updateMetadata" } });Remarks
Only valid when used with Create, Replace and Delete methods for documents. Currently only one PreTrigger is permitted per operation.
PreTriggerInclude
Gets or sets the trigger to be invoked before the operation in the Azure Cosmos DB service.
public IList<string> PreTriggerInclude { get; set; }Property Value
Examples
The following example shows how to use RequestOptions to include a PreTrigger to execute before persisting the document.
client.CreateDocumentAsync(collection.SelfLink,
new { id = "AndersenFamily", isRegistered = true },
new RequestOptions { PreTriggerInclude = new List<string> { "validateDocumentContents" } });Remarks
Only valid when used with Create, Replace and Delete methods for documents. Currently only one PreTrigger is permitted per operation.
ResourceTokenExpirySeconds
Gets or sets the expiry time for resource token. Used when creating/updating/reading permissions in the Azure Cosmos DB service.
public int? ResourceTokenExpirySeconds { get; set; }Property Value
- int?
The expiry time in seconds for the resource token.
Remarks
When working with Azure Cosmos DB Users and Permissions, the way to instantiate an instance of DocumentClient is to get the Token for the resource the User wants to access and pass this to the authKeyOrResourceToken parameter of DocumentClient constructor
When requesting this Token, a RequestOption for ResourceTokenExpirySeconds can be used to set the length of time to elapse before the token expires. This value can range from 10 seconds, to 5 hours (or 18,000 seconds) The default value for this, should none be supplied is 1 hour (or 3,600 seconds).
- See Also
SessionToken
Gets or sets the token for use with session consistency in the Azure Cosmos DB service.
public string SessionToken { get; set; }Property Value
- string
The token for use with session consistency.
Examples
This example shows how you can retrieve the SessionToken from a ResourceResponse<TResource> and then use it on a different instance of DocumentClient within RequestOptions This example assumes that the each instance of the client is running from code within a different AppDomain, such as on different nodes in the case of multiple node web application
string sessionToken;
string docSelfLink;
using (DocumentClient client = new DocumentClient(new Uri(""), ""))
{
ResourceResponse<Document> response = client.CreateDocumentAsync(collection.SelfLink, new { id = "an id", value = "some value" }).Result;
sessionToken = response.SessionToken;
Document created = response.Resource;
docSelfLink = created.SelfLink;
}
using (DocumentClient client = new DocumentClient(new Uri(""), ""))
{
ResourceResponse<Document> read = client.ReadDocumentAsync(docSelfLink, new RequestOptions { SessionToken = sessionToken }).Result;
}Remarks
One of the ConsistencyLevel for Azure Cosmos DB is Session. In fact, this is the deault level applied to accounts.
When working with Session consistency, each new write request to Azure Cosmos DB is assigned a new SessionToken. The DocumentClient will use this token internally with each read/query request to ensure that the set consistency level is maintained.
In some scenarios you need to manage this Session yourself; Consider a web application with multiple nodes, each node will have its own instance of DocumentClient If you wanted these nodes to participate in the same session (to be able read your own writes consistently across web tiers) you would have to send the SessionToken from ResourceResponse<TResource> of the write action on one node to the client tier, using a cookie or some other mechanism, and have that token flow back to the web tier for subsequent reads. If you are using a round-robin load balancer which does not maintain session affinity between requests, such as the Azure Load Balancer, the read could potentially land on a different node to the write request, where the session was created.
If you do not flow the Azure Cosmos DB SessionToken across as described above you could end up with inconsistent read results for a period of time.
- See Also
SharedOfferThroughput
Gets or sets shared offer throughput on a collection.
[Obsolete("Deprecated")]
public int? SharedOfferThroughput { get; set; }Property Value
- int?
Examples
The followng example shows how to create a collection with offer throughtput.
await client.CreateDocumentCollectionAsync(
database.SelfLink,
new DocumentCollection { Id = "newcoll" },
new RequestOptions { SharedOfferThroughput = 50000 });Remarks
This option is only valid when creating a document collection that shares offer throughput provisioned at database level. Specifies maximum shared throughput available for collection in the absence of contention. This value should be less than the throughput specified at database level.