Delen via

Werken met datums in Azure Cosmos DB for NoSQL

  • Artikel

VAN TOEPASSING OP: NoSQL

Azure Cosmos DB for NoSQL biedt schemaflexiteit en uitgebreide indexering via een systeemeigen JSON-gegevensmodel . Alle Azure Cosmos DB-resources, waaronder databases, containers, documenten en opgeslagen procedures, worden gemodelleerd en opgeslagen als JSON-documenten. JSON (en Azure Cosmos DB) ondersteunt slechts een kleine set basistypen: Tekenreeks, Getal, Booleaanse waarde, Matrix, Object en Null. JSON is echter flexibel en stelt ontwikkelaars en frameworks in staat om complexere typen te vertegenwoordigen met behulp van deze primitieven en ze op te stellen als objecten of matrices.

Naast de basistypen hebben veel toepassingen het DateTime type nodig om datums en tijdgegevens weer te geven. In dit artikel wordt beschreven hoe ontwikkelaars datums in Azure Cosmos DB kunnen opslaan, ophalen en er query's op kunnen uitvoeren met behulp van de .NET SDK.

Datum/tijd opslaan

Azure Cosmos DB ondersteunt JSON-typen, zoals tekenreeks, getal, booleaanse waarde, null, matrix, object. Het biedt geen rechtstreekse ondersteuning voor een DateTime type. Op dit moment biedt de API voor NoSQL geen ondersteuning voor lokalisatie van datums. U moet dus datum- en tijdgegevens opslaan als tekenreeksen. De aanbevolen notatie voor datum- en tijdtekenreeksen is yyyy-MM-ddTHH:mm:ss.fffffffZ, die volgt op de ISO 8601 UTC-standaard. Het is raadzaam om alle datums in Azure Cosmos DB op te slaan als UTC. Als u de datumtekenreeksen naar deze notatie converteert, kunt u datums lexicografisch sorteren. Als niet-UTC-datums worden opgeslagen, moet de logica worden verwerkt aan de clientzijde. Als u een lokale datum- en tijdwaarde wilt converteren naar UTC, moet de offset bekend/opgeslagen zijn als een eigenschap in de JSON en kan de client de offset gebruiken om de UTC-datum- en tijdwaarde te berekenen.

Bereikquery's met datum- en tijdtekenreeksen als filters worden alleen ondersteund als de datum- en tijdtekenreeksen allemaal in UTC zijn. De systeemfunctie GetCurrentDateTime retourneert de huidige DATUM- en tijd-ISO 8601-tekenreekswaarde in de notatie: yyyy-MM-ddTHH:mm:ss.fffffffZ.

De meeste toepassingen kunnen om de volgende redenen de standaardtekenreeksweergave DateTime gebruiken:

  • Tekenreeksen kunnen worden vergeleken en de relatieve volgorde van de datum/tijd-waarden blijft behouden wanneer ze worden getransformeerd naar tekenreeksen.
  • Voor deze aanpak zijn geen aangepaste code of kenmerken vereist voor JSON-conversie.
  • De datums die zijn opgeslagen in JSON, kunnen door mensen worden gelezen.
  • Deze benadering kan profiteren van de index voor snelle queryprestaties.

In het volgende fragment wordt bijvoorbeeld een Order object met twee DateTime eigenschappen opgeslagen, ShipDate en OrderDate als document met behulp van de .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 = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        OrderDate = DateTime.UtcNow.AddDays(-30),
        ShipDate = DateTime.UtcNow.AddDays(-14),
        Total = 113.39
    });

Dit document wordt opgeslagen in de volgende structuur:

{
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "OrderDate": "2014-09-15T23:14:25.7251173Z",
  "ShipDate": "2014-09-30T23:14:25.7251173Z",
  "Total": 113.39
}

U kunt ook DateTimes opslaan als Unix-tijdstempels, dat wil gezegd, als een getal dat het aantal verstreken seconden vertegenwoordigt sinds 1 januari 1970. De eigenschap interne tijdstempel (_ts) van Azure Cosmos DB for NoSQL volgt deze benadering. U kunt de UnixDateTimeConverter klasse gebruiken om datums en tijden als getallen te serialiseren.

Query's uitvoeren op datum en tijd in LINQ

De .NET SDK biedt automatisch ondersteuning voor het uitvoeren van query's op gegevens die zijn opgeslagen met behulp van Language Integrated Query (LINQ). In het volgende fragment ziet u bijvoorbeeld een LINQ-query waarmee orders worden gefilterd die in de afgelopen drie dagen zijn verzonden:

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

De LINQ-query wordt vertaald naar de volgende SQL-instructie en uitgevoerd in Azure Cosmos DB:

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

Zie LINQ naar SQL-vertaling voor meer informatie over de querytaal en de LINQ-provider.

Indexeringsdatum en -tijd voor bereikquery's

Query's zijn gebruikelijk met DateTime waarden. Als u deze query's efficiënt wilt uitvoeren, moet u een index hebben gedefinieerd voor eigenschappen in het filter van de query.

Zie indexeringsbeleidsregels voor meer informatie over het configureren van indexeringsbeleid.

Gerelateerde inhoud