بدء استخدام استعلامات SQL

ينطبق على: واجهة برمجة التطبيقات SQL

في حسابات Azure Cosmos DB SQL API، هناك طريقتان لقراءة البيانات:

قراءة النقاط - يمكنك إجراء بحث عن مفتاح/قيمة على معرّف عنصر واحد ومفتاح قسم. مجموعة مفاتيح القسم معرّف العنصر هي المفتاح والعنصر نفسه هو القيمة. بالنسبة إلى مستند 1 كيلوبايت، عادةً ما تكلف قراءات النقاط 1 وحدة طلب مع زمن انتقال أقل من 10 مللي ثانية. ترجع قراءات النقاط عنصرا كاملا واحدا، وليس عنصرا جزئيا أو حقلا معينا.

فيما يلي بعض الأمثلة عن كيفية إجراء قراءات النقاط مع كل SDK:

استعلامات SQL - يمكنك الاستعلام عن البيانات عن طريق كتابة استعلامات باستخدام لغة الاستعلام الهيكلية (SQL) كلغة استعلام JSON. تكلف الاستعلامات دائماً 2.3 وحدة طلب على الأقل، وبصفة عامة، سيكون لها زمن انتقال أعلى ومتغير أكثر من قراءات النقاط. يمكن للاستعلامات إرجاع العديد من العناصر.

تستخدم معظم أحمال العمل المليئة بالقراءة على Azure Cosmos DB مزيجاً من قراءات النقاط واستعلامات SQL. إذا كنت تحتاج فقط إلى قراءة عنصر واحد، فإن قراءات النقاط أرخص وأسرع من الاستعلامات. لا تحتاج قراءات النقاط إلى استخدام محرك الاستعلام للوصول إلى البيانات ويمكنها قراءة البيانات مباشرة. بالطبع، ليس من الممكن لجميع أعباء العمل قراءة البيانات حصرياً باستخدام قراءات النقاط، لذا فإن دعم SQL كلغة استعلام والفهرسة الحيادية للمخطط يوفران طريقة أكثر مرونة للوصول إلى بياناتك.

فيما يلي بعض الأمثلة عن كيفية إجراء استعلامات SQL مع كل SDK:

يوضح الجزء المتبقي من هذا المستند كيفية البدء في كتابة استعلامات SQL في Azure Cosmos DB. يمكن تشغيل استعلامات SQL من خلال بوابة SDK أو مدخل Microsoft Azure.

تحميل بيانات العينة

في حساب SQL API Cosmos DB الخاص بك، افتح Data Explorer لإنشاء حاوية تسمى Families. بعد إنشاء الحاوية، استخدم متصفح هياكل البيانات للعثور عليها وفتحها. في حاوية Families الخاصة بك، سترى الخيار Items أسفل اسم الحاوية مباشرةً. افتح هذا الخيار وسترى زراً، في شريط القائمة في وسط الشاشة، لإنشاء "عنصر جديد". ستستخدم هذه الميزة لإنشاء عناصر JSON أدناه.

إنشاء عناصر JSON

عنصرا JSON التاليين عبارة عن مستندات حول عائلات Andersen وWakefield. وهي تشمل الآباء والأطفال وحيواناتهم الأليفة والعنوان ومعلومات التسجيل.

يحتوي العنصر الأول على سلاسل وأرقام وبيانات منطقية ومصفوفات وخصائص متداخلة:

{
  "id": "AndersenFamily",
  "lastName": "Andersen",
  "parents": [
     { "firstName": "Thomas" },
     { "firstName": "Mary Kay"}
  ],
  "children": [
     {
         "firstName": "Henriette Thaulow",
         "gender": "female",
         "grade": 5,
         "pets": [{ "givenName": "Fluffy" }]
     }
  ],
  "address": { "state": "WA", "county": "King", "city": "Seattle" },
  "creationDate": 1431620472,
  "isRegistered": true
}

يستخدم العنصر الثاني givenName وfamilyName بدلاً من firstName وlastName:

{
  "id": "WakefieldFamily",
  "parents": [
      { "familyName": "Wakefield", "givenName": "Robin" },
      { "familyName": "Miller", "givenName": "Ben" }
  ],
  "children": [
      {
        "familyName": "Merriam",
        "givenName": "Jesse",
        "gender": "female",
        "grade": 1,
        "pets": [
            { "givenName": "Goofy" },
            { "givenName": "Shadow" }
        ]
      },
      {
        "familyName": "Miller",
         "givenName": "Lisa",
         "gender": "female",
         "grade": 8 }
  ],
  "address": { "state": "NY", "county": "Manhattan", "city": "NY" },
  "creationDate": 1431620462,
  "isRegistered": false
}

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

جرب بعض الاستعلامات مقابل بيانات JSON لفهم بعض الجوانب الرئيسية للغة استعلام SQL الخاصة بـ Azure Cosmos DB.

يقوم الاستعلام التالي بإرجاع العناصر حيث يتطابق الحقل id مع AndersenFamily. نظراً لأنه استعلام SELECT *، فإن ناتج الاستعلام هو عنصر JSON الكامل. لمزيد من المعلومات حول بنية SELECT، راجع عبارة SELECT.

    SELECT *
    FROM Families f
    WHERE f.id = "AndersenFamily"

نتائج الاستعلام هي:

    [{
        "id": "AndersenFamily",
        "lastName": "Andersen",
        "parents": [
           { "firstName": "Thomas" },
           { "firstName": "Mary Kay"}
        ],
        "children": [
           {
               "firstName": "Henriette Thaulow", "gender": "female", "grade": 5,
               "pets": [{ "givenName": "Fluffy" }]
           }
        ],
        "address": { "state": "WA", "county": "King", "city": "Seattle" },
        "creationDate": 1431620472,
        "isRegistered": true
    }]

يقوم الاستعلام التالي بإعادة تنسيق إخراج JSON إلى شكل مختلف. يعرض الاستعلام كائن JSON Family جديداً مع حقلين محددين، Name وCity، عندما تكون مدينة العنوان هي نفس الولاية. تطابق "NY، NY" هذه الحالة.

    SELECT {"Name":f.id, "City":f.address.city} AS Family
    FROM Families f
    WHERE f.address.city = f.address.state

نتائج الاستعلام هي:

    [{
        "Family": {
            "Name": "WakefieldFamily",
            "City": "NY"
        }
    }]

يعرض طلب البحث التالي جميع أسماء الأطفال في العائلة التي id تتطابق مع WakefieldFamily، مرتبة حسب المدينة.

    SELECT c.givenName
    FROM Families f
    JOIN c IN f.children
    WHERE f.id = 'WakefieldFamily'
    ORDER BY f.address.city ASC

والنتائج هي:

    [
      { "givenName": "Jesse" },
      { "givenName": "Lisa"}
    ]

الملاحظات

توضح الأمثلة السابقة عدة جوانب من لغة استعلام Cosmos DB:

  • نظراً لأن SQL API تعمل على قيم JSON، فإنها تتعامل مع كيانات على شكل شجرة بدلاً من الصفوف والأعمدة. يمكنك الرجوع إلى عقد الشجرة بأي عمق عشوائي، مثل Node1.Node2.Node3…..Nodem، على غرار المرجع المكون من جزأين لـ <table>.<column> في ANSI SQL.

  • نظراً لأن لغة الاستعلام تعمل مع بيانات المخطط، يجب ربط نظام النوع ديناميكياً. يمكن أن ينتج عن نفس التعبير أنواعاً مختلفة في عناصر مختلفة. نتيجة الاستعلام هي قيمة JSON صالحة، ولكن ليس مضموناً أن تكون ذات مخطط ثابت.

  • يدعم Azure Cosmos DB عناصر JSON الصارمة فقط. يقتصر نظام الكتابة والتعبيرات على التعامل مع أنواع JSON فقط. لمزيد من المعلومات، راجع مواصفات JSON.

  • حاوية Cosmos عبارة عن مجموعة من عناصر JSON خالية من المخطط. يتم التقاط العلاقات داخل وعبر عناصر الحاوية ضمنياً عن طريق الاحتواء، وليس عن طريق المفتاح الأساسي وعلاقات المفتاح الخارجي. هذه الميزة مهمة للصلات داخل العنصر الموضحة في الصلات في Azure Cosmos DB.

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