Freigeben über

Arbeiten mit Datumsangaben in Azure Cosmos DB for NoSQL

GILT FÜR: NoSQL

Azure Cosmos DB for NoSQL bietet Schemaflexibilität und eine umfassende Indizierung über ein natives JSON-Datenmodell. Alle Azure Cosmos DB-Ressourcen, z.B. Datenbanken, Container, Dokumente und gespeicherte Prozeduren, werden als JSON-Dokumente modelliert und gespeichert. Aufgrund der erforderlichen Portierbarkeit unterstützt JSON (ebenso wie Azure Cosmos DB) nur einen kleinen Satz grundlegender Typen: String, Number, Boolean, Array, Object und Null. JSON ist jedoch flexibel und ermöglicht es Entwicklern und Frameworks, komplexere Typen darzustellen, indem diese einfachen Typen verwendet und als Objekte oder Arrays zusammengestellt werden.

Zusätzlich zu den Grundtypen benötigen viele Anwendungen den DateTime-Typ, um Datums- und Uhrzeitinformationen darzustellen. Dieser Artikel beschreibt, wie Entwickler Datumsangaben in Azure Cosmos DB über das .NET SDK speichern, abrufen und abfragen können.

Speichern von DateTime-Werten

Azure Cosmos DB unterstützt JSON-Typen wie „String“, „Number“, „Boolean“, „NULL“, „Array“ und „Object“. Ein DateTime-Typ wird nicht direkt unterstützt. Derzeit unterstützt die API für NoSQL die Lokalisierung von Datumsangaben nicht. Daher müssen Sie Datums- und Uhrzeitinformationen als Zeichenfolgen speichern. Das empfohlene Format für Datums- und Uhrzeitzeichenfolgen ist yyyy-MM-ddTHH:mm:ss.fffffffZ, das dem ISO 8601 UTC-Standard folgt. Es wird empfohlen, alle Datumsangaben in Azure Cosmos DB als UTC zu speichern. Die Konvertierung der Datumszeichenfolgen in dieses Format ermöglicht das lexikografische Sortieren der Datumsangaben. Wenn Datumsangaben in einem anderen Format als UTC gespeichert werden, muss die Logik auf Clientseite behandelt werden. Um einen lokalen Datums- und Uhrzeitwert in UTC zu konvertieren, muss das Offset bekannt und als Eigenschaft im JSON-Format gespeichert sein, und der Client kann das Offset verwenden, um den UTC-Datums- und Uhrzeitwert zu berechnen.

Bereichsabfragen mit Datums- und Uhrzeitzeichenfolgen als Filter werden nur unterstützt, wenn die Datums- und Uhrzeitzeichenfolgen alle in UTC vorliegen. Die GetCurrentDateTime-Systemfunktion gibt den aktuellen ISO 8601-Zeichenfolgenwert für UTC-Datums und -Uhrzeit im folgenden Format zurück: yyyy-MM-ddTHH:mm:ss.fffffffZ.

Die meisten Anwendungen können die Standard-Zeichenfolgendarstellung für DateTime aus folgenden Gründen verwenden:

  • Zeichenfolgen können verglichen werden, und die relative Reihenfolge der DateTime-Werte wird beibehalten, wenn sie in Zeichenfolgen umgewandelt werden.
  • Für diesen Ansatz sind weder benutzerdefinierter Code noch Attribute für die JSON-Konvertierung erforderlich.
  • Die als JSON gespeicherten Daten sind visuell lesbar.
  • Dieser Ansatz kann den Index für eine schnelle Abfrageleistung nutzen.

Der folgende Codeschnipsel beispielsweise speichert ein Order-Objekt mit zwei DateTime-Eigenschaften – ShipDate und OrderDate als Dokument mit dem .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
    });

Dieses Dokument wird in der folgenden Struktur gespeichert:

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

Alternativ dazu können Sie DateTime-Werte auch als UNIX-Zeitstempel speichern, also als Zahl, welche die Anzahl der seit dem 1. Januar 1970 verstrichenen Sekunden darstellt. Der interne Zeitstempel (_ts) von Azure Cosmos DB for NoSQL folgt diesem Ansatz. Sie können die UnixDateTimeConverter-Klasse verwenden, um Datums- und Uhrzeitangaben als Zahlen zu serialisieren.

Abfragen von Datum und Uhrzeit in LINQ

Das .NET-SDK unterstützt automatisch das Abfragen von Daten, die mithilfe von LINQ (Language Integrated Query) gespeichert wurden. Der folgende Codeausschnitt enthält z. B. eine LINQ-Abfrage, die Aufträge filtert, die in den letzten drei Tagen ausgeliefert wurden:

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

Die LINQ-Abfrage wird in die folgende SQL-Anweisung übersetzt und in Azure Cosmos DB ausgeführt:

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

Weitere Informationen zur Abfragesprache und zum LINQ-Anbieter finden Sie unter LINQ to SQL-Übersetzung.

Indizieren von Datum und Uhrzeit für Bereichsabfragen

Bei Abfragen werden häufig DateTime-Werte verwendet. Damit diese Abfragen effizient ausgeführt werden können, muss ein Index für alle Eigenschaften im Filter der Abfrage definiert sein.

Weitere Informationen zum Konfigurieren von Indizierungsrichtlinien finden Sie unter Indizierungsrichtlinien.

Zugehöriger Inhalt