الخصائص المحسوبة في Azure Cosmos DB ل NoSQL

ينطبق على: NoSQL

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

إشعار

هل لديك أي ملاحظات حول الخصائص المحسوبة؟ نريد أن نسمعه! لا تتردد في مشاركة الملاحظات مباشرة مع فريق هندسة Azure Cosmos DB: cosmoscomputedprops@microsoft.com.

ما هي الخاصية المحسوبة؟

يجب أن تكون الخصائص المحسوبة في المستوى الأعلى في العنصر ولا يمكن أن يكون لها مسار متداخل. يحتوي كل تعريف خاصية حوسبة على مكونين: اسم واستعلام. الاسم هو اسم الخاصية المحسوبة، ويحدد الاستعلام المنطق لحساب قيمة الخاصية لكل عنصر. يتم تحديد نطاق الخصائص المحسوبة لعنصر فردي وبالتالي لا يمكن استخدام قيم من عناصر متعددة أو الاعتماد على خصائص محسوبة أخرى. يمكن أن يكون لكل حاوية 20 خاصية حوسبة كحد أقصى.

مثال تعريف الخاصية المحسوبة:

{
  "computedProperties": [
    {
      "name": "cp_lowerName",
      "query": "SELECT VALUE LOWER(c.name) FROM c"
    }
  ]
}

قيود الاسم

نوصي بشدة بتسمية الخصائص المحسوبة بحيث لا يوجد تضارب مع اسم الخاصية المستمر. لتجنب تداخل أسماء الخصائص، يمكنك إضافة بادئة أو لاحقة إلى كافة أسماء الخصائص المحسوبة. تستخدم هذه المقالة البادئة cp_ في كافة تعريفات الأسماء.

هام

لا يؤدي تعريف خاصية حوسبة باستخدام نفس اسم الخاصية المستمرة إلى حدوث خطأ، ولكنه قد يؤدي إلى سلوك غير متوقع. بغض النظر عما إذا كانت الخاصية المحسوبة مفهرسة، لن يتم تضمين القيم من الخصائص المستمرة التي تشترك في اسم مع خاصية حوسبة في الفهرس. ستستخدم الاستعلامات دائما الخاصية المحسوبة بدلا من الخاصية الدائمة، باستثناء الخاصية الدائمة التي يتم إرجاعها بدلا من الخاصية المحسوبة إذا كان هناك إسقاط حرف بدل في عبارة SELECT. لا يتضمن إسقاط حرف البدل تلقائيا الخصائص المحسوبة.

القيود المفروضة على أسماء الخصائص المحسوبة هي:

• يجب أن تحتوي جميع الخصائص المحسوبة على أسماء فريدة.
• تمثل قيمة الخاصية name اسم خاصية المستوى الأعلى الذي يمكن استخدامه للإشارة إلى الخاصية المحسوبة.
• لا يمكن استخدام أسماء خصائص النظام المحجوزة مثل idو _ridوأسماء _ts الخصائص المحسوبة.
• لا يمكن أن يتطابق اسم الخاصية المحسوبة مع مسار خاصية تمت فهرسته بالفعل. ينطبق هذا القيد على كافة مسارات الفهرسة المحددة، بما في ذلك:
  • المسارات المضمنة
  • المسارات المستبعدة
  • الفهارس المكانية
  • الفهارس المركبة

قيود الاستعلام

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

القيود المفروضة على تعريفات استعلام الخاصية المحسوبة هي:

• يجب أن تحدد الاستعلامات عبارة FROM التي تمثل مرجع العنصر الجذر. أمثلة على عبارات FROM المدعومة هي: FROM cو FROM root cو.FROM MyContainer c
• يجب أن تستخدم الاستعلامات عبارة VALUE في الإسقاط.
• لا يمكن أن تتضمن الاستعلامات JOIN.
• لا يمكن للاستعلامات استخدام تعبيرات عددية غير محددة. أمثلة على التعبيرات العددية غير المحددة هي: GetCurrentDateTime و GetCurrentTimeStamp و GetCurrentTicks و RAND.
• لا يمكن للاستعلامات استخدام أي من العبارات التالية: WHERE وGROUP BY و ORDER BY و TOP و DISTINCT و OFFSET LIMIT و EXISTS و ALL و LAST و FIRST و NONE.
• لا يمكن أن تتضمن الاستعلامات استعلاما فرعيا عدديا.
• لا يتم دعم الدوال التجميعية والوظائف المكانية والدالات غير المحددة والدالات المعرفة من قبل المستخدم (UDFs).

