مفاتيح الأقسام الهرمية في Azure Cosmos DB

مقالة
08/15/2024

ينطبق على: NoSQL

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

إذا كنت تستخدم مفاتيح اصطناعية اليوم، أو كان لديك سيناريوهات يمكن أن تتجاوز فيها مفاتيح الأقسام 20 غيغابايت من البيانات، أو ترغب في التأكد من تعيين مستند كل مستأجر إلى القسم المنطقي الخاص به، يمكن أن يساعد التقسيم الفرعي. إذا كنت تستخدم هذه الميزة، يمكن أن تتجاوز بادئات مفتاح القسم المنطقي 20 غيغابايت و10000 وحدة طلب في الثانية (RU/s). يتم توجيه الاستعلامات حسب البادئة بكفاءة إلى المجموعة الفرعية من الأقسام التي تحتوي على البيانات.

اختيار مفاتيح الأقسام الهرمية

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

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

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

بالنسبة لجميع الحاويات، يجب أن يكون كل مستوى من المسار الكامل (بدءا من المستوى الأول) لمفتاح القسم الهرمي الخاص بك:
- لديك علاقة أساسية عالية. يجب أن تحتوي المفاتيح الأولى والثانية والثالثة (إن أمكن) للقسم الهرمي على مجموعة واسعة من القيم المحتملة.
  - وجود علاقة أساسية منخفضة في المستوى الأول من مفتاح القسم الهرمي سيحد من جميع عمليات الكتابة الخاصة بك في وقت الاستيعاب إلى قسم فعلي واحد فقط حتى يصل إلى 50 غيغابايت ويقسم إلى قسمين ماديين. على سبيل المثال، افترض أن مفتاح المستوى الأول قيد التشغيل TenantId وأن لديك 5 مستأجرين فريدين فقط. سيتم تحديد نطاق كل عملية من عمليات هؤلاء المستأجرين إلى قسم مادي واحد فقط، ما يحد من استهلاك معدل النقل الخاص بك إلى ما هو موجود على هذا القسم المادي. وذلك لأن الأقسام الهرمية تعمل على تحسين جميع المستندات التي لها نفس مفتاح المستوى الأول ليتم تجميعها على نفس القسم الفعلي لتجنب استعلامات التوزيع الكامل.
  - على الرغم من أن هذا قد يكون مقبولا لأحمال العمل حيث نقوم استيعاب لمرة واحدة لجميع بيانات المستأجرين لدينا والعمليات التالية ثقيلة القراءة في المقام الأول بعد ذلك، يمكن أن يكون هذا غير ظاهري لأحمال العمل حيث تتضمن متطلبات عملك استيعاب البيانات في غضون وقت محدد. على سبيل المثال، إذا كانت لديك متطلبات عمل صارمة لتجنب زمن الانتقال، فإن الحد الأقصى لمعدل النقل الذي يمكن أن يحققه حمل العمل نظريا لاستيعاب البيانات هو عدد الأقسام المادية * 10 آلاف. إذا كان مفتاح المستوى الأعلى الخاص بك له علاقة أساسية منخفضة، فمن المحتمل أن يكون عدد الأقسام الفعلية 1، ما لم تكن هناك بيانات كافية للمفتاح من المستوى 1 ليتم توزيعه عبر أقسام متعددة بعد التقسيمات التي قد تستغرق ما بين 4-6 ساعات لإكمالها.
- نشر استهلاك وحدة الطلب (RU) وتخزين البيانات بالتساوي عبر جميع الأقسام المنطقية. يضمن هذا الانتشار استهلاك وحدات الطلب وتوزيع التخزين عبر الأقسام المادية.
  - إذا اخترت مفتاح المستوى الأول الذي يبدو أن له علاقة أساسية عالية مثل UserId، ولكن في الممارسة العملية يقوم حمل العمل الخاص بك بإجراء عمليات على واحد محدد UserIdفقط ، فمن المحتمل أن تصادف قسما ساخنا حيث سيتم تحديد نطاق جميع العمليات الخاصة بك إلى قسم فعلي واحد أو عدد قليل فقط.
