Przechowywanie dat i wykonywanie zapytań — język zapytań w usłudze Cosmos DB (na platformie Azure i w sieci szkieletowej)

  • Dotyczy: ✅ Azure Cosmos DB, ✅ Cosmos DB in Microsoft Fabric

Usługa Cosmos DB (na platformie Azure i w sieci szkieletowej) zapewnia elastyczność schematu i zaawansowane indeksowanie za pośrednictwem natywnego modelu danych JSON . Wszystkie zasoby usługi Cosmos DB, w tym bazy danych, kontenery, dokumenty i procedury składowane, są modelowane i przechowywane jako dokumenty JSON. Jako wymóg bycia przenośnym kod JSON (i cosmos DB) obsługuje tylko niewielki zestaw typów podstawowych: Ciąg, Liczba, Wartość logiczna, Tablica, Obiekt i Wartość null. Jednak kod JSON jest elastyczny i umożliwia deweloperom i platformom reprezentowanie bardziej złożonych typów przy użyciu tych typów pierwotnych i tworzenie ich jako obiektów lub tablic.

Oprócz podstawowych typów wiele aplikacji potrzebuje DateTime typu do reprezentowania informacji o dacie i godzinie. W tym artykule opisano, jak deweloperzy mogą przechowywać, pobierać i wykonywać zapytania o daty w usłudze Cosmos DB przy użyciu zestawu .NET SDK.

Przechowywanie dat/godzin

Usługa Cosmos DB obsługuje typy JSON, takie jak — ciąg, liczba, wartość logiczna, wartość null, tablica, obiekt. Nie obsługuje DateTime on bezpośrednio typu. Obecnie interfejs API dla noSQL nie obsługuje lokalizacji dat. Dlatego należy przechowywać informacje o dacie i godzinie jako ciągi. Zalecany format ciągów daty i godziny to yyyy-MM-ddTHH:mm:ss.fffffffZ, który jest zgodny ze standardem ISO 8601 UTC. Przechowuj wszystkie daty w usłudze Cosmos DB jako utc. Konwertowanie ciągów dat na ten format umożliwia sortowanie dat leksykograficznie. Jeśli daty inne niż UTC są przechowywane, logika musi być obsługiwana po stronie klienta. Aby przekonwertować lokalną wartość daty i godziny na utc, przesunięcie musi być znane/przechowywane jako właściwość w formacie JSON, a klient może użyć przesunięcia, aby obliczyć wartość daty i godziny UTC.

Zapytania zakresu z ciągami daty i godziny jako filtry są obsługiwane tylko wtedy, gdy ciągi daty i godziny znajdują się w formacie UTC. Funkcja systemowa GetCurrentDateTime zwraca bieżącą wartość ciągu ISO 8601 w formacie yyyy-MM-ddTHH:mm:ss.fffffffZUTC: .

Większość aplikacji może używać domyślnej reprezentacji DateTime ciągu z następujących powodów:

  • Ciągi można porównać, a względne porządkowanie wartości DateTime jest zachowywane podczas przekształcania ich do ciągów.
  • Takie podejście nie wymaga żadnego niestandardowego kodu ani atrybutów konwersji JSON.
  • Daty przechowywane w formacie JSON są czytelne dla człowieka.
  • Takie podejście może korzystać z indeksu w celu uzyskania szybkiej wydajności zapytań.

Na przykład poniższy fragment kodu przechowuje Order obiekt zawierający dwie DateTime właściwości — ShipDate i OrderDate jako dokument przy użyciu zestawu SDK platformy .NET:

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
    });

Ten dokument jest przechowywany w następującej strukturze:

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

Alternatively, you can store DateTimes as Unix timestamps, that is, as a number representing the number of elapsed seconds since **January 1, 1970**. Cosmos DB's internal timestamp (`_ts`) property follows this approach. You can use the [`UnixDateTimeConverter`](/dotnet/api/microsoft.azure.documents.unixdatetimeconverter) class to serialize dates and times as numbers.

## Query date and time in LINQ

The .NET SDK automatically supports querying data stored using Language Integrated Query (LINQ). For example, the following snippet shows a LINQ query that filters orders that were shipped in the last three days:

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

Zapytanie LINQ jest tłumaczone na następującą instrukcję SQL i wykonywane w usłudze Cosmos DB:

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

Aby uzyskać więcej informacji na temat języka zapytań i dostawcy LINQ, zobacz TŁUMACZENIE LINQ to SQL.

Data i godzina indeksowania dla zapytań zakresu

Zapytania są wspólne z wartościami DateTime . Aby efektywnie wykonywać te zapytania, należy mieć indeks zdefiniowany we wszystkich właściwościach filtru zapytania.

Aby uzyskać więcej informacji na temat konfigurowania zasad indeksowania, zobacz Zasady indeksowania.

  • Last updated on