إنشاء خصائص حوسبة

بعد إنشاء الخصائص المحسوبة، يمكنك تنفيذ الاستعلامات التي تشير إلى الخصائص باستخدام أي أسلوب، بما في ذلك جميع SDKs وAzure Data Explorer في مدخل Microsoft Azure.

	إصدار مدعوم	ملاحظات
NET SDK. الإصدار 3	>= 3.34.0-معاينة	تتوفر الخصائص المحسوبة حاليا فقط في إصدارات حزمة المعاينة.
Java SDK v4	>= 4.46.0	الخصائص المحسوبة حاليا ضمن إصدار المعاينة.
Python SDK	>= v4.5.2b5	الخصائص المحسوبة حاليا ضمن إصدار المعاينة.

إنشاء خصائص محسوبة باستخدام SDK

يمكنك إما إنشاء حاوية جديدة تحتوي على خصائص حوسبة معرفة، أو يمكنك إضافة خصائص حوسبة إلى حاوية موجودة.

فيما يلي مثال على كيفية إنشاء خصائص حوسبة في حاوية جديدة:

NET.

ContainerProperties containerProperties = new ContainerProperties("myContainer", "/pk")
{
    ComputedProperties = new Collection<ComputedProperty>
    {
        new ComputedProperty
        {
            Name = "cp_lowerName",
            Query = "SELECT VALUE LOWER(c.name) FROM c"
        }
    }
};

Container container = await client.GetDatabase("myDatabase").CreateContainerAsync(containerProperties);

Java

CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/pk");
List<ComputedProperty> computedProperties = new ArrayList<>(List.of(new ComputedProperty("cp_lowerName", "SELECT VALUE LOWER(c.name) FROM c")));
containerProperties.setComputedProperties(computedProperties);
client.getDatabase("myDatabase").createContainer(containerProperties);

Python

يمكنك تعريف خصائص متعددة حوسبة في قائمة ثم إضافتها إلى خصائص الحاوية. لا يدعم Python SDK حاليا الخصائص المحسوبة على الحاويات الموجودة.

computed_properties = [{'name': "cp_lower", 'query': "SELECT VALUE LOWER(c.db_group) FROM c"},
                       {'name': "cp_power", 'query': "SELECT VALUE POWER(c.val, 2) FROM c"},
                       {'name': "cp_str_len", 'query': "SELECT VALUE LENGTH(c.stringProperty) FROM c"}]

container_with_computed_props = db.create_container_if_not_exists(
            "myContainer", PartitionKey(path="/pk"), computed_properties=computed_properties)

يمكن استخدام الخصائص المحسوبة مثل أي خاصية أخرى في الاستعلامات. على سبيل المثال، يمكنك استخدام الخاصية cp_lower المحسوبة في استعلام مثل هذا:

queried_items = list(
            container_with_computed_props.query_items(query='Select * from c Where c.cp_power = 25', partition_key="test"))

فيما يلي مثال على كيفية تحديث الخصائص المحسوبة على حاوية موجودة:

NET.

var container = client.GetDatabase("myDatabase").GetContainer("myContainer");

// Read the current container properties
var containerProperties = await container.ReadContainerAsync();
// Make the necessary updates to the container properties
containerProperties.Resource.ComputedProperties = new Collection<ComputedProperty>
    {
        new ComputedProperty
        {
            Name = "cp_lowerName",
            Query = "SELECT VALUE LOWER(c.name) FROM c"
        },
        new ComputedProperty
        {
            Name = "cp_upperName",
            Query = "SELECT VALUE UPPER(c.name) FROM c"
        }
    };
// Update the container with changes
await container.ReplaceContainerAsync(containerProperties);

Java

CosmosContainer container = client.getDatabase("myDatabase").getContainer("myContainer");
// Read the current container properties
CosmosContainerProperties containerProperties = container.read().getProperties();
// Make the necessary updates to the container properties
Collection<ComputedProperty> modifiedComputedProperites = containerProperties.getComputedProperties();
modifiedComputedProperites.add(new ComputedProperty("cp_upperName", "SELECT VALUE UPPER(c.firstName) FROM c"));
containerProperties.setComputedProperties(modifiedComputedProperites);
// Update the container with changes
container.replace(containerProperties);

Python

تحديث الخصائص المحسوبة على حاوية موجودة غير معتمد في Python SDK. يمكنك فقط تعريف الخصائص المحسوبة عند إنشاء حاوية جديدة. هذا عمل قيد التقدم حاليا.