أحمال العمل كثيفة القراءة: نوصي باختيار مفاتيح الأقسام الهرمية التي تظهر بشكل متكرر في استعلاماتك.
- على سبيل المثال، يمكن أن يستفيد حمل العمل الذي يشغل الاستعلامات بشكل متكرر لتصفية جلسات عمل مستخدم معينة في تطبيق متعدد المستأجرين من مفاتيح الأقسام الهرمية ل TenantIdUserIdو و SessionIdبهذا الترتيب. يمكن توجيه الاستعلامات بكفاءة إلى الأقسام الفعلية ذات الصلة فقط عن طريق تضمين مفتاح القسم في دالة التقييم لعامل التصفية. لمزيد من المعلومات حول اختيار مفاتيح الأقسام لأحمال العمل الثقيلة للقراءة، راجع نظرة عامة على التقسيم.
أحمال العمل كثيفة الكتابة: نوصي باستخدام قيمة أساسية عالية للمستوى الأول من مفتاح القسم الهرمي. تعني العلاقة الأساسية العالية أن مفتاح المستوى الأول (والمستويات اللاحقة أيضا) يحتوي على الآلاف على الأقل من القيم الفريدة والقيم الفريدة أكثر من عدد الأقسام الفعلية.
- على سبيل المثال، افترض أن لدينا حمل عمل يعزل المستأجرين حسب مفتاح القسم، ويحتوي على عدد قليل من المستأجرين الكبار الذين هم أكثر كتابة من غيرهم. اليوم، سيتوقف Azure Cosmos DB عن استيعاب البيانات على أي قيمة مفتاح قسم إذا تجاوزت 20 غيغابايت من البيانات. في حمل العمل هذا، تعد Microsoft وContoso مستأجرين كبيرين ونتوقع نموها بشكل أسرع بكثير من المستأجرين الآخرين. لتجنب خطر عدم القدرة على استيعاب البيانات لهؤلاء المستأجرين، تسمح لنا مفاتيح الأقسام الهرمية بتحجيم هؤلاء المستأجرين إلى ما بعد حد 20 غيغابايت. يمكننا إضافة المزيد من المستويات مثل UserId و SessionId لضمان قابلية توسع أعلى عبر المستأجرين.
- للتأكد من أن حمل العمل الخاص بك يمكن أن يستوعب عمليات الكتابة لجميع المستندات بنفس مفتاح المستوى الأول، ضع في اعتبارك استخدام معرف العنصر كمفتاح من المستوى الثاني أو الثالث.
- إذا لم يكن لدى المستوى الأول علاقة أساسية عالية وكنت تصل إلى حد القسم المنطقي 20 غيغابايت على مفتاح القسم الخاص بك اليوم، فإننا نقترح استخدام مفتاح قسم اصطناعي بدلا من مفتاح قسم هرمي.

مثال على حالة الاستخدام

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

في سيناريو العالم الحقيقي، يمكن أن ينمو بعض المستأجرين بشكل كبير، مع آلاف المستخدمين، في حين أن العديد من المستأجرين الآخرين أصغر ولديهم عدد قليل من المستخدمين. قد يؤدي التقسيم حسب /TenantId إلى تجاوز حد تخزين Azure Cosmos DB 20 غيغابايت على قسم منطقي واحد. التقسيم عن طريق /UserId يجعل جميع الاستعلامات على المستأجر عبر الأقسام. وكلا النهجين له سلبيات كبيرة.

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

إذا كان حمل العمل الخاص بك يحتوي على مستأجرين بنفس أنماط حمل العمل تقريبا، يمكن أن يساعد مفتاح القسم الهرمي. باستخدام مفاتيح الأقسام الهرمية، يمكنك التقسيم أولا على TenantId، ثم على UserId. إذا كنت تتوقع أن TenantId تنتج المجموعة و UserId أقساما تتجاوز 20 غيغابايت، يمكنك حتى تقسيم المزيد إلى مستوى آخر، مثل على SessionId. لا يمكن أن يتجاوز العمق الإجمالي ثلاثة مستويات. عندما يتجاوز القسم المادي 50 غيغابايت من التخزين، يقوم Azure Cosmos DB تلقائيا بتقسيم القسم المادي بحيث يكون نصف البيانات تقريبا على قسم مادي واحد، ونصفها على الآخر. بشكل فعال، يعني التقسيم الفرعي أن قيمة واحدة TenantId يمكن أن تتجاوز 20 غيغابايت من البيانات، ومن الممكن أن TenantId تمتد البيانات عبر أقسام مادية متعددة.

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

