Impostare automaticamente come scaduti i dati nelle raccolte di Cosmos DB usando la durata (TTL)Expire data in Azure Cosmos DB collections automatically with time to live

Le applicazioni posso produrre e archiviare grandi quantità di dati.Applications can produce and store vast amounts of data. Alcuni di questi, come i dati eventi generati da computer, i registri e le informazioni sulle sessioni utente sono utili per un periodo di tempo limitato.Some of this data, like machine generated event data, logs, and user session information is only useful for a finite period of time. Quando i dati eccedono le esigenze dell'applicazione è possibile eliminarli e ridurre le risorse di archiviazione necessarie per l'applicazione.Once the data becomes surplus to the needs of the application it is safe to purge this data and reduce the storage needs of an application.

Con l'impostazione della durata (TTL), Microsoft Azure Cosmos DB offre la possibilità di eliminare automaticamente i documenti dal database dopo un periodo di tempo determinato.With "time to live" or TTL, Microsoft Azure Cosmos DB provides the ability to have documents automatically purged from the database after a period of time. La durata predefinita può essere impostata a livello di raccolta ed è possibile eseguirne l'override in base ai singoli documenti.The default time to live can be set at the collection level, and overridden on a per-document basis. Quando il valore di TTL è impostato, come impostazione predefinita di una raccolta o a livello di documento, Cosmos DB rimuove automaticamente i documenti esistenti dopo un numero di secondi dall'ultima modifica pari a tale valore.Once TTL is set, either as a collection default or at a document level, Cosmos DB will automatically remove documents that exist after that period of time, in seconds, since they were last modified.

In Cosmos DB la durata usa la differenza dall'ora dell'ultima modifica al documento.Time to live in Cosmos DB uses an offset against when the document was last modified. A tale scopo usa il campo _ts che esiste in ogni documento.To do this it uses the _ts field which exists on every document. Il campo _ts è un timestamp Epoch di tipo Unix che rappresenta la data e l'oraThe _ts field is a unix-style epoch timestamp representing the date and time. e il campo _ts viene aggiornato ogni volta che si modifica un documento.The _ts field is updated every time a document is modified.

Comportamento di TTLTTL behavior

La funzionalità TTL è controllata dalle proprietà TTL a livello di raccolta e a livello di documento.The TTL feature is controlled by TTL properties at two levels - the collection level and the document level. I valori sono espressi in secondi e vengono trattati come differenziale dal _ts dell'ultima modifica al documento.The values are set in seconds and are treated as a delta from the _ts that the document was last modified at.

  1. DefaultTTL per la raccolta:DefaultTTL for the collection

    • Se non è presente o è impostata su Null, i documenti non vengono eliminati automaticamente.If missing (or set to null), documents are not deleted automatically.
    • Se è presente e il valore è "-1" = infinito, i documenti non scadono per impostazione predefinita.If present and the value is "-1" = infinite – documents don’t expire by default
    • Se è presente e il valore è un numero "n", i documenti scadono "n" secondi dopo l'ultima modifica.If present and the value is some number ("n") – documents expire "n” seconds after last modification
  2. TTL per i documenti:TTL for the documents:

    • La proprietà è applicabile solo se DefaultTTL è presente per la raccolta padre.Property is applicable only if DefaultTTL is present for the parent collection.
    • Esegue l'override del valore di DefaultTTL per la raccolta padre.Overrides the DefaultTTL value for the parent collection.

Alla scadenza (ttl + _ts <= ora corrente del server), il documento viene contrassegnato come "scaduto".As soon as the document has expired (ttl + _ts <= current server time), the document is marked as "expired”. Da questo momento sui documenti scaduti non è possibile eseguire alcuna operazione e vengono esclusi dai risultati delle query.No operation will be allowed on these documents after this time and they will be excluded from the results of any queries performed. I documenti vengono eliminati fisicamente dal sistema e vengono eliminati in background in base alle esigenze in un secondo momento.The documents are physically deleted in the system, and are deleted in the background opportunistically at a later time. L'operazione non utilizza le unità richiesta (UR) del budget della raccolta.This does not consume any Request Units (RUs) from the collection budget.

La logica precedente può essere illustrata in questa matrice:The above logic can be shown in the following matrix:

