Stocker et interroger des dates - Langage de requête dans Cosmos DB (dans Azure et Fabric)

Cosmos DB (dans Azure et Fabric) offre une flexibilité de schéma et une indexation enrichie via un modèle de données JSON natif. Toutes les ressources Cosmos DB, notamment les bases de données, les conteneurs, les documents et les procédures stockées, sont modélisées et stockées en tant que documents JSON. Pour être portable, JSON (et Cosmos DB) ne prend en charge qu’un petit ensemble de types de base : String, Number, Boolean, Array, Object et Null. Toutefois, JSON est flexible et permet aux développeurs et aux frameworks de représenter des types plus complexes à l’aide de ces primitives et de les composer en tant qu’objets ou tableaux.

En plus des types de base, de nombreuses applications ont besoin du DateTime type pour représenter les dates et les informations d’heure. Cet article décrit comment les développeurs peuvent stocker, récupérer et interroger des dates dans Cosmos DB à l’aide du Kit de développement logiciel (SDK) .NET.

Dates du magasin

Cosmos DB prend en charge les types JSON tels que : chaîne, nombre, booléen, null, tableau, objet. Il ne prend pas directement en charge un DateTime type. Actuellement, l’API pour NoSQL ne prend pas en charge la localisation des dates. Vous devez donc stocker les informations de date et d’heure sous forme de chaînes. Le format recommandé pour les chaînes de date et d’heure est yyyy-MM-ddTHH:mm:ss.fffffffZ, qui suit la norme UTC ISO 8601 . Stockez toutes les dates dans Cosmos DB au format UTC. La conversion des chaînes de date dans ce format permet de trier les dates lexicographiquement. Si des dates non UTC sont stockées, la logique doit être gérée côté client. Pour convertir une valeur de date et d’heure locale en utc, le décalage doit être connu/stocké en tant que propriété dans le JSON et le client peut utiliser le décalage pour calculer la valeur de date et d’heure UTC.

Les requêtes de plage avec des chaînes de date et d’heure en tant que filtres ne sont prises en charge que si les chaînes de date et d’heure sont toutes au format UTC. La fonction système GetCurrentDateTime retourne la valeur de chaîne ISO 8601 UTC actuelle au format : yyyy-MM-ddTHH:mm:ss.fffffffZ.

La plupart des applications peuvent utiliser la représentation sous forme de chaîne par défaut pour DateTime les raisons suivantes :

• Les chaînes peuvent être comparées et l’ordre relatif des valeurs DateTime est conservé lorsqu’elles sont transformées en chaînes.
• Cette approche ne nécessite aucun code ou attribut personnalisé pour la conversion JSON.
• Les dates stockées dans JSON sont lisibles par l’homme.
• Cette approche peut tirer parti de l’index pour des performances de requête rapides.

Par exemple, l’extrait de code suivant stocke un Order objet contenant deux DateTime propriétés et ShipDateOrderDate en tant que document à l’aide du Kit de développement logiciel (SDK) .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
    });

Ce document est stocké dans la structure suivante :

{
  "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));

La requête LINQ est traduite en instruction SQL suivante et exécutée sur Cosmos DB :

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

Pour plus d’informations sur le langage de requête et le fournisseur LINQ, consultez traduction LINQ to SQL.

Date et heure d’index pour les requêtes de plage

Les requêtes sont communes aux DateTime valeurs. Pour exécuter ces requêtes efficacement, vous devez disposer d’un index défini sur toutes les propriétés du filtre de la requête.

Pour plus d’informations sur la configuration des stratégies d’indexation, consultez les stratégies d’indexation.