استخدام معرف العنصر في التسلسل الهرمي

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

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

لمزيد من المعلومات حول استخدام معرف العنصر كمفتاح قسم، راجع نظرة عامة على التقسيم.

الشروع في العمل

هام

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

ابحث عن أحدث إصدار أولي لعدة تطوير البرامج المدعومة:

SDK	الإصدارات المدعومة	ارتباط مدير الحزمة
NET SDK. الإصدار 3	>= 3.33.0	https://www.nuget.org/packages/Microsoft.Azure.Cosmos/3.33.0/
Java SDK v4	>= 4.42.0	https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/cosmos/azure-cosmos/CHANGELOG.md#4420-2023-03-17/
JavaScript SDK v4	4.0.0	https://www.npmjs.com/package/@azure/cosmos/
Python SDK	>= 4.6.0	https://pypi.org/project/azure-cosmos/4.6.0/

إنشاء حاوية باستخدام مفاتيح الأقسام الهرمية

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

يمكنك إنشاء حاوية جديدة باستخدام أحد الخيارات التالية:

مدخل Azure
SDK
قالب Azure Resource Manager
محاكي Azure Cosmos DB

مدخل Azure

أبسط طريقة لإنشاء حاوية وتحديد مفاتيح الأقسام الهرمية هي باستخدام مدخل Microsoft Azure.

قم بتسجيل الدخول إلى بوابة Azure.
انتقل إلى صفحة حساب Azure Cosmos DB for NoSQL الموجودة.
في القائمة اليسرى، حدد Data Explorer.
في Data Explorer، حدد خيار New Container .
في حاوية جديدة، لمفتاح القسم، أدخل /TenantId. بالنسبة إلى الحقول المتبقية، أدخل أي قيمة تطابق السيناريو الخاص بك.

إشعار

/TenantId نستخدم كمثال هنا. يمكنك تحديد أي مفتاح للمستوى الأول عند تنفيذ مفاتيح الأقسام الهرمية على الحاويات الخاصة بك.
حدد Add hierarchical partition key مرتين.
بالنسبة للطبقتين الثانية والثالثة من التقسيم الفرعي، أدخل /UserId و /SessionId على التوالي.
حدد موافق لإنشاء الحاوية.

SDK

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

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<string> subpartitionKeyPaths = new List<string> { 
    "/TenantId",
    "/UserId",
    "/SessionId"
};

// Create a container properties object
ContainerProperties containerProperties = new ContainerProperties(
    id: "<container-name>",
    partitionKeyPaths: subpartitionKeyPaths
);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Container container = await database.CreateContainerIfNotExistsAsync(containerProperties, throughput: 400);

// List of partition keys, in hierarchical order. You can have up to three levels of keys.
List<String> subpartitionKeyPaths = new ArrayList<String>();
subpartitionKeyPaths.add("/TenantId");
subpartitionKeyPaths.add("/UserId");
subpartitionKeyPaths.add("/SessionId");

//Create a partition key definition object with Kind ("MultiHash") and Version V2
PartitionKeyDefinition subpartitionKeyDefinition = new PartitionKeyDefinition();
subpartitionKeyDefinition.setPaths(subpartitionKeyPaths);
subpartitionKeyDefinition.setKind(PartitionKind.MULTI_HASH);
subpartitionKeyDefinition.setVersion(PartitionKeyDefinitionVersion.V2);

// Create a container properties object
CosmosContainerProperties containerProperties = new CosmosContainerProperties("<container-name>", subpartitionKeyDefinition);

// Create a throughput properties object
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