DefaultTTL mancante o non impostata nella raccoltaDefaultTTL missing/not set on the collection DefaultTTL = -1 nella raccoltaDefaultTTL = -1 on collection DefaultTTL = n nella raccoltaDefaultTTL = "n" on collection
TTL mancante nel documentoTTL Missing on document Non viene eseguito l'override a livello di documento, perché sia il documento che la raccolta sono privi di TTL.Nothing to override at document level since both the document and collection have no concept of TTL. I documenti in questa raccolta non scadono.No documents in this collection will expire. I documenti nella raccolta scadono al termine dell'intervallo n.The documents in this collection will expire when interval n elapses.
Durata TTL = -1 nel documentoTTL = -1 on document Non viene eseguito l'override a livello di documento, perché la raccolta non definisce la proprietà DefaultTTL di cui è possibile eseguire l'override a livello di documento.Nothing to override at the document level since the collection doesn’t define the DefaultTTL property that a document can override. L'impostazione TTL a livello di documento non viene interpretata dal sistema.TTL on a document is un-interpreted by the system. I documenti in questa raccolta non scadono.No documents in this collection will expire. Il documento con TTL =-1 in questa raccolta non scade.The document with TTL=-1 in this collection will never expire. Tutti gli altri documenti scadono dopo l'intervallo di tempo n.All other documents will expire after "n" interval.
TTL = n nel documentoTTL = n on document Non viene eseguito l'override a livello di documento.Nothing to override at the document level. L'impostazione TTL a livello di documento non viene interpretata dal sistema.TTL on a document in un-interpreted by the system. Il documento con TTL = n scade dopo l'intervallo di tempo n, espresso in secondi.The document with TTL = n will expire after interval n, in seconds. Gli altri documenti ereditano l'intervallo -1 e non scadono.Other documents will inherit interval of -1 and never expire. Il documento con TTL = n scade dopo l'intervallo di tempo n, espresso in secondi.The document with TTL = n will expire after interval n, in seconds. Gli altri documenti ereditano l'intervallo n dalla raccolta.Other documents will inherit "n" interval from the collection.

Configurazione di TTLConfiguring TTL

Per impostazione predefinita, la durata è disabilitata in tutte le raccolte di Cosmos DB e in tutti i documenti.By default, time to live is disabled by default in all Cosmos DB collections and on all documents. la durata (TTL) può essere impostata a livello di codice o nel portale di Azure, nella sezione Impostazioni per la raccolta.TTL can be set programmatically or in the Azure portal, in the Settings section for the collection.

Abilitazione di TTLEnabling TTL

Per abilitare la durata (TTL) in una raccolta o nei documenti all'interno di una raccolta, è necessario impostare la proprietà DefaultTTL della raccolta su -1 o su un numero positivo diverso da zero.To enable TTL on a collection, or the documents within a collection, you need to set the DefaultTTL property of a collection to either -1 or a non-zero positive number. Quando DefaultTTL = -1, per impostazione predefinita tutti i documenti nella raccolta hanno durata infinita. Il servizio Cosmos DB deve tuttavia monitorare i documenti per cui viene eseguito l'override di questa impostazione predefinita nella raccolta.Setting the DefaultTTL to -1 means that by default all documents in the collection will live forever but the Cosmos DB service should monitor this collection for documents that have overridden this default.

DocumentCollection collectionDefinition = new DocumentCollection();
collectionDefinition.Id = "orders";
collectionDefinition.PartitionKey.Paths.Add("/customerId");
collectionDefinition.DefaultTimeToLive =-1; //never expire by default

DocumentCollection ttlEnabledCollection = await client.CreateDocumentCollectionAsync(
    UriFactory.CreateDatabaseUri(databaseName),
    collectionDefinition,
    new RequestOptions { OfferThroughput = 20000 });

Configurazione del valore TTL predefinito in una raccoltaConfiguring default TTL on a collection

È possibile configurare una durata predefinita a livello di raccolta.You are able to configure a default time to live at a collection level. Per impostare la durata (TTL) in una raccolta, è necessario specificare un numero positivo diverso da zero che indica il periodo di tempo, espresso in secondi, per la scadenza di tutti i documenti nella raccolta dopo l'ultimo timestamp di modifica del documento (_ts).To set the TTL on a collection, you need to provide a non-zero positive number that indicates the period, in seconds, to expire all documents in the collection after the last modified timestamp of the document (_ts). In alternativa, è possibile impostare il valore predefinito su -1, per fare in modo che tutti i documenti inseriti nella raccolta abbiano una durata illimitata per impostazione predefinita.Or, you can set the default to -1, which implies that all documents inserted in to the collection will live indefinitely by default.

DocumentCollection collectionDefinition = new DocumentCollection();
collectionDefinition.Id = "orders";
collectionDefinition.PartitionKey.Paths.Add("/customerId");
collectionDefinition.DefaultTimeToLive = 90 * 60 * 60 * 24; // expire all documents after 90 days

