Uso delle date in Azure Cosmos DB per NoSQL

  • Articolo

SI APPLICA A: NoSQL

Azure Cosmos DB per NoSQL offre flessibilità dello schema e indicizzazione avanzata tramite un modello di dati JSON nativo. Tutte le risorse di Azure Cosmos DB, inclusi database, contenitori, documenti e procedure archiviate, sono modellate e archiviate come documenti JSON. 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. Json, tuttavia, è flessibile e consente agli sviluppatori e ai framework di rappresentare tipi più complessi usando queste primitive e componendoli come oggetti o matrici.

Oltre ai tipi di base, molte applicazioni richiedono il DateTime tipo per rappresentare le informazioni di data e ora. Questo articolo descrive come gli sviluppatori possono archiviare, recuperare ed eseguire query di date in Azure Cosmos DB usando .NET SDK.

Archiviazione di valori DateTime

Azure Cosmos DB supporta tipi JSON, ad esempio- string, number, boolean, null, array, object. Non supporta direttamente un DateTime tipo. Attualmente l'API per NoSQL non supporta la localizzazione delle date. È quindi necessario archiviare le informazioni di data e ora come stringhe. Il formato consigliato per le stringhe di data e ora è yyyy-MM-ddTHH:mm:ss.fffffffZ, che segue lo standard ISO 8601 UTC. È consigliabile archiviare tutte le date in Azure Cosmos DB come UTC. La conversione delle stringhe di data in questo formato consente l'ordinamento di date lexicograficamente. Se le date non UTC vengono archiviate, la logica deve essere gestita sul lato client. Per convertire un valore di data e ora locale in UTC, l'offset deve essere noto/archiviato come proprietà nel file JSON e il client può usare l'offset per calcolare il valore di data e ora UTC.

Le query di intervallo con stringhe di data e ora come filtri sono supportate solo se le stringhe di data e ora sono tutte in formato UTC. La funzione di sistema GetCurrentDateTime restituisce il valore della stringa ISO 8601 della data UTC corrente nel formato : yyyy-MM-ddTHH:mm:ss.fffffffZ.

La maggior parte delle applicazioni può usare la rappresentazione stringa predefinita per DateTime i motivi seguenti:

  • Le stringhe possono essere confrontate e l'ordinamento relativo dei valori DateTime viene mantenuto quando vengono trasformati in stringhe.
  • Questo approccio non richiede codici o attributi personalizzati per la conversione JSON.
  • Le date così come archiviate in JSON sono leggibili dall'utente.
  • Questo approccio può sfruttare l'indice per prestazioni di query veloci.

Ad esempio, il frammento di codice seguente archivia un Order oggetto contenente due DateTime proprietà ShipDate e OrderDate come documento usando .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 container.CreateItemAsync(
    new Order
    {
        Id = "09152014101",
        OrderDate = DateTime.UtcNow.AddDays(-30),
        ShipDate = DateTime.UtcNow.AddDays(-14),
        Total = 113.39
    });

Questo documento viene archiviato nella struttura seguente:

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

In alternativa, è possibile archiviare DateTimes come timestamp Unix, ovvero come numero che rappresenta il numero di secondi trascorsi dal 1° gennaio 1970. La proprietà timestamp interna (_ts) di Azure Cosmos DB per NoSQL segue questo approccio. È possibile usare la UnixDateTimeConverter classe per serializzare date e ore come numeri.

Esecuzione di query su data e ora in LINQ

.NET SDK supporta automaticamente l'esecuzione di query sui dati archiviati tramite Query integrata del linguaggio (LINQ). Ad esempio, il frammento di codice seguente mostra una query LINQ che filtra gli ordini inviati negli ultimi tre giorni:

IQueryable<Order> orders = container
    .GetItemLinqQueryable<Order>(allowSynchronousQueryExecution: true)
    .Where(o => o.ShipDate >= DateTime.UtcNow.AddDays(-3));

La query LINQ viene tradotta nell'istruzione SQL seguente ed eseguita in Azure Cosmos DB:

SELECT
    *
FROM
    root
WHERE
    (root["ShipDate"] >= "2014-09-30T23:14:25.7251173Z")

Per altre informazioni sul linguaggio di query e sul provider LINQ, vedere LINQ to SQL traduzione.

Indicizzazione di data e ora per le query di intervallo

Le query sono comuni con DateTime i valori. Per eseguire queste query in modo efficiente, è necessario disporre di un indice definito in qualsiasi proprietà nel filtro della query.

Per altre informazioni su come configurare i criteri di indicizzazione, vedere Criteri di indicizzazione.

Contenuti correlati