// Create a container that's subpartitioned by TenantId > UserId > SessionId
Mono<CosmosContainerResponse> container = database.createContainerIfNotExists(containerProperties, throughputProperties);

const containerDefinition = {
  id: "Test Database",
  partitionKey: {
    paths: ["/name", "/address/zip"],
    version: PartitionKeyDefinitionVersion.V2,
    kind: PartitionKeyKind.MultiHash,
  },
}
const { container } = await database.containers.createIfNotExists(containerDefinition);
console.log(container.id);

container = database.create_container(
        id=container_name, partition_key=PartitionKey(path=["/tenantId", "/userId", "/sessionId"], kind="MultiHash")
    )

قوالب Azure Resource Manager

قالب Azure Resource Manager لحاوية فرعية متطابق تقريبا مع حاوية قياسية. الفرق الرئيسي الوحيد هو قيمة properties/partitionKey المسار. لمزيد من المعلومات حول إنشاء قالب Azure Resource Manager لمورد Azure Cosmos DB، راجع مرجع قالب Azure Resource Manager لـ Azure Cosmos DB.

قم بتكوين partitionKey الكائن باستخدام القيم الموجودة في الجدول التالي لإنشاء حاوية فرعية:

المسار	القيمة‬
`paths`	قائمة مفاتيح الأقسام الهرمية (بحدٍ أقصى ثلاثة مستويات من العمق)
`kind`	`MultiHash`
`version`	`2`

مثال تعريف مِفتاح القسم

على سبيل المثال، افترض أن لديك مفتاح قسم هرمي يتكون من TenantIdSessionId>UserId>. partitionKey سيتم تكوين الكائن لتضمين كافة القيم الثلاث في الخاصية paths وقيمة MultiHashkind و وقيمة version 2.

Bicep
JSON

partitionKey: {
  paths: [
    '/TenantId'
    '/UserId'
    '/SessionId'
  ]
  kind: 'MultiHash'
  version: 2
}

"partitionKey": {
    "paths": [
        "/TenantId",
        "/UserId",
        "/SessionId"
    ],
    "kind": "MultiHash",
    "version": 2
}

لمزيد من المعلومات حول partitionKey العنصر، راجع مواصفات ContainerPartitionKey.

محاكي Azure Cosmos DB

يمكنك اختبار ميزة التقسيم الفرعي باستخدام أحدث إصدار من المحاكي المحلي ل Azure Cosmos DB. لتمكين التقسيم الفرعي على المحاكي، ابدأ تشغيل المحاكي من دليل التثبيت مع العلامة /EnablePreview :

.\CosmosDB.Emulator.exe /EnablePreview

تحذير

لا يدعم المحاكي حاليا جميع ميزات مفتاح القسم ال hiearchical كمدخل. لا يدعم المحاكي حاليا:

استخدام Data Explorer لإنشاء حاويات بمفاتيح أقسام هرمية
استخدام مستكشف البيانات للانتقال إلى العناصر والتفاعل معها باستخدام مفاتيح الأقسام الهرمية

لمزيد من المعلومات، راجع محاكي Azure Cosmos DB.

استخدام SDKs للعمل مع الحاويات التي تحتوي على مفاتيح أقسام هرمية

عندما يكون لديك حاوية تحتوي على مفاتيح أقسام هرمية، استخدم الإصدارات المحددة مسبقا من .NET أو Java SDKs لتنفيذ العمليات وتنفيذ الاستعلامات على تلك الحاوية.

إضافة عنصر إلى حاوية

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

الاستخراج التلقائي
تحديد المسار يدويا

الاستخراج التلقائي

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

// Create a new item
UserSession item = new UserSession()
{
    id = "f7da01b0-090b-41d2-8416-dacae09fbb4a",
    TenantId = "Microsoft",
    UserId = "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b",
    SessionId = "0000-11-0000-1111"
};

// Pass in the object, and the SDK automatically extracts the full partition key path
ItemResponse<UserSession> createResponse = await container.CreateItemAsync(item);

// Create a new item
UserSession item = new UserSession();
item.setId("f7da01b0-090b-41d2-8416-dacae09fbb4a");
item.setTenantId("Microsoft");
item.setUserId("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b");
item.setSessionId("0000-11-0000-1111");
   
