Table of Contents

Class DocumentCollection

Namespace
Microsoft.Azure.Documents
Assembly
Microsoft.Azure.Documents.Client.dll

Represents a document collection in the Azure Cosmos DB service. A collection is a named logical container for documents.

public class DocumentCollection : Resource
Inheritance
DocumentCollection
Inherited Members
Extension Methods

Examples

The example below creates a new partitioned collection with 50000 Request-per-Unit throughput. The partition key is the first level 'country' property in all the documents within this collection.

DocumentCollection collection = await client.CreateDocumentCollectionAsync(
    databaseLink,
    new DocumentCollection 
    { 
        Id = "MyCollection",
        PartitionKey = new PartitionKeyDefinition
        {
            Paths = new Collection<string> { "/country" }
        }
    }, 
    new RequestOptions { OfferThroughput = 50000} ).Result;

The example below creates a new collection with OfferThroughput set to 10000.

DocumentCollection collection = await client.CreateDocumentCollectionAsync(
    databaseLink,
    new DocumentCollection { Id = "MyCollection" }, 
    new RequestOptions { OfferThroughput = 10000} ).Result;

The example below creates a new collection with a custom indexing policy.

DocumentCollection collectionSpec = new DocumentCollection { Id ="MyCollection" };
collectionSpec.IndexingPolicy.Automatic = true;
collectionSpec.IndexingPolicy.IndexingMode = IndexingMode.Consistent;
collection = await client.CreateDocumentCollectionAsync(database.SelfLink, collectionSpec);

The example below creates a document of type Book inside this collection.

Document doc = await client.CreateDocumentAsync(collection.SelfLink, new Book { Title = "War and Peace" });

The example below queries for a Database by Id to retrieve the SelfLink.

using Microsoft.Azure.Documents.Linq;
DocumentCollection collection = client.CreateDocumentCollectionQuery(databaseLink).Where(c => c.Id == "myColl").AsEnumerable().FirstOrDefault();
string collectionLink = collection.SelfLink;

The example below deletes this collection.

await client.DeleteDocumentCollectionAsync(collection.SelfLink);

Remarks

A database may contain zero or more named collections and each collection consists of zero or more JSON documents. Being schema-free, the documents in a collection do not need to share the same structure or fields. Since collections are application resources, they can be authorized using either the master key or resource keys. Refer to http://azure.microsoft.com/documentation/articles/documentdb-resources/#collections for more details on collections.

Constructors

DocumentCollection()

Initializes a new instance of the DocumentCollection class for the Azure Cosmos DB service.

public DocumentCollection()

Properties

ConflictResolutionPolicy

Gets or sets the ConflictResolutionPolicy that is used for resolving conflicting writes on documents in different regions, in a collection in the Azure Cosmos DB service.

public ConflictResolutionPolicy ConflictResolutionPolicy { get; set; }

Property Value

ConflictResolutionPolicy

Gets the self-link for conflicts in a collection from the Azure Cosmos DB service.

public string ConflictsLink { get; }

Property Value

string

The self-link for conflicts in a collection.

DefaultTimeToLive

Gets the default time to live in seconds for documents in a collection from the Azure Cosmos DB service.

public int? DefaultTimeToLive { get; set; }

Property Value

int?

It is an optional property. A valid value must be either a nonzero positive integer, '-1', or null. By default, DefaultTimeToLive is set to null meaning the time to live is turned off for the collection. The unit of measurement is seconds. The maximum allowed value is 2147483647.

Examples

The example below disables time-to-live on a collection.

collection.DefaultTimeToLive = null;

The example below enables time-to-live on a collection. By default, all the documents never expire.

collection.DefaultTimeToLive = -1;

The example below enables time-to-live on a collection. By default, the document will expire after 1000 seconds since its last write time.

collection.DefaultTimeToLive = 1000;

Remarks

The DefaultTimeToLive will be applied to all the documents in the collection as the default time-to-live policy. The individual document could override the default time-to-live policy by setting its TimeToLive.

When the DefaultTimeToLive is null, the time-to-live will be turned off for the collection. It means all the documents will never expire. The individual document's TimeToLive will be disregarded.

When the DefaultTimeToLive is '-1', the time-to-live will be turned on for the collection. By default, all the documents will never expire. The individual document could be given a specific time-to-live value by setting its TimeToLive. The document's TimeToLive will be honored, and the expired documents will be deleted in background.