DocumentCollection ttlEnabledCollection = await client.CreateDocumentCollectionAsync(
    "/dbs/salesdb",
    collectionDefinition,
    new RequestOptions { OfferThroughput = 20000 });

Impostazione di TTL in un documentoSetting TTL on a document

Oltre al valore TTL predefinito in una raccolta è possibile impostare una durata (TTL) specifica a livello di documento.In addition to setting a default TTL on a collection you can set specific TTL at a document level. Questa impostazione esegue l'override dell'impostazione predefinita della raccolta.Doing this will override the default of the collection.

  • Per impostare la durata (TTL) in un documento, è necessario specificare un numero positivo diverso da zero che indica il periodo di tempo, espresso in secondi, per la scadenza del documento dopo l'ultimo timestamp di modifica del documento (_ts).To set the TTL on a document, you need to provide a non-zero positive number which indicates the period, in seconds, to expire the document after the last modified timestamp of the document (_ts).
  • Se il documento non ha il campo TTL, viene applicata l'impostazione predefinita della raccolta.If a document has no TTL field, then the default of the collection will apply.
  • Se la funzionalità TTL è disabilitata a livello di raccolta, il campo TTL del documento viene ignorato finché non viene abilitata nuovamente la funzionalità TTL per la raccolta.If TTL is disabled at the collection level, the TTL field on the document will be ignored until TTL is enabled again on the collection.

Di seguito è riportato un frammento di codice che illustra come impostare la scadenza della durata (TTL) su un documento:Here's a snippet showing how to set the TTL expiration on a document:

// Include a property that serializes to "ttl" in JSON
public class SalesOrder
{
    [JsonProperty(PropertyName = "id")]
    public string Id { get; set; }

    [JsonProperty(PropertyName="cid")]
    public string CustomerId { get; set; }

    // used to set expiration policy
    [JsonProperty(PropertyName = "ttl", NullValueHandling = NullValueHandling.Ignore)]
    public int? TimeToLive { get; set; }

    //...
}

// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder
{
    Id = "SO05",
    CustomerId = "CO18009186470",
    TimeToLive = 60 * 60 * 24 * 30;  // Expire sales orders in 30 days 
};

Estensione di TTL in un documento esistenteExtending TTL on an existing document

Per reimpostare il valore TTL in un documento è possibile eseguire una qualsiasi operazione di scrittura nel documento.You can reset the TTL on a document by doing any write operation on the document. L'operazione imposta _ts sull'ora corrente e fa ripartire il conto alla rovescia per la scadenza del documento, data dal valore di ttl.Doing this will set the _ts to the current time, and the countdown to the document expiry, as set by the ttl, will begin again. Per modificare il valore ttl di un documento, è possibile aggiornare il campo come si fa con qualsiasi altro campo impostabile.If you wish to change the ttl of a document, you can update the field as you can do with any other settable field.

response = await client.ReadDocumentAsync(
    "/dbs/salesdb/colls/orders/docs/SO05"), 
    new RequestOptions { PartitionKey = new PartitionKey("CO18009186470") });

Document readDocument = response.Resource;
readDocument.TimeToLive = 60 * 30 * 30; // update time to live

response = await client.ReplaceDocumentAsync(salesOrder);

Rimozione di TTL da un documentoRemoving TTL from a document

Se è stato impostato un valore TTL per un documento ma si preferisce non farlo scadere, è possibile recuperare il documento, rimuovere il campo TTL e sostituire il documento nel server.If a TTL has been set on a document and you no longer want that document to expire, then you can retrieve the document, remove the TTL field and replace the document on the server. Quando il campo TTL viene rimosso dal documento, viene applicata l'impostazione predefinita della raccolta.When the TTL field is removed from the document, the default of the collection will be applied. Per impedire la scadenza di un documento e fare in modo che non erediti dalla raccolta, è necessario impostare il valore TTL su -1.To stop a document from expiring and not inherit from the collection then you need to set the TTL value to -1.

response = await client.ReadDocumentAsync(
    "/dbs/salesdb/colls/orders/docs/SO05"), 
    new RequestOptions { PartitionKey = new PartitionKey("CO18009186470") });

Document readDocument = response.Resource;
readDocument.TimeToLive = null; // inherit the default TTL of the collection

response = await client.ReplaceDocumentAsync(salesOrder);

Disabilitazione di TTLDisabling TTL