// Pass in the object, and the SDK automatically extracts the full partition key path
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item);

 // Create a new item
const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
    SessionId: '0000-11-0000-1111'
}

// Pass in the object, and the SDK automatically extracts the full partition key path
const { resource: document } = await = container.items.create(item);

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

تحديد المسار يدويا

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

تلميح

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

// Create a new item object
PaymentEvent item = new PaymentEvent()
{
    id = Guid.NewGuid().ToString(),
    TenantId = "Microsoft",
    UserId = "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b",
    SessionId = "0000-11-0000-1111"
};

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .Add(item.TenantId)
            .Add(item.UserId)
            .Add(item.SessionId)
            .Build();

// Create the item in the container
ItemResponse<PaymentEvent> createResponse = await container.CreateItemAsync(item, partitionKey);

// Create a new item object
UserSession item = new UserSession();
item.setTenantId("Microsoft");
item.setUserId("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b");
item.setSessionId("0000-11-0000-1111");
item.setId(UUID.randomUUID().toString());

// Specify the full partition key path when creating the item
PartitionKey partitionKey = new PartitionKeyBuilder()
            .add(item.getTenantId())
            .add(item.getUserId())
            .add(item.getSessionId())
            .build();
       
// Create the item in the container     
Mono<CosmosItemResponse<UserSession>> createResponse = container.createItem(item, partitionKey);

const item: UserSession = {
    Id: 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
    TenantId: 'Microsoft',
    UserId: '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
    SessionId: '0000-11-0000-1111'
}

// Specify the full partition key path when creating the item
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Create the item in the container
const { resource: document } = await container.items.create(item, partitionKey);

بالنسبة إلى python، ما عليك سوى التأكد من تحديد قيم كافة الحقول في مسار مفتاح القسم في تعريف العنصر.

# specify values for all fields on partition key path
item_definition = {'id': 'f7da01b0-090b-41d2-8416-dacae09fbb4a',
                        'tenantId': 'Microsoft',
                        'userId': '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b',
                        'sessionId': '0000-11-0000-1111'}

item = container.create_item(body=item_definition)

إجراء بحث عن مفتاح/قيمة (قراءة نقطة) لعنصر

يتم تنفيذ عمليات البحث عن المفتاح/القيمة (قراءات النقاط) بطريقة مشابهة لحاوية غير فرعية. على سبيل المثال، افترض أن لديك مفتاح قسم هرمي يتكون من TenantIdSessionId>UserId>. المعرف الفريد للعنصر هو GUID. يتم تمثيله كسلسلة تعمل كمعرف معاملة مستند فريد. لتنفيذ قراءة نقطة على عنصر واحد، قم بتمرير خاصية العنصر والقيمة الكاملة لمفتاح القسم، بما في id ذلك جميع المكونات الثلاثة للمسار.

// Store the unique identifier
string id = "f7da01b0-090b-41d2-8416-dacae09fbb4a";

// Build the full partition key path
PartitionKey partitionKey = new PartitionKeyBuilder()
    .Add("Microsoft") //TenantId
    .Add("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b") //UserId
    .Add("0000-11-0000-1111") //SessionId
    .Build();

// Perform a point read
ItemResponse<UserSession> readResponse = await container.ReadItemAsync<UserSession>(
    id,
    partitionKey
);

// Store the unique identifier
String id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"; 

// Build the full partition key path
PartitionKey partitionKey = new PartitionKeyBuilder()
    .add("Microsoft") //TenantId
    .add("8411f20f-be3e-416a-a3e7-dcd5a3c1f28b") //UserId
    .add("0000-11-0000-1111") //SessionId
    .build();
    
// Perform a point read
Mono<CosmosItemResponse<UserSession>> readResponse = container.readItem(id, partitionKey, UserSession.class);

// Store the unique identifier
const id = "f7da01b0-090b-41d2-8416-dacae09fbb4a";

// Build the full partition key path
const partitionKey: PartitionKey = new PartitionKeyBuilder()
    .addValue(item.TenantId)
    .addValue(item.UserId)
    .addValue(item.SessionId)
    .build();