تلميح

في كل مرة تقوم فيها بتحديث خصائص الحاوية، تتم الكتابة فوق القيم القديمة. إذا كانت لديك خصائص حوسبة موجودة وتريد إضافة خصائص جديدة، فتأكد من إضافة خصائص حوسبة جديدة وموجودة إلى المجموعة.

استخدام الخصائص المحسوبة في الاستعلامات

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

تستخدم الأمثلة التالية مجموعة بيانات منتجات التشغيل السريع المتوفرة في Data Explorer في مدخل Microsoft Azure. للبدء، حدد تشغيل البدء السريع وتحميل مجموعة البيانات في حاوية جديدة.

فيما يلي مثال على عنصر:

{
  "id": "08225A9E-F2B3-4FA3-AB08-8C70ADD6C3C2",
  "categoryId": "75BF1ACB-168D-469C-9AA3-1FD26BB4EA4C",
  "categoryName": "Bikes, Touring Bikes",
  "sku": "BK-T79U-50",
  "name": "Touring-1000 Blue, 50",
  "description": "The product called \"Touring-1000 Blue, 50\"",
  "price": 2384.07,
  "tags": [
    {
      "id": "27B7F8D5-1009-45B8-88F5-41008A0F0393",
      "name": "Tag-61"
    }
  ],
  "_rid": "n7AmAPTJ480GAAAAAAAAAA==",
  "_self": "dbs/n7AmAA==/colls/n7AmAPTJ480=/docs/n7AmAPTJ480GAAAAAAAAAA==/",
  "_etag": "\"01002683-0000-0800-0000-6451fb4b0000\"",
  "_attachments": "attachments/",
  "_ts": 1683094347
}

إسقاط

إذا كانت الخصائص المحسوبة بحاجة إلى العرض، فيجب الرجوع إليها بشكل صريح. إسقاطات أحرف البدل مثل SELECT * إرجاع جميع الخصائص المستمرة، ولكنها لا تتضمن خصائص محسوبة.

فيما يلي مثال لتعريف الخاصية المحسوبة لتحويل الخاصية name إلى أحرف صغيرة:

{ 
  "name": "cp_lowerName", 
  "query": "SELECT VALUE LOWER(c.name) FROM c" 
} 

يمكن بعد ذلك عرض هذه الخاصية في استعلام:

SELECT 
    c.cp_lowerName 
FROM 
    c

عبارة WHERE

يمكن الرجوع إلى الخصائص المحسوبة في دالات تقييم التصفية مثل أي خصائص ثابتة. نوصي بإضافة أي فهارس مفردة أو مركبة ذات صلة عند استخدام الخصائص المحسوبة في عوامل التصفية.

فيما يلي مثال لتعريف الخاصية المحسوبة لحساب خصم سعر 20 بالمائة:

{ 
  "name": "cp_20PercentDiscount", 
  "query": "SELECT VALUE (c.price * 0.2) FROM c" 
} 

يمكن بعد ذلك تصفية هذه الخاصية للتأكد من إرجاع المنتجات التي يكون الخصم فيها أقل من 50 دولارا فقط:

SELECT 
    c.price - c.cp_20PercentDiscount as discountedPrice, 
    c.name 
FROM 
    c 
WHERE 
    c.cp_20PercentDiscount < 50.00

عبارة GROUP BY

كما هو الحال مع الخصائص المستمرة، يمكن الرجوع إلى الخصائص المحسوبة في عبارة GROUP BY واستخدام الفهرس كلما أمكن ذلك. للحصول على أفضل أداء، أضف أي فهارس مفردة أو مركبة ذات صلة.

فيما يلي مثال لتعريف الخاصية المحسوبة الذي يعثر على الفئة الأساسية لكل عنصر من الخاصية categoryName :

{
  "name": "cp_primaryCategory",
  "query": "SELECT VALUE SUBSTRING(c.categoryName, 0, INDEX_OF(c.categoryName, ',')) FROM c"
}

يمكنك بعد ذلك التجميع حسب cp_primaryCategory للحصول على عدد العناصر في كل فئة أساسية:

SELECT 
    COUNT(1), 
    c.cp_primaryCategory 
FROM 
    c 
GROUP BY 
    c.cp_primaryCategory

تلميح