Per disabilitare del tutto la durata (TTL) in una raccolta e impedire al processo in background di cercare documenti scaduti, è necessario eliminare la proprietà DefaultTTL dalla raccolta.To disable TTL entirely on a collection and stop the background process from looking for expired documents the DefaultTTL property on the collection should be deleted. Eliminare questa proprietà non equivale a impostarla su -1.Deleting this property is different from setting it to -1. Se la proprietà è impostata su -1, i nuovi documenti aggiunti alla raccolta non hanno scadenza ma è possibile eseguire l'override dell'impostazione per documenti specifici nella raccolta.Setting to -1 means new documents added to the collection will live forever but you can override this on specific documents in the collection. Se la proprietà viene rimossa dalla raccolta, nessuno dei documenti ha una scadenza, anche se sono presenti documenti con override esplicito di una impostazione predefinita precedente.Removing this property entirely from the collection means that no documents will expire, even if there are documents that have explicitly overridden a previous default.

DocumentCollection collection = await client.ReadDocumentCollectionAsync("/dbs/salesdb/colls/orders");

// Disable TTL
collection.DefaultTimeToLive = null;

await client.ReplaceDocumentCollectionAsync(collection);

Interazione di durata (TTL) e indiceTTL and Index interaction

L'aggiunta o la modifica di una durata (TTL) è una modifica all'indice sottostante.TTL addition or change is a change to underlying index. Quando non c'è alcuna durata (TTL) e si specifica un valore di durata (TTL) valido, viene eseguita un'operazione di reindicizzazione.When there is no TTL and you provide a valid TTL value - this results in re-index operation. Per l'indice coerente, l'utente non vedrà alcuna modifica nello stato dell'indice.For consistent Index - user will not see any change in Index state. In caso di indice differito, l'indice deve prima di tutto sempre allinearsi e con la modifica della durata (TTL), l'indice viene ricreato da zero.In case of lazy index - the index first of all is always catching up and with this change in ttl, index is recreated from scratch. L'impatto in quest'ultimo caso è che le query eseguite durante la ricompilazione dell'indice non restituiranno risultati completi o corretti.The impact in latter case is that queries done during the index rebuild will not return complete or correct results. Non modificare la durata (TTL) per l'indice differito se è necessario un numero di dati esatto e così via, in quanto la modalità di indicizzazione stessa è differita.Please do not change TTL for lazy index if you need exact data count etc as indexing mode itself is lazy. In teoria bisognerebbe scegliere sempre l'indice coerente.Ideally consistent index should be always chosen.

domande frequentiFAQ

Quanto costa la durata (TTL)?What will TTL cost me?

Non sono previsti costi aggiuntivi per l'impostazione di una durata (TTL) in un documento.There is no additional cost to setting a TTL on a document.

Quanto tempo è necessario per eliminare il documento dopo la scadenza?How long will it take to delete my document once the TTL is up?

I documenti scadono immediatamente dopo la scadenza e non sarà possibile accedervi usando operazioni CRUD o API di query.The documents are expired immediately once the TTL is up, and will not be accessible via CRUD or query APIs.

La durata (TTL) impostata per un documento influisce sugli addebiti delle unità richiesta?Will TTL on a document have any impact on RU charges?

No, gli addebiti delle unità richiesta non risentono delle eliminazioni di documenti scaduti con TTL in Cosmos DB.No, there will be no impact on RU charges for deletions of expired documents via TTL in Cosmos DB.

La funzionalità TTL si applica solo all'intero documento o è possibile impostare come scaduti singoli valori delle proprietà di un documento?Does the TTL feature only apply to entire documents, or can I expire individual document property values?

La funzionalità TTL si applica all'intero documento.TTL applies to the entire document. Per impostare come scaduta solo una parte di un documento, è consigliabile estrarla dal documento principale, inserirla in un documento "collegato" separato e usare la funzionalità TTL sul documento estratto.If you would like to expire just a portion of a document, then it is recommended that you extract the portion from the main document in to a separate "linked” document and then use TTL on that extracted document.

La funzionalità TTL ha requisiti di indicizzazione specifici?Does the TTL feature have any specific indexing requirements?

Sì.Yes. I criteri di indicizzazione della raccolta devono essere impostati su Coerente o Differita.The collection must have indexing policy set to either Consistent or Lazy. Il tentativo di impostare DefaultTTL in una raccolta la cui indicizzazione è impostata su None genera un errore, come anche il tentativo di disabilitare l'indicizzazione in una raccolta in cui la proprietà DefaultTTL è già impostata.Trying to set DefaultTTL on a collection with indexing set to None will result in an error, as will trying to turn off indexing on a collection that has a DefaultTTL already set.

Passaggi successiviNext steps

Per altre informazioni su Azure Cosmos DB, vedere la pagina della documentazione del servizio.To learn more about Azure Cosmos DB, refer to the service documentation page.