// Perform a point read
const { resource: document } = await container.item(id, partitionKey).read();

item_id = "f7da01b0-090b-41d2-8416-dacae09fbb4a"
pk = ["Microsoft", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b", "0000-11-0000-1111"]
container.read_item(item=item_id, partition_key=pk)

تشغيل استعلام

التعليمات البرمجية SDK التي تستخدمها لتشغيل استعلام على حاوية فرعية مماثلة لتشغيل استعلام على حاوية غير فرعية.

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

على سبيل المثال، ضع في اعتبارك مفتاح قسم هرمي يتكون من TenantIdSessionId>UserId>. تحدد مكونات عامل تصفية الاستعلام ما إذا كان الاستعلام عبارة عن استعلام قسم واحد أو استعلام مستهدف عبر الأقسام أو استعلام توزيع.

الاستعلام	التوجيه
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b' AND c.SessionId = '0000-11-0000-1111'`	يتم توجيهه إلى القسم المنطقي والمادي الفردي الذي يحتوي على بيانات القيم المحددة من `TenantId`و `UserId`و.`SessionId`
`SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b'`	يتم توجيهها إلى المجموعة الفرعية المستهدفة فقط من الأقسام المنطقية والمادية التي تحتوي على بيانات للقيم المحددة لـ `TenantId` و `UserId`. يعد هذا الاستعلام استعلامًا مستهدفًا عبر الأقسام يقوم بإرجاع البيانات لمستخدم معين في المستأجر.
`SELECT * FROM c WHERE c.TenantId = 'Microsoft'`	يتم توجيهها إلى المجموعة الفرعية المستهدفة فقط من الأقسام المنطقية والمادية التي تحتوي على بيانات للقيم المحددة لـ `TenantId`. يُعد هذا الاستعلام استعلامًا مستهدفًا عبر الأقسام يقوم بإرجاع البيانات لجميع المستخدمين في المستأجر.
`SELECT * FROM c WHERE c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b'`	يتم توجيهها إلى جميع الأقسام المادية، ما يؤدي إلى استعلام توزيع عبر الأقسام.
`SELECT * FROM c WHERE c.SessionId = '0000-11-0000-1111'`	يتم توجيهها إلى جميع الأقسام المادية، ما يؤدي إلى استعلام توزيع عبر الأقسام.

استعلام قسم واحد على حاويةٍ فرعية

فيما يلي مثال على تشغيل استعلام يتضمن جميع مستويات التقسيم الفرعي، مما يجعل الاستعلام استعلام قسم واحد بشكل فعال.

// Define a single-partition query that specifies the full partition key path
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id AND c.UserId = @user-id AND c.SessionId = @session-id")
    .WithParameter("@tenant-id", "Microsoft")
    .WithParameter("@user-id", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b")
    .WithParameter("@session-id", "0000-11-0000-1111");

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

// Define a single-partition query that specifies the full partition key path
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s' AND c.UserId = '%s' AND c.SessionId = '%s'",
    "Microsoft",
    "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b",
    "0000-11-0000-1111"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a single-partition query that specifies the full partition key path
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft' AND c.UserId = '8411f20f-be3e-416a-a3e7-dcd5a3c1f28b' AND c.SessionId = '0000-11-0000-1111'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b", "0000-11-0000-1111"]
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id and r.sessionId=@session_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]},
        {"name": "@session_id", "value": pk[2]}
    ]
))

استعلام متعدد الأقسام المستهدفة على حاوية فرعية

فيما يلي مثال على استعلام يتضمن مجموعة فرعية من مستويات التقسيم الفرعي، مما يجعل هذا الاستعلام استعلاما مستهدفا متعدد الأقسام.

// Define a targeted cross-partition query specifying prefix path[s]
QueryDefinition query = new QueryDefinition(
    "SELECT * FROM c WHERE c.TenantId = @tenant-id")
    .WithParameter("@tenant-id", "Microsoft")

