Abfragen von Elementen in Azure Cosmos DB for NoSQL mithilfe von .NET

Artikel
08/19/2024

GILT FÜR: NoSQL

Elemente in Azure Cosmos DB stellen Entitäten dar, die in einem Container gespeichert sind. In der API für NoSQL besteht ein Element aus Daten im JSON-Format mit einem eindeutigen Bezeichner. Wenn Sie Abfragen mithilfe der API für NoSQL ausführen, werden Ergebnisse als ein JSON-Array von JSON-Dokumenten zurückgegeben.

Abfragen von Elementen mit SQL

Azure Cosmos DB for NoSQL unterstützt die Verwendung von Structured Query Language (SQL) zum Abfragen von Elementen in Containern. Eine einfache SQL-Abfrage wie SELECT * FROM products gibt alle Elemente und Eigenschaften aus einem Container zurück. Abfragen können allerdings auch komplexer sein und spezifische Feldprojektionen, Filter und andere gängige SQL-Klauseln enthalten:

SELECT 
    p.name, 
    p.description AS copy
FROM 
    products p 
WHERE 
    p.price > 500

Weitere Informationen zur SQL-Syntax für Azure Cosmos DB for NoSQL finden Sie unter Erste Schritte mit SQL-Abfragen.

Abfragen eines Elements

Hinweis

In den Beispielen dieses Artikels wird davon ausgegangen, dass Sie bereits einen C#-Typ namens Product definiert haben, der Ihre Daten darstellt:

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

Rufen Sie eine der folgenden Methoden auf, um Elemente in einem Container abzufragen:

GetItemQueryIterator<>
GetItemLinqQueryable<>

Abfragen von Elementen mithilfe einer asynchronen SQL-Abfrage

In diesem Beispiel wird eine SQL-Abfrage mit einer einfachen Zeichenfolge erstellt und ein Feediterator abgerufen. Anschließend werden geschachtelte Schleifen verwendet, um die Ergebnisse zu durchlaufen. Die äußere Schleife vom Typ while durchläuft die Ergebnisseiten, während die innere Schleife vom Typ foreach die Ergebnisse innerhalb einer Seite durchläuft.

// Query multiple items from container
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryText: "SELECT * FROM products p WHERE p.quantity > 10"
);

// Iterate query result pages
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Die Methode Container.GetItemQueryIterator<> gibt einen Feediterator (FeedIterator<>) zurück, der zum Durchlaufen mehrseitiger Ergebnisse verwendet wird. Die Eigenschaft HasMoreResults gibt an, ob noch weitere Ergebnisseiten vorhanden sind. Die Methode ReadNextAsync ruft die nächste Ergebnisseite als aufzählbares Element ab. Dieses wird dann in einer Schleife verwendet, um die Ergebnisse zu durchlaufen.

Verwenden Sie alternativ die Abfragedefinition (QueryDefinition), um eine SQL-Abfrage mit parametrisierter Eingabe zu erstellen:

// Build query definition
var parameterizedQuery = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.quantity > @quantity"
)
    .WithParameter("@quantity", 10);

// Query multiple items from container
using FeedIterator<Product> filteredFeed = container.GetItemQueryIterator<Product>(
    queryDefinition: parameterizedQuery
);

// Iterate query result pages
while (filteredFeed.HasMoreResults)
{
    FeedResponse<Product> response = await filteredFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

Tipp

Durch die Verwendung parametrisierter Eingabewerte lassen sich zahlreiche gängige SQL-Abfrageeinschleusungsangriffe verhindern.

Asynchrones Abfragen von Elementen mithilfe von LINQ

In diesem Beispiel wird ein Objekt vom Typ IQueryable<> verwendet, um eine sprachintegrierte Abfrage (Language Integrated Query, LINQ) zu erstellen. Die Ergebnisse werden dann mithilfe eines Feediterators durchlaufen.

// Get LINQ IQueryable object
IOrderedQueryable<Product> queryable = container.GetItemLinqQueryable<Product>();

// Construct LINQ query
var matches = queryable
    .Where(p => p.quantity > 10);

// Convert to feed iterator
using FeedIterator<Product> linqFeed = matches.ToFeedIterator();

// Iterate query result pages
while (linqFeed.HasMoreResults)
{
    FeedResponse<Product> response = await linqFeed.ReadNextAsync();

    // Iterate query results
    foreach (Product item in response)
    {
        Console.WriteLine($"Matched item:\t{item.name}");
    }
}

Die Methode Container.GetItemLinqQueryable<> erstellt ein Element vom Typ IQueryable, um die LINQ-Abfrage zu erstellen. Anschließend wird die Methode ToFeedIterator<> verwendet, um den LINQ-Abfrageausdruck in einen Feediterator (FeedIterator<>) umzuwandeln.

Tipp

Sie können zwar IQueryable<> durchlaufen, dieser Vorgang ist jedoch synchron. Verwenden Sie die Methode ToFeedIterator<>, um Ergebnisse asynchron zu sammeln.

Nächste Schritte

Nachdem Sie mehrere Elemente abgefragt haben, probieren Sie jetzt eines unserer End-to-End-Tutorials mit der API für NoSQL aus.

Erstellen einer App, die Daten von Azure Cosmos DB for NoSQL abfragt und ihr hinzufügt

Freigeben über