على الرغم من أنه يمكنك أيضا تحقيق هذا الاستعلام دون استخدام الخصائص المحسوبة، فإن استخدام الخصائص المحسوبة يبسط كتابة الاستعلام بشكل كبير ويسمح بزيادة الأداء لأنه cp_primaryCategory يمكن فهرسته. يتطلب كل من SUBSTRING() و INDEX_OF() فحصا كاملا لجميع العناصر في الحاوية، ولكن إذا قمت بفهرسة الخاصية المحسوبة، فيمكن تقديم الاستعلام بأكمله من الفهرس بدلا من ذلك. القدرة على خدمة الاستعلام من الفهرس بدلا من الاعتماد على فحص كامل يزيد من الأداء ويخفض تكاليف وحدة طلب الاستعلام (RU).

عبارة ORDER BY

كما هو الحال مع الخصائص المستمرة، يمكن الرجوع إلى الخصائص المحسوبة في عبارة ORDER BY، ويجب فهرستها حتى ينجح الاستعلام. باستخدام الخصائص المحسوبة، يمكنك ORDER BY نتيجة دالات النظام أو المنطق المعقدة، والتي تفتح العديد من سيناريوهات الاستعلام الجديدة عند استخدام Azure Cosmos DB.

فيما يلي مثال لتعريف الخاصية المحسوبة الذي يحصل على الشهر من _ts القيمة:

{
  "name": "cp_monthUpdated",
  "query": "SELECT VALUE DateTimePart('m', TimestampToDateTime(c._ts*1000)) FROM c"
}

قبل أن تتمكن من ORDER BY cp_monthUpdated، يجب إضافته إلى نهج الفهرسة. بعد تحديث نهج الفهرسة، يمكنك الترتيب حسب الخاصية المحسوبة.

SELECT
    *
FROM
    c
ORDER BY
    c.cp_monthUpdated

خصائص الفهرس المحسوبة

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

هناك بعض الاعتبارات لفهرسة الخصائص المحسوبة، بما في ذلك:

• يمكن تحديد الخصائص المحسوبة في المسارات المضمنة والمسارات المستبعدة ومسارات الفهرس المركبة.
• لا يمكن أن يكون للخصائص المحسوبة فهرس مكاني محدد عليها.
• تعمل مسارات حرف البدل ضمن مسار الخاصية المحسوبة كما تفعل للخصائص العادية.
• إذا كنت تقوم بإزالة خاصية محسوبة تمت فهرستها، فيجب أيضا إسقاط جميع الفهارس الموجودة على هذه الخاصية.

إشعار

يتم تعريف جميع الخصائص المحسوبة في المستوى الأعلى للعنصر. المسار هو دائما /<computed property name>.

تلميح

في كل مرة تقوم فيها بتحديث خصائص الحاوية، تتم الكتابة فوق القيم القديمة. إذا كانت لديك خصائص حوسبة موجودة وتريد إضافة خصائص جديدة، فتأكد من إضافة خصائص حوسبة جديدة وموجودة إلى المجموعة.

إشعار

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

إذا كنت تريد حذف خاصية حوسبة، فستحتاج أولا إلى إزالتها من نهج الفهرس.

إضافة فهرس واحد للخصائص المحسوبة

لإضافة فهرس واحد لخاصية حوسبة تسمى cp_myComputedProperty:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/*"
    },
    {
      "path": "/cp_myComputedProperty/?"
    }
  ],
  "excludedPaths": [
    {
      "path": "/\"_etag\"/?"
    }
  ]
}

إضافة فهرس مركب للخصائص المحسوبة

لإضافة فهرس مركب على خاصيتين يتم حساب إحداهما ك cp_myComputedProperty، والأخرى ثابتة ك myPersistedProperty:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/*"
    }
  ],
  "excludedPaths": [
    {
      "path": "/\"_etag\"/?"
    }
  ],
  "compositeIndexes": [
    [
      {
        "path": "/cp_myComputedProperty"
      },
      {
        "path": "/path/to/myPersistedProperty"
      }
    ]
  ]
}

فهم استهلاك وحدة الطلب

لا تستهلك إضافة الخصائص المحسوبة إلى حاوية وحدات الطلب. قد يكون لعمليات الكتابة على الحاويات التي تحتوي على خصائص حوسبة محددة زيادة طفيفة في وحدات الطلب. إذا تمت فهرسة خاصية حوسبة، تزيد وحدات الطلب على عمليات الكتابة لتعكس تكاليف الفهرسة والتقييم للخاصية المحسوبة.

المحتوى ذو الصلة

• إدارة نهج الفهرسة
• بيانات مستند النموذج