// Retrieve an iterator for the result set
using FeedIterator<PaymentEvent> results = container.GetItemQueryIterator<PaymentEvent>(query);

while (results.HasMoreResults)
{
    FeedResponse<UserSession> resultsPage = await resultSet.ReadNextAsync();
    foreach(UserSession result in resultsPage)
    {
        // Process result
    }
}

// Define a targeted cross-partition query specifying prefix path[s]
String query = String.format(
    "SELECT * FROM c WHERE c.TenantId = '%s'",
    "Microsoft"
);

// Retrieve an iterator for the result set
CosmosPagedFlux<UserSession> pagedResponse = container.queryItems(
    query, options, UserSession.class);

pagedResponse.byPage().flatMap(fluxResponse -> {
    for (UserSession result : page.getResults()) {
        // Process result
    }
    return Flux.empty();
}).blockLast();

// Define a targeted cross-partition query specifying prefix path[s]
const query: string = "SELECT * FROM c WHERE c.TenantId = 'Microsoft'";

// Retrieve an iterator for the result set
const queryIterator = container.items.query(query);

while (queryIterator.hasMoreResults()) {
    const { resources: results } = await queryIterator.fetchNext();
    // Process result
}

pk = ["Microsoft", "8411f20f-be3e-416a-a3e7-dcd5a3c1f28b", "0000-11-0000-1111"]
# enable_cross_partition_query should be set to True as the container is partitioned
items = list(container.query_items(
    query="SELECT * FROM r WHERE r.tenantId=@tenant_id and r.userId=@user_id",
    parameters=[
        {"name": "@tenant_id", "value": pk[0]},
        {"name": "@user_id", "value": pk[1]}
    ],
    enable_cross_partition_query=True
))

القيود والمشاكل المعروفة

يتم دعم العمل مع الحاويات التي تستخدم مفاتيح الأقسام الهرمية فقط في .NET v3 SDK، وفي Java v4 SDK، وفي Python SDK، وفي إصدار المعاينة من JavaScript SDK. يجب استخدام SDK مدعوم لإنشاء حاويات جديدة تحتوي على مفاتيح أقسام هرمية ولإجراء عمليات CRUD أو الاستعلام على البيانات. لا يتوفر الدعم ل SDKs الأخرى، بما في ذلك Python، حاليا.
هناك قيود مع موصلات Azure Cosmos DB المختلفة (على سبيل المثال، مع Azure Data Factory).
يمكنك تحديد مفاتيح الأقسام الهرمية حتى ثلاث طبقات فقط في العمق.
يمكن تمكين مفاتيح الأقسام الهرمية حاليا فقط على حاويات جديدة. يجب تعيين مسارات مفتاح القسم في وقت إنشاء الحاوية، ولا يمكنك تغييرها لاحقا. لاستخدام الأقسام الهرمية على الحاويات الموجودة، قم بإنشاء حاوية جديدة مع تعيين مفاتيح الأقسام الهرمية ونقل البيانات باستخدام مهام نسخ الحاوية.
مفاتيح الأقسام الهرمية مدعومة حاليا فقط لواجهة برمجة التطبيقات لحسابات NoSQL. واجهات برمجة التطبيقات ل MongoDB وCassandra غير مدعومة حاليا.
مفاتيح الأقسام الهرمية غير مدعومة حاليا مع ميزة المستخدمين والأذونات. لا يمكنك تعيين إذن لبادئة جزئية لمسار مفتاح القسم الهرمي. يمكن تعيين الأذونات فقط لمسار مفتاح القسم المنطقي بأكمله. على سبيل المثال، إذا قمت بتقسيم حسب TenantId - >UserId، فلا يمكنك تعيين إذن لقيمة معينة من TenantId. ومع ذلك، يمكنك تعيين إذن لمفتاح قسم إذا قمت بتحديد كل من قيمة TenantId و'UserId''.

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

راجع الأسئلة المُتداولة حول مفاتيح الأقسام الهرمية.
تعلّم المزيد حول التقسيم في Azure Cosmos DB.
تعرّف على المزيد حول استخدام قوالب Azure Resource Manager مع Azure Cosmos DB.

مشاركة عبر