مشاركة عبر

واجهة برمجة تطبيقات الاستعلام المتكاملة مع JavaScript في Azure Cosmos DB

  • مقالة

ينطبق على: NoSQL

بالإضافة إلى إصدار الاستعلامات باستخدام واجهة برمجة التطبيقات ل NoSQL في Azure Cosmos DB، يوفر SDK من جانب خادم Azure Cosmos DB واجهة JavaScript لتنفيذ الاستعلامات المحسنة في الإجراءات والمشغلات المخزنة في Azure Cosmos DB. غير مطلوب منك معرف لغة SQL لاستخدام واجهة JavaScript هذه. تسمح لك واجهة برمجة تطبيقات استعلام JavaScript بإنشاء استعلامات برمجيا عن طريق تمرير دالات التقييم إلى تسلسل من استدعاءات الدالة، مع بناء جملة مشابهة لمضمنات صفيف ECMAScript5 ومكتبات JavaScript الشائعة مثل Lodash. تُوزّع الاستعلامات حسب وقت تشغيل JavaScript وتُنفّذ بكفاءة باستخدام مؤشرات Azure Cosmos DB.

كائنات JavaScript المدعومة

دالة الوصف
chain() ... .value([callback] [, options]) تبدأ استدعاء متسلسل يجب إنهاؤه بالقيمة().
filter(predicateFunction [, options] [, callback]) تساعد في تصفية الإدخال باستخدام دالة تقييم تكتب صحيح/خطأ لتصفية مستندات الداخل/الخرج في المجموعة الناتجة. تعمل هذه الدالة بشكل مشابه لعبارة WHERE في SQL.
flatten([isShallow] [, options] [, callback]) تجمع الصفيفات من كل عنصر إدخال في صفيف واحد وتدمجها. تعمل هذه الدالة بشكل مشابه لـ SelectMany في LINQ.
map(transformationFunction [, options] [, callback]) تستخدم إسقاط مع تحديد دالة تحويل تعيِّن كل عنصر إدخال إلى كائن أو قيمة JavaScript. تعمل هذه الدالة بشكل مشابه لعبارة SELECT في SQL.
pluck([propertyName] [, options] [, callback]) تمثل هذه الدالة اختصاراً لخريطة تستخرج قيمة خاصية واحدة من كل عنصر إدخال.
sortBy([predicate] [, options] [, callback]) تنتج مجموعة جديدة من المستندات عن طريق فرز المستندات في دفق مستند الإدخال بترتيب تصاعدي باستخدام دالة التقييم المحددة. تعمل هذه الدالة بشكل مشابه لعبارة ORDER BY في SQL.
sortByDescending([predicate] [, options] [, callback]) تنتج مجموعة جديدة من المستندات عن طريق فرز المستندات في دفق مستند الإدخال بترتيب تنازلي باستخدام دالة التقييم المحددة. تعمل هذه الدالة بشكل مشابه لعبارة ORDER BY x DESC في SQL.
unwind(collectionSelector, [resultSelector], [options], [callback]) تنفِّذ ترابطاً داخلياً مع الصفيف الداخلي وتضيف نتائج من كلا الجانبين كمجموعات إلى الإسقاط الناتج. على سبيل المثال، فإن انضمام وثيقة شخص مع person.pets قد ينتج مجموعات [شخص وحيوان أليف]. يشبه هذا SelectMany في .NET LINQ.

عند تضمينه داخل دالات التقييم و/أو المحدد، تُحسّن بنيات JavaScript التالية تلقائياً لتشغيلها مباشرة على مؤشرات Azure Cosmos DB:

  • عوامل تشغيل بسيطة: = + - * / % | ^ & == != === !== < > <= >= || && << >> >>> ~
  • القيم الحرفية، بما فيها القيم الحرفية للكائن: {}
  • المتغير، العودة

لا تُحسَن بنيات JavaScript التالية للاستخدام مع مؤشرات Azure Cosmos DB:

  • تدفق التحكم: if for while
  • استدعاءات الدالة

لمزيد من المعلومات، راجع وثائق JavaScript من جانب خادم Azure Cosmos DB.

SQL لورقة المعلومات المرجعية لـ JavaScript

يعرض الجدول التالي عدة استعلامات متنوعة لـ SQL واستعلامات JavaScript المطابقة. كما هو الحال مع استعلامات SQL، فإن الخصائص (على سبيل المثال، item.id) حساسة لحالة الأحرف.

إشعار

__ (شرطة سفلية مزدوجة) هي اسم مستعار لـ getContext().getCollection() عند استخدام API استعلام JavaScript.

SQL واجهة برمجة تطبيقات استعلام JavaScript الوصف
SELECT *
مستندات FROM		 __.map(function(doc) {
    المستند الناتج؛
});		 النتائج في جميع المستندات (مرقمة برمز متابعة) كما هي.
اختار
   docs.id,
   docs.message AS msg,
   docs.actions
مستندات FROM		 __.map(function(doc) {
    الناتج {
        id: doc.id,
        msg: doc.message,
        actions:doc.actions
    };
});		 يعرض المُعرِف والرسالة (مسمى باسم مستعار msg)، والإجراء من جميع المستندات.
SELECT *
مستندات FROM
WHERE
   docs.id="X998_Y998"		 __.filter(function(doc) {
    return doc.id ==="X998_Y998";
});		 استعلامات المستندات ذات دالة التقييم: "X998_Y998".
SELECT *
مستندات FROM
WHERE
   ARRAY_CONTAINS(docs.Tags, 123)		 __.filter(function(x) {
    إرجاع x.Tags &x.Tags.indexOf(123) > -1;
});		 استعلامات المستندات التي تحتوي على خاصية العلامات وتوجد العلامات في صفيف يحتوي على القيمة 123.
حدد …
   docs.id,
   docs.message AS msg
مستندات FROM
WHERE
   docs.id="X998_Y998"		 __.chain()
    .filter(function(doc) {
        return doc.id ==="X998_Y998";
    })
    .map(function(doc) {
       الناتج {
            id: doc.id,
            msg: doc.message
       };
    })
.value();		 استعلامات المستندات ذات دالة التقييم، معرف = "X998_Y998"، تعرض المعرف والرسالة (مسمى بالاسم المستعار msg).
علامة SELECT VALUE
مستندات FROM
JOIN tag IN docs.Tags
ترتيب حسب docs._ts		 __.chain()
    .filter(function(doc) {
        return doc.Tags && Array.isArray(doc.Tags);
    })
    .sortBy(function(doc) {
        return doc._ts;
    })
    .pluck("Tags")
    .flatten()
    .value()		 عوامل تصفية المستندات التي تحتوي على خاصية الصفيف والعلامات وتفرز المستندات الناتجة باستخدام خاصية نظام الطابع الزمني _ts وتعرض الصفيف Tags وتدمجها.

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

تعرّف على مزيد من المفاهيم وكيفية كتابة الإجراءات المخزنة والمشغلات والدالات المعروفة للمستخدم أو استخدامها في Azure Cosmos DB: