Uso delle date in Azure Cosmos DBWorking with Dates in Azure Cosmos DB

Azure Cosmos DB offre flessibilità dello schema e un'indicizzazione avanzata tramite un modello di dati JSON nativo.Azure Cosmos DB delivers schema flexibility and rich indexing via a native JSON data model. Tutte le risorse di Azure Cosmos DB, inclusi database, raccolte, documenti e procedure archiviate, sono modellate e archiviate come documenti JSON.All Azure Cosmos DB resources including databases, collections, documents, and stored procedures are modeled and stored as JSON documents. Come requisito per essere portatile, JSON, insieme a Azure Cosmos DB, supporta solo un piccolo set di tipi di base: String, Number, Boolean, Array, Object e Null.As a requirement for being portable, JSON (and Azure Cosmos DB) supports only a small set of basic types: String, Number, Boolean, Array, Object, and Null. Tuttavia, JSON è flessibile e consente a sviluppatori e strutture di rappresentare tipi più complessi tramite l'uso di queste primitive, componendole come oggetti o matrici.However, JSON is flexible and allow developers and frameworks to represent more complex types using these primitives and composing them as objects or arrays.

Oltre ai tipi di base, molte applicazioni hanno bisogno del tipo DateTime per rappresentare date e timestamp.In addition to the basic types, many applications need the DateTime type to represent dates and timestamps. Questo articolo descrive come gli sviluppatori possono archiviare, recuperare ed eseguire query di date in Azure Cosmos DB usando .NET SDK.This article describes how developers can store, retrieve, and query dates in Azure Cosmos DB using the .NET SDK.

Archiviazione di valori DateTimeStoring DateTimes

Per impostazione predefinita, Azure Cosmos DB SDK serializza i valori DateTime come stringhe ISO 8601.By default, the Azure Cosmos DB SDK serializes DateTime values as ISO 8601 strings. La maggior parte delle applicazioni può usare la rappresentazione predefinita della stringa per il valore DateTime, per i motivi seguenti:Most applications can use the default string representation for DateTime for the following reasons:

  • Le stringhe possono essere confrontate e l'ordinamento relativo dei valori DateTime viene conservato quando questi vengono trasformati in stringhe.Strings can be compared, and the relative ordering of the DateTime values is preserved when they are transformed to strings.
  • Questo approccio non richiede codici o attributi personalizzati per la conversione JSON.This approach doesn't require any custom code or attributes for JSON conversion.
  • Le date così come archiviate in JSON sono leggibili dall'utente.The dates as stored in JSON are human readable.
  • Questo approccio può sfruttare l'indicizzazione di Azure Cosmos DB per query più veloci.This approach can take advantage of Azure Cosmos DB's index for fast query performance.

Ad esempio, il frammento seguente memorizza come documento un oggetto Order che contiene due proprietà DateTime, ShipDate e OrderDate, tramite .NET SDK:For example, the following snippet stores an Order object containing two DateTime properties - ShipDate and OrderDate as a document using the .NET SDK:

public class Order
{
    [JsonProperty(PropertyName="id")]
    public string Id { get; set; }
    public DateTime OrderDate { get; set; }
    public DateTime ShipDate { get; set; }
    public double Total { get; set; }
}

await client.CreateDocumentAsync("/dbs/orderdb/colls/orders", 
    new Order 
    { 
        Id = "09152014101",
        OrderDate = DateTime.UtcNow.AddDays(-30),
        ShipDate = DateTime.UtcNow.AddDays(-14), 
        Total = 113.39
    });

Il documento viene archiviato in Azure Cosmos DB come illustrato di seguito:This document is stored in Azure Cosmos DB as follows:

{
    "id": "09152014101",
    "OrderDate": "2014-09-15T23:14:25.7251173Z",
    "ShipDate": "2014-09-30T23:14:25.7251173Z",
    "Total": 113.39
}

In alternativa, è possibile archiviare valori DateTime come timestamp Unix, ovvero come un numero che rappresenti i secondi trascorsi a partire dal 1° gennaio 1970.Alternatively, you can store DateTimes as Unix timestamps, that is, as a number representing the number of elapsed seconds since January 1, 1970. La proprietà Timestamp interna di Azure Cosmos DB (_ts) segue questo approccio.Azure Cosmos DB's internal Timestamp (_ts) property follows this approach. È possibile usare la classe UnixDateTimeConverter per serializzare come numeri i valori DateTime.You can use the UnixDateTimeConverter class to serialize DateTimes as numbers.

Indicizzazione dei valori DateTime per le query di intervalloIndexing DateTimes for range queries

Le query di intervallo sono comuni con i valori DateTime.Range queries are common with DateTime values. Ad esempio, sono necessarie per trovare tutti gli ordini creati dal giorno precedente o tutti gli ordini spediti negli ultimi cinque minuti.For example, if you need to find all orders created since yesterday, or find all orders shipped in the last five minutes, you need to perform range queries. Per eseguire queste query in modo efficiente, è necessario configurare la raccolta per l'indicizzazione di intervallo nelle stringhe.To execute these queries efficiently, you must configure your collection for Range indexing on strings.

DocumentCollection collection = new DocumentCollection { Id = "orders" };
collection.IndexingPolicy = new IndexingPolicy(new RangeIndex(DataType.String) { Precision = -1 });
await client.CreateDocumentCollectionAsync("/dbs/orderdb", collection);

Per altre informazioni su come configurare i criteri di indicizzazione, vedere i criteri di indicizzazione di Azure Cosmos DB.You can learn more about how to configure indexing policies at Azure Cosmos DB Indexing Policies.

Esecuzione di query per i valori DateTime in LINQQuerying DateTimes in LINQ

DocumentDB .NET SDK supporta automaticamente le query sui dati archiviati in Azure Cosmos DB tramite LINQ.The DocumentDB .NET SDK automatically supports querying data stored in Azure Cosmos DB via LINQ. Ad esempio, il frammento seguente mostra una query LINQ che filtra gli ordini inviati negli ultimi tre giorni.For example, the following snippet shows a LINQ query that filters orders that were shipped in the last three days.

IQueryable<Order> orders = client.CreateDocumentQuery<Order>("/dbs/orderdb/colls/orders")
    .Where(o => o.ShipDate >= DateTime.UtcNow.AddDays(-3));

// Translated to the following SQL statement and executed on Azure Cosmos DB
SELECT * FROM root WHERE (root["ShipDate"] >= "2016-12-18T21:55:03.45569Z")

Per altre informazioni sul linguaggio di query SQL di Azure Cosmos DB e sul provider LINQ, vedere l'esecuzione di query in Cosmos DB.You can learn more about Azure Cosmos DB's SQL query language and the LINQ provider at Querying Cosmos DB.

In questo articolo è stato descritto come archiviare, indicizzare ed eseguire query per valori DateTime in Azure Cosmos DB.In this article, we looked at how to store, index, and query DateTimes in Azure Cosmos DB.

Passaggi successiviNext Steps