When the DefaultTimeToLive is a nonzero positive integer, the time-to-live will be turned on for the collection. And a default time-to-live in seconds will be applied to all the documents. A document will be expired after the specified DefaultTimeToLive value in seconds since its last write time. The individual document could override the default time-to-live policy by setting its TimeToLive. Please refer to the TimeToLive for more details about evaluating the final time-to-live policy of a document.

See Also

Gets the self-link for documents in a collection from the Azure Cosmos DB service.

public string DocumentsLink { get; }

Property Value

string

The self-link for documents in a collection.

IndexingPolicy

Gets the IndexingPolicy associated with the collection from the Azure Cosmos DB service.

public IndexingPolicy IndexingPolicy { get; set; }

Property Value

IndexingPolicy

The indexing policy associated with the collection.

PartitionKey

Gets or sets PartitionKeyDefinition object in the Azure Cosmos DB service.

public PartitionKeyDefinition PartitionKey { get; set; }

Property Value

PartitionKeyDefinition

PartitionKeyDefinition object.

PartitionKeyRangeStatistics

Gets a collection of PartitionKeyRangeStatistics object in the Azure Cosmos DB service.

public IReadOnlyList<PartitionKeyRangeStatistics> PartitionKeyRangeStatistics { get; }

Property Value

IReadOnlyList<PartitionKeyRangeStatistics>

PartitionKeyRangeStatistics object.

Examples

The following code shows how to log statistics for all partition key ranges as a string:

var collection = await client.ReadDocumentCollectionAsync(
    collectionUri,
    new RequestOptions { PopulatePartitionKeyRangeStatistics = true } );

Console.WriteLine(collection.PartitionKeyRangeStatistics.ToString());

To log individual partition key range statistics, use the following code:

var collection = await client.ReadDocumentCollectionAsync(
    collectionUri,
    new RequestOptions { PopulatePartitionKeyRangeStatistics = true } );

foreach(var partitionKeyRangeStatistics in collection.PartitionKeyRangeStatistics)
{
    Console.WriteLine(partitionKeyRangeStatistics.PartitionKeyRangeId);
    Console.WriteLine(partitionKeyRangeStatistics.DocumentCount);
    Console.WriteLine(partitionKeyRangeStatistics.SizeInKB);

    foreach(var partitionKeyStatistics in partitionKeyRangeStatistics.PartitionKeyStatistics)
    {
        Console.WriteLine(partitionKeyStatistics.PartitionKey);
        Console.WriteLine(partitionKeyStatistics.SizeInKB);
    }
 }

The output will look something like that: "statistics": [ {"id":"0","sizeInKB":1410184,"documentCount":42807,"partitionKeys":[]}, {"id":"1","sizeInKB":3803113,"documentCount":150530,"partitionKeys":[{"partitionKey":["4009696"],"sizeInKB":3731654}]}, {"id":"2","sizeInKB":1447855,"documentCount":59056,"partitionKeys":[{"partitionKey":["4009633"],"sizeInKB":2861210},{"partitionKey":["4004207"],"sizeInKB":2293163}]}, {"id":"3","sizeInKB":1026254,"documentCount":44241,"partitionKeys":[]}, {"id":"4","sizeInKB":3250973,"documentCount":124959,"partitionKeys":[]} ]

Remarks

This is reported based on a sub-sampling of partition keys within the collection and hence these are approximate. If your partition keys are below 1GB of storage, they may not show up in the reported statistics.

See Also

Gets the self-link for stored procedures in a collection from the Azure Cosmos DB service.

public string StoredProceduresLink { get; }

Property Value

string

The self-link for stored procedures in a collection.

TimeToLivePropertyPath

Gets or sets the time to live base timestamp property path.

public string TimeToLivePropertyPath { get; set; }

Property Value

string

It is an optional property. This property should be only present when DefaultTimeToLive is set. When this property is present, time to live for a document is decided based on the value of this property in document. By default, TimeToLivePropertyPath is set to null meaning the time to live is based on the _ts property in document.

Gets the self-link for triggers in a collection from the Azure Cosmos DB service.

public string TriggersLink { get; }

Property Value

string

The self-link for triggers in a collection.

UniqueKeyPolicy

Gets or sets the UniqueKeyPolicy that guarantees uniqueness of documents in collection in the Azure Cosmos DB service.

public UniqueKeyPolicy UniqueKeyPolicy { get; set; }

Property Value

UniqueKeyPolicy

Gets the self-link for user defined functions in a collection from the Azure Cosmos DB service.

public string UserDefinedFunctionsLink { get; }

Property Value

string

The self-link for user defined functions in a collection.

See Also

IndexingPolicy
PartitionKeyDefinition
Document
Database
Offer