مشاركة عبر

الاستعلام عن العناصر في Azure Cosmos DB ل NoSQL باستخدام .NET

  • مقالة

ينطبق على: NoSQL

تمثل العناصر في Azure Cosmos DB الكيانات المخزنة داخل حاوية. في واجهة برمجة التطبيقات ل NoSQL، يتكون العنصر من بيانات بتنسيق JSON مع معرف فريد. عند إصدار استعلامات باستخدام واجهة برمجة التطبيقات ل NoSQL، يتم إرجاع النتائج كصفيف JSON من مستندات JSON.

الاستعلام عن العناصر باستخدام SQL

يدعم Azure Cosmos DB ل NoSQL استخدام لغة الاستعلامات المركبة (SQL) لإجراء استعلامات على العناصر في الحاويات. سيقوم استعلام SQL بسيط مثل SELECT * FROM products بإرجاع كافة العناصر والخصائص من حاوية. يمكن أن تكون الاستعلامات أكثر تعقيدا وتتضمن إسقاطات حقول محددة وعوامل تصفية وعبارات SQL شائعة أخرى:

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

لمعرفة المزيد حول بناء جملة SQL ل Azure Cosmos DB ل NoSQL، راجع بدء استخدام استعلامات SQL.

الاستعلام عن عنصر

إشعار

تفترض الأمثلة الواردة في هذه المقالة أنك قمت بالفعل بتعريف نوع C# لتمثيل بياناتك المسماة Product:

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

للإستعلام عن العنصر في الحاوية، قم باستدعاء أحد الأساليب التالية:

الاستعلام عن العناصر باستخدام استعلام SQL بشكل غير متزامن

ينشئ هذا المثال استعلاما SQL باستخدام سلسلة بسيطة، ويسترد مكرر موجز، ثم يستخدم حلقات متداخلة للتكرار عبر النتائج. سيتم تكرار التكرار الحلقي الخارجي أثناء عبر صفحات النتائج، بينما تتكرر حلقة foreach الداخلية عبر النتائج داخل الصفحة.

// Query multiple items from container
using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryText: "SELECT * FROM products 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}");
    }
}

يقوم أسلوب Container.GetItemQueryIterator<> بإرجاع FeedIterator<> الذي يتم استخدامه للتكرار من خلال نتائج متعددة الصفحات. تشير الخاصية HasMoreResults إلى ما إذا كان هناك المزيد من صفحات النتائج المتبقية. يحصل الأسلوب ReadNextAsync على الصفحة التالية من النتائج كعداد يتم استخدامه بعد ذلك في حلقة للتكرار عبر النتائج.

بدلا من ذلك، استخدم QueryDefinition لإنشاء استعلام SQL مع إدخال ذي معلمات:

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

تلميح

يمكن أن تساعد قيم الإدخال ذات المعلمات في منع العديد من هجمات إدخال استعلام SQL الشائعة.

الاستعلام عن العناصر باستخدام LINQ بشكل غير متزامن

في هذا المثال، يتم استخدام عنصر IQueryable<> لإنشاء استعلام اللغة المتكاملة (LINQ). ثم يتم تكرار النتائج باستخدام مكرر موجز.

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

ينشئ الأسلوب Container.GetItemLinqQueryable<>IQueryable لإنشاء استعلام اللغة المتكاملة LINQ. ثم يتم استخدام الأسلوبToFeedIterator<> لتحويل تعبير استعلام LINQ إلى FeedIterator<>.

تلميح

بينما يمكنك التكرار عبر IQueryable<>، تكون هذه العملية متزامنة. استخدم الأسلوب ToFeedIterator<> لجمع النتائج بشكل غير متزامن.

الخطوات التالية

الآن بعد أن استعلمت عن عناصر متعددة، جرب أحد البرامج التعليمية الشاملة باستخدام واجهة برمجة التطبيقات ل NoSQL.

إنشاء تطبيق يستعلم عن البيانات ويضيفها إلى Azure Cosmos DB ل NoSQL