Query's uitvoeren met de EF Core Azure Cosmos DB-provider

Basisbeginselen opvragen

EF Core LINQ-query's kunnen op dezelfde manier worden uitgevoerd op Azure Cosmos DB als voor andere databaseproviders. Voorbeeld:

public class Session
{
    public Guid Id { get; set; }
    public string Category { get; set; }

    public string TenantId { get; set; } = null!;
    public Guid UserId { get; set; }
    public int SessionId { get; set; }
}

var stringResults = await context.Sessions
    .Where(
        e => e.Category.Length > 4
            && e.Category.Trim().ToLower() != "disabled"
            && e.Category.TrimStart().Substring(2, 2).Equals("xy", StringComparison.OrdinalIgnoreCase))
    .ToListAsync();

Partitiesleutels

Het voordeel van partitioneren is om uw query's alleen uit te voeren op de partitie waar de relevante gegevens worden gevonden, kosten te besparen en snellere resultaatsnelheid te garanderen. Query's die geen partitiesleutels opgeven, worden uitgevoerd op alle partities, wat behoorlijk kostbaar kan zijn.

Vanaf EF 9.0 detecteert en extraheert EF automatisch partitiesleutelvergelijkingen in de operators van Where uw LINQ-query. Stel dat we de volgende query uitvoeren op ons Session entiteitstype, dat is geconfigureerd met een hiërarchische partitiesleutel:

protected override void OnModelCreating(ModelBuilder modelBuilder)
{
    modelBuilder.Entity<Session>()
        .HasPartitionKey(b => new { b.TenantId, b.UserId, b.SessionId })
}

var tenantId = "Microsoft";
var userId = new Guid("00aa00aa-bb11-cc22-dd33-44ee44ee44ee");
var username = "scott";

var sessions = await context.Sessions
    .Where(
        e => e.TenantId == tenantId
             && e.UserId == userId
             && e.SessionId > 0
             && e.Username == username)
    .ToListAsync();

Als we de logboeken bekijken die door EF worden gegenereerd, zien we dat deze query als volgt wordt uitgevoerd:

Executed ReadNext (166.6985 ms, 2.8 RU) ActivityId='312da0d2-095c-4e73-afab-27072b5ad33c', Container='test', Partition='["Microsoft","00aa00aa-bb11-cc22-dd33-44ee44ee44ee"]', Parameters=[]
SELECT VALUE c
FROM root c
WHERE ((c["SessionId"] > 0) AND CONTAINS(c["Username"], "a"))

In deze logboeken zien we het volgende:

• De eerste twee vergelijkingen , aan TenantId en UserId - zijn verwijderd en worden weergegeven in de ReadNext partitie in plaats van in de WHERE component. Dit betekent dat de query alleen wordt uitgevoerd op de subpartities voor deze waarden.
• SessionId maakt ook deel uit van de hiërarchische partitiesleutel, maar in plaats van een gelijkheidsvergelijking maakt het gebruik van een operator groter dan (>) en kan daarom niet worden verwijderd. Het maakt deel uit van de WHERE component zoals elke gewone eigenschap.
• Username is een gewone eigenschap , geen deel van de partitiesleutel - en blijft daarom ook in de WHERE component.

Houd er rekening mee dat hoewel sommige partitiesleutelwaarden niet worden opgegeven, hiërarchische partitiesleutels nog steeds alleen gericht zijn op de subpartities die overeenkomen met de eerste twee eigenschappen. Hoewel dit niet zo efficiënt is als het richten op één partitie (zoals geïdentificeerd door alle drie de eigenschappen), is het nog steeds veel efficiënter dan het instellen van alle partities.

In plaats van te verwijzen naar eigenschappen van partitiesleutels in een Where operator, kunt u deze expliciet opgeven met behulp van de WithPartitionKey operator:

var sessions = await context.Sessions
    .WithPartitionKey(tenantId, userId)
    .Where(e => e.SessionId > 0 && e.Username.Contains("a"))
    .ToListAsync();

Dit wordt op dezelfde manier uitgevoerd als de bovenstaande query en kan de voorkeur hebben als u partitiesleutels explicieter wilt maken in uw query's. Het gebruik WithPartitionKey kan nodig zijn in versies van EF vóór 9.0: houd de logboeken in de gaten om ervoor te zorgen dat query's partitiesleutels gebruiken zoals verwacht.

Puntleesbewerkingen

Hoewel Azure Cosmos DB krachtige query's via SQL mogelijk maakt, kunnen dergelijke query's behoorlijk duur zijn. Azure Cosmos DB ondersteunt ook puntleesbewerkingen, die moeten worden gebruikt bij het ophalen van één document als zowel de id eigenschap als de volledige partitiesleutel bekend zijn. Punt leest rechtstreeks een specifiek document in een specifieke partitie en voert zeer efficiënt uit en met lagere kosten vergeleken met het ophalen van hetzelfde document met een query. Het is raadzaam om uw systeem zo vaak mogelijk te ontwerpen om puntleesbewerkingen te gebruiken. Raadpleeg de Documentatie van Azure Cosmos DB voor meer informatie.

In de vorige sectie hebben we EF gezien dat vergelijkingen van partitiesleutels uit de Where component worden geïdentificeerd en geëxtraheerd voor efficiëntere query's, waardoor de verwerking alleen wordt beperkt tot de relevante partities. Het is mogelijk om nog een stap verder te gaan en ook de id eigenschap in de query op te geven. Laten we de volgende query bekijken:

var session = await context.Sessions.SingleAsync(
    e => e.Id == someId
         && e.TenantId == tenantId
         && e.UserId == userId
         && e.SessionId == sessionId);

In deze query wordt een waarde voor de Id eigenschap opgegeven (die is toegewezen aan de eigenschap Azure Cosmos DB id ), evenals waarden voor alle eigenschappen van de partitiesleutel. Bovendien zijn er geen extra onderdelen voor de query. Wanneer aan al deze voorwaarden wordt voldaan, kan EF de query uitvoeren als puntleespunt:

Executed ReadItem (46 ms, 1 RU) ActivityId='d7391311-2266-4811-ae2d-535904c42c43', Container='test', Id='9', Partition='["Microsoft","00aa00aa-bb11-cc22-dd33-44ee44ee44ee",10.0]'

Let op, ReadItemwat aangeeft dat de query is uitgevoerd als een efficiënt punt lezen. Er is geen SQL-query betrokken.

Zoals bij het extraheren van partitiesleutels zijn belangrijke verbeteringen aangebracht in dit mechanisme in EF 9.0; oudere versies detecteren en gebruiken geen puntleesbewerkingen betrouwbaar.

Pagina-indeling

Paginering verwijst naar het ophalen van resultaten in pagina's, in plaats van allemaal tegelijk; Dit wordt meestal gedaan voor grote resultatensets, waarbij een gebruikersinterface wordt weergegeven, zodat gebruikers door pagina's van de resultaten kunnen navigeren.

Een veelgebruikte manier om paginering met databases te implementeren, is door de Skip operators en Take LINQ-operators (OFFSET en LIMIT in SQL) te gebruiken. Op basis van een paginaformaat van 10 resultaten kan de derde pagina als volgt worden opgehaald met EF Core:

var position = 20;
var nextPage = await context.Session
    .OrderBy(s => s.Id)
    .Skip(position)
    .Take(10)
    .ToListAsync();

Helaas is deze techniek behoorlijk inefficiënt en kan de querykosten aanzienlijk verhogen. Azure Cosmos DB biedt een speciaal mechanisme voor het pagineren van het resultaat van een query, via het gebruik van vervolgtokens:

CosmosPage firstPage = await context.Sessions
    .OrderBy(s => s.Id)
    .ToPageAsync(pageSize: 10, continuationToken: null);

string continuationToken = firstPage.ContinuationToken;
foreach (var session in firstPage.Values)
{
    // Display/send the sessions to the user
}

In plaats van de LINQ-query met ToListAsync of vergelijkbaar te beëindigen, gebruiken we de ToPageAsync methode om deze maximaal 10 items op elke pagina op te halen (houd er rekening mee dat er mogelijk minder items in de database zijn). Omdat dit de eerste query is, willen we resultaten van het begin ophalen en doorgeven null als het vervolgtoken. ToPageAsync retourneert een CosmosPage<T>, waarmee een vervolgtoken en de waarden op de pagina worden weergegeven (maximaal 10 items). Uw programma verzendt deze waarden doorgaans naar de client, samen met het vervolgtoken; Hierdoor kan de query later worden hervat en meer resultaten worden opgehaald.

Stel dat de gebruiker nu op de knop Volgende in de gebruikersinterface klikt en vraagt om de volgende 10 items. Vervolgens kunt u de query als volgt uitvoeren:

CosmosPage nextPage = await context.Sessions.OrderBy(s => s.Id).ToPageAsync(10, continuationToken);
string continuationToken = nextPage.ContinuationToken;
foreach (var session in nextPage.Values)
{
    // Display/send the sessions to the user
}

We voeren dezelfde query uit, maar deze keer geven we het vervolgtoken door dat is ontvangen van de eerste uitvoering; hiermee wordt de query-engine geïnstrueerd om door te gaan met de query waar deze was gebleven en de volgende 10 items op te halen. Zodra we de laatste pagina hebben opgehaald en er geen resultaten meer zijn, wordt het vervolgtoken weergegeven nullen kan de knop 'Volgende' grijs worden weergegeven. Deze pagineringsmethode is uiterst efficiënt en rendabel in vergelijking met het gebruik Skip en Take.

Zie deze pagina voor meer informatie over paginering in Azure Cosmos DB.

FindAsync

FindAsync is een nuttige API voor het ophalen van een entiteit door de primaire sleutel en het vermijden van een retour van een database wanneer de entiteit al is geladen en wordt bijgehouden door de context.

Ontwikkelaars die bekend zijn met relationele databases, worden gebruikt voor de primaire sleutel van een entiteitstype dat bestaat uit bijvoorbeeld een Id eigenschap. Wanneer u de EF Azure Cosmos DB-provider gebruikt, bevat de primaire sleutel de eigenschappen van de partitiesleutel naast de eigenschap die is toegewezen aan de JSON-eigenschap id . Dit is het geval omdat Azure Cosmos DB verschillende partities toestaat documenten met dezelfde JSON-eigenschap id te bevatten, en dus alleen de gecombineerde id en partitiesleutel uniek één document in een container identificeren:

public class Session
{
    public Guid Id { get; set; }
    public string PartitionKey { get; set; }
    ...
}

var mySession = await context.FindAsync(id, pkey);

Als u een hiërarchische partitiesleutel hebt, moet u alle partitiesleutelwaarden doorgeven aan FindAsync, in de volgorde waarin ze zijn geconfigureerd.

SQL-query's

Query's kunnen ook rechtstreeks in SQL worden geschreven. Voorbeeld:

var rating = 3;
_ = await context.Blogs
    .FromSql($"SELECT VALUE c FROM root c WHERE c.Rating > {rating}")
    .ToListAsync();

Deze query resulteert in de volgende queryuitvoering:

SELECT VALUE s
FROM (
    SELECT VALUE c FROM root c WHERE c.Angle1 <= @p0
) s

Houd er rekening mee dat FromSql is geïntroduceerd in EF 9.0. In eerdere versies kan in plaats daarvan FromSqlRaw worden gebruikt, hoewel u er rekening mee houdt dat deze methode kwetsbaar is voor SQL-injectieaanvallen.

Zie de relationele documentatie over SQL-query's voor meer informatie over SQL-query's. de meeste inhoud is ook relevant voor de Azure Cosmos DB-provider.

Functietoewijzingen

In deze sectie ziet u welke .NET-methoden en -leden worden vertaald in welke SQL-functies worden uitgevoerd bij het uitvoeren van query's met de Azure Cosmos DB-provider.

Datum- en tijdfuncties

¹ De andere leden van het onderdeel worden ook vertaald (Maand, Dag...).

Numerieke functies

Stringfuncties

Vector en zoeken in volledige tekst

Zie de documentatie voor meer informatie over vectorzoekopdrachten. Zie de documentatie voor meer informatie over zoeken in volledige tekst.

Diverse functies

¹ Houd er rekening mee CoalesceUndefineddat undefined samensnommen , niet null. Als u wilt samenvoegen null, gebruikt u de reguliere C# ?? -operator.