إدارة نهج الفهرسة في Azure Cosmos DB
ينطبق على: 
NoSQL
في Azure Cosmos DB، تُفهرَس البيانات باتباع نهج الفهرسة المحددة لكل حاوية. يفرض نهج الفهرسة الافتراضي للحاويات المنشأة حديثا فهارس النطاق لأي سلسلة أو رقم. يمكنك تجاوز هذا النهج باستخدام نهج الفهرسة المخصص الخاص بك.
إشعار
تنطبق طريقة تحديث نهج الفهرسة الموضحة في هذه المقالة فقط على Azure Cosmos DB ل NoSQL. تعرف على الفهرسة في Azure Cosmos DB ل MongoDB والفهرسة الثانوية في Azure Cosmos DB ل Apache Cassandra.
أمثلة عن نهج الفهرسة
فيما يلي بعض الأمثلة على نهج الفهرسة الموضحة بتنسيق JSON. يتم عرضها على مدخل Microsoft Azure بتنسيق JSON. يمكن تعيين المعلمات نفسها عن طريق CLI Azure أو SDK.
نهج إلغاء الاشتراك لاستبعاد بعض مسارات الخصائص بشكل انتقائي
{
"indexingMode": "consistent",
"includedPaths": [
{
"path": "/*"
}
],
"excludedPaths": [
{
"path": "/path/to/single/excluded/property/?"
},
{
"path": "/path/to/root/of/multiple/excluded/properties/*"
}
]
}
نهج الاشتراك لتضمين بعض مسارات الخصائص بشكل انتقائي
{
"indexingMode": "consistent",
"includedPaths": [
{
"path": "/path/to/included/property/?"
},
{
"path": "/path/to/root/of/multiple/included/properties/*"
}
],
"excludedPaths": [
{
"path": "/*"
}
]
}
إشعار
نوصي عموما باستخدام نهج فهرسة إلغاء الاشتراك. يقوم Azure Cosmos DB بفهرسة أي خاصية جديدة قد تتم إضافتها إلى نموذج البيانات بشكل استباقي.
استخدام فهرس مكاني في مسار خاصية محددة فقط
{
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*"
}
],
"excludedPaths": [
{
"path": "/_etag/?"
}
],
"spatialIndexes": [
{
"path": "/path/to/geojson/property/?",
"types": [
"Point",
"Polygon",
"MultiPolygon",
"LineString"
]
}
]
}
أمثلة على نهج فهرسة المتجهات
بالإضافة إلى تضمين مسارات الخصائص الفردية أو استبعادها، يمكنك أيضا تحديد فهرس متجه. بشكل عام، يجب تحديد فهارس المتجهات كلما VectorDistance تم استخدام وظيفة النظام لقياس التشابه بين متجه استعلام وخاصية متجه.
إشعار
يجب عليك التسجيل في ميزة معاينة Azure Cosmos DB NoSQL Vector Index لاستخدام البحث عن المتجهات في Azure Cosmos DB ل NoSQL.>
هام
يجب أن يكون نهج فهرسة المتجهات على المسار المحدد في نهج متجه الحاوية. تعرف على المزيد حول نهج متجهات الحاوية.)
{
"indexingMode": "consistent",
"automatic": true,
"includedPaths": [
{
"path": "/*"
}
],
"excludedPaths": [
{
"path": "/_etag/?"
}
],
"vectorIndexes": [
{
"path": "/vector",
"type": "quantizedFlat"
}
]
}
يمكنك تحديد الأنواع التالية من نهج فهرس المتجهات:
| النوع | الوصف | الحد الأقصى للأبعاد |
|---|---|---|
flat |
يخزن المتجهات على نفس الفهرس مثل الخصائص المفهرسة الأخرى. | 505 |
quantizedFlat |
قياس (ضغط) المتجهات قبل التخزين على الفهرس. يمكن أن يؤدي ذلك إلى تحسين زمن الانتقال ومعدل النقل على حساب قدر صغير من الدقة. | 4096 |
diskANN |
إنشاء فهرس يستند إلى DiskANN للبحث التقريبي السريع والفعال. | 4096 |
flat تستفيد أنواع الفهرس و quantizedFlat من فهرس Azure Cosmos DB لتخزين كل متجه وقراءته عند إجراء بحث متجه. عمليات البحث المتجهة ذات الفهرس flat هي عمليات بحث غاشمة وتنتج دقة 100٪ . ومع ذلك، هناك قيود على 505 أبعاد المتجهات على فهرس ثابت.
يخزن quantizedFlat الفهرس المتجهات الكمية أو المضغوطة على الفهرس. عمليات البحث المتجهة ذات quantizedFlat الفهرس هي أيضا عمليات بحث بقوة غاشمة، ولكن قد تكون دقتها أقل قليلا من 100٪ نظرا لأن المتجهات يتم تحديدها كميا قبل الإضافة إلى الفهرس. ومع ذلك، يجب أن يكون لعمليات البحث الموجهة ذات quantized flat زمن انتقال أقل ومعدل نقل أعلى وتكلفة وحدة طلب أقل من عمليات البحث المتجهة flat على فهرس. هذا خيار جيد للسيناريوهات التي تستخدم فيها عوامل تصفية الاستعلام لتضييق نطاق البحث المتجه إلى مجموعة صغيرة نسبيا من المتجهات.
الفهرس diskANN هو فهرس منفصل محدد خصيصا للخطوط المتجهة التي تستفيد من DiskANN، وهي مجموعة من خوارزميات فهرسة المتجهات عالية الأداء التي طورتها Microsoft Research. يمكن أن توفر فهارس DiskANN بعض أقل زمن انتقال وأعلى استعلام في الثانية (QPS) وأقل استعلامات تكلفة RU بدقة عالية. ومع ذلك، نظرا لأن DiskANN هو أقرب فهرس جار تقريبي (ANN)، فقد تكون الدقة أقل من quantizedFlat أو flat.
أمثلة عن نهج الفهرسة المركبة
فضلاً عن تضمين مسارات خصائص فردية أو استبعادها، يمكنك أيضاً تحديد فهرس مُركب. لتنفيذ استعلام يحتوي على ORDER BY عبارة لخصائص متعددة، يلزم وجود فهرس مركب على تلك الخصائص. إذا كان الاستعلام يتضمن عوامل تصفية مع الفرز على خصائص متعددة، فقد تحتاج إلى أكثر من فهرس مركب واحد.
الفهارس المركبة لها أيضا ميزة أداء للاستعلامات التي تحتوي على عوامل تصفية متعددة أو كل من عامل تصفية وعبارة ORDER BY.
إشعار
تتضمن المسارات المركبة /? ضمنية بسبب عدم فهرسة سوى القيمة العددية في هذا المسار فقط. الحرف البدل /* غير معتمد في المسارات المركبة. لا يجب تحديد /? أو /* في مسار مركب. المسارات المركبة حساسة لحالة الأحرف أيضا.
فهرس مركب معرف ل (الاسم asc، العمر desc)
{
"automatic":true,
"indexingMode":"Consistent",
"includedPaths":[
{
"path":"/*"
}
],
"excludedPaths":[],
"compositeIndexes":[
[
{
"path":"/name",
"order":"ascending"
},
{
"path":"/age",
"order":"descending"
}
]
]
}
الفهرس المركب على الاسم والعمر مطلوب للاستعلامات التالية:
الاستعلام رقم 1:
SELECT *
FROM c
ORDER BY c.name ASC, c.age DESC
الاستعلام رقم 2:
SELECT *
FROM c
ORDER BY c.name DESC, c.age ASC
يستفيد هذا الفهرس المركب من الاستعلامات التالية ويحسن عوامل التصفية:
الاستعلام رقم 3:
SELECT *
FROM c
WHERE c.name = "Tim"
ORDER BY c.name DESC, c.age ASC
الاستعلام رقم 4:
SELECT *
FROM c
WHERE c.name = "Tim" AND c.age > 18
فهرس مركب معرف ل (الاسم ASC، العمر ASC) و (الاسم ASC، العمر DESC)
يمكنك تعريف فهارس مركبة متعددة ضمن نفس نهج الفهرسة.
{
"automatic":true,
"indexingMode":"Consistent",
"includedPaths":[
{
"path":"/*"
}
],
"excludedPaths":[],
"compositeIndexes":[
[
{
"path":"/name",
"order":"ascending"
},
{
"path":"/age",
"order":"ascending"
}
],
[
{
"path":"/name",
"order":"ascending"
},
{
"path":"/age",
"order":"descending"
}
]
]
}
فهرس مركب معرف ل (الاسم ASC، العمر ASC)
من الاختياري تحديد الطلب. في حالة عدم تحديد الترتيب، يكون تصاعديًا.
{
"automatic":true,
"indexingMode":"Consistent",
"includedPaths":[
{
"path":"/*"
}
],
"excludedPaths":[],
"compositeIndexes":[
[
{
"path":"/name"
},
{
"path":"/age"
}
]
]
}
استبعاد كافة مسارات الخصائص مع الحفاظ على تنشيط الفهرسة
يمكنك استخدام هذا النهج حيث تكون ميزة مدة البقاء (TTL) نشطة ولكن لا توجد فهارس أخرى ضرورية لاستخدام Azure Cosmos DB كمخزن قيمة مفتاح خالص.
{
"indexingMode": "consistent",
"includedPaths": [],
"excludedPaths": [{
"path": "/*"
}]
}
لا توجد فهرسة
يقوم هذا النهج بإيقاف تشغيل الفهرسة. إذا indexingMode تم تعيين إلى none، فلا يمكنك تعيين TTL على الحاوية.
{
"indexingMode": "none"
}
تحديث نهج الفهرسة
في Azure Cosmos DB، يمكن تحديث نهج الفهرسة باستخدام أي من الطرق التالية:
- من مدخل Azure
- استخدام Azure CLI
- استخدام PowerShell
- استخدام إحدى حزم SDK
يؤدي تحديث نهج الفهرسة إلى بدء تحويل الفهرس. ويمكن أيضا تتبع تقدم هذا التحول من أدوات SDK.
إشعار
عند تحديث نهج الفهرسة، تتم الكتابة إلى Azure Cosmos DB دون انقطاع. معرفة المزيد عن تحويلات الفهرسة
هام
تسري إزالة فهرس على الفور، في حين أن إضافة فهرس جديد يستغرق بعض الوقت لأنه يتطلب تحويل فهرسة. عند استبدال فهرس بفهرس آخر (على سبيل المثال، استبدال فهرس خاصية واحد بفهرس مركب) تأكد من إضافة الفهرس الجديد أولا ثم انتظر حتى يكتمل تحويل الفهرس قبل إزالة الفهرس السابق من نهج الفهرسة. وإلا فإن هذا سيؤثر سلبا على قدرتك على الاستعلام عن الفهرس السابق وقد يكسر أي أحمال عمل نشطة تشير إلى الفهرس السابق.
استخدام مدخل Microsoft Azure
تخزن حاويات Azure Cosmos DB نهج الفهرسة كمستند JSON يتيح لك مدخل Azure تحريره مباشرة.
قم بتسجيل الدخول إلى بوابة Azure.
إنشاء حساب Azure Cosmos DB جديد أو تحديد حساب موجود.
افتح جزء مستكشف البيانات وحدد الحاوية التي تريد العمل عليها.
حدد Scale & Settings.
تعديل مستند JSON لنهج الفهرسة، كما هو موضح في هذه الأمثلة.
حدد حفظ عند الانتهاء.
استخدام Azure CLI
لإنشاء حاوية باستخدام نهج فهرسة مخصص، راجع إنشاء حاوية باستخدام نهج فهرس مخصص باستخدام CLI.
استخدام PowerShell
لإنشاء حاوية باستخدام نهج فهرسة مخصص، راجع إنشاء حاوية باستخدام نهج فهرس مخصص باستخدام PowerShell.
استخدم .NET عدة تطوير البرامج
ContainerProperties يعرض IndexingPolicy الكائن من .NET SDK v3 خاصية تتيح لك تغيير وإضافة IndexingMode أو إزالة IncludedPaths وExcludedPaths. لمزيد من المعلومات، راجع التشغيل السريع: مكتبة عميل Azure Cosmos DB for NoSQL ل .NET.
// Retrieve the container's details
ContainerResponse containerResponse = await client.GetContainer("database", "container").ReadContainerAsync();
// Set the indexing mode to consistent
containerResponse.Resource.IndexingPolicy.IndexingMode = IndexingMode.Consistent;
// Add an included path
containerResponse.Resource.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
// Add an excluded path
containerResponse.Resource.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/name/*" });
// Add a spatial index
SpatialPath spatialPath = new SpatialPath
{
Path = "/locations/*"
};
spatialPath.SpatialTypes.Add(SpatialType.Point);
containerResponse.Resource.IndexingPolicy.SpatialIndexes.Add(spatialPath);
// Add a composite index
containerResponse.Resource.IndexingPolicy.CompositeIndexes.Add(new Collection<CompositePath> { new CompositePath() { Path = "/name", Order = CompositePathSortOrder.Ascending }, new CompositePath() { Path = "/age", Order = CompositePathSortOrder.Descending } });
// Update container with changes
await client.GetContainer("database", "container").ReplaceContainerAsync(containerResponse.Resource);
لتعقب تقدم تحويل الفهرس، مرر كائن RequestOptions الذي يعيِّن الخاصية PopulateQuotaInfo على true . استرداد القيمة من عنوان الاستجابة x-ms-documentdb-collection-index-transformation-progress .
// retrieve the container's details
ContainerResponse containerResponse = await client.GetContainer("database", "container").ReadContainerAsync(new ContainerRequestOptions { PopulateQuotaInfo = true });
// retrieve the index transformation progress from the result
long indexTransformationProgress = long.Parse(containerResponse.Headers["x-ms-documentdb-collection-index-transformation-progress"]);
تتيح لك واجهة برمجة تطبيقات SDK V3 بطلاقة كتابة هذا التعريف بطريقة موجزة وفعالة عند تحديد نهج فهرسة مخصص أثناء إنشاء حاوية جديدة:
await client.GetDatabase("database").DefineContainer(name: "container", partitionKeyPath: "/myPartitionKey")
.WithIndexingPolicy()
.WithIncludedPaths()
.Path("/*")
.Attach()
.WithExcludedPaths()
.Path("/name/*")
.Attach()
.WithSpatialIndex()
.Path("/locations/*", SpatialType.Point)
.Attach()
.WithCompositeIndex()
.Path("/name", CompositePathSortOrder.Ascending)
.Path("/age", CompositePathSortOrder.Descending)
.Attach()
.Attach()
.CreateIfNotExistsAsync();
استخدم Java SDK
DocumentCollection يعرض الكائن من Java SDK الأسلوبين getIndexingPolicy() وsetIndexingPolicy(). يسمح لك الكائن IndexingPolicy الذي يعالجونه تغيير وضع الفهرسة وإضافة مسارات مضمنة ومستبعدة أو إزالتها. لمزيد من المعلومات، راجع التشغيل السريع: إنشاء تطبيق Java لإدارة Azure Cosmos DB لبيانات NoSQL.
// Retrieve the container's details
Observable<ResourceResponse<DocumentCollection>> containerResponse = client.readCollection(String.format("/dbs/%s/colls/%s", "database", "container"), null);
containerResponse.subscribe(result -> {
DocumentCollection container = result.getResource();
IndexingPolicy indexingPolicy = container.getIndexingPolicy();
// Set the indexing mode to consistent
indexingPolicy.setIndexingMode(IndexingMode.Consistent);
// Add an included path
Collection<IncludedPath> includedPaths = new ArrayList<>();
IncludedPath includedPath = new IncludedPath();
includedPath.setPath("/*");
includedPaths.add(includedPath);
indexingPolicy.setIncludedPaths(includedPaths);
// Add an excluded path
Collection<ExcludedPath> excludedPaths = new ArrayList<>();
ExcludedPath excludedPath = new ExcludedPath();
excludedPath.setPath("/name/*");
excludedPaths.add(excludedPath);
indexingPolicy.setExcludedPaths(excludedPaths);
// Add a spatial index
Collection<SpatialSpec> spatialIndexes = new ArrayList<SpatialSpec>();
Collection<SpatialType> collectionOfSpatialTypes = new ArrayList<SpatialType>();
SpatialSpec spec = new SpatialSpec();
spec.setPath("/locations/*");
collectionOfSpatialTypes.add(SpatialType.Point);
spec.setSpatialTypes(collectionOfSpatialTypes);
spatialIndexes.add(spec);
indexingPolicy.setSpatialIndexes(spatialIndexes);
// Add a composite index
Collection<ArrayList<CompositePath>> compositeIndexes = new ArrayList<>();
ArrayList<CompositePath> compositePaths = new ArrayList<>();
CompositePath nameCompositePath = new CompositePath();
nameCompositePath.setPath("/name");
nameCompositePath.setOrder(CompositePathSortOrder.Ascending);
CompositePath ageCompositePath = new CompositePath();
ageCompositePath.setPath("/age");
ageCompositePath.setOrder(CompositePathSortOrder.Descending);
compositePaths.add(ageCompositePath);
compositePaths.add(nameCompositePath);
compositeIndexes.add(compositePaths);
indexingPolicy.setCompositeIndexes(compositeIndexes);
// Update the container with changes
client.replaceCollection(container, null);
});
لتعقب تقدم تحويل الفهرس على حاوية، مرر كائنا RequestOptions يطلب تعبئة معلومات الحصة النسبية. استرداد القيمة من عنوان الاستجابة x-ms-documentdb-collection-index-transformation-progress .
// set the RequestOptions object
RequestOptions requestOptions = new RequestOptions();
requestOptions.setPopulateQuotaInfo(true);
// retrieve the container's details
Observable<ResourceResponse<DocumentCollection>> containerResponse = client.readCollection(String.format("/dbs/%s/colls/%s", "database", "container"), requestOptions);
containerResponse.subscribe(result -> {
// retrieve the index transformation progress from the response headers
String indexTransformationProgress = result.getResponseHeaders().get("x-ms-documentdb-collection-index-transformation-progress");
});
استخدام عقدة.js عدة تطوير البرامج
تعرض الواجهة ContainerDefinition من Node.js SDK خاصية تتيح لك تغيير وإضافة indexingMode أو إزالة includedPaths وexcludedPaths.indexingPolicy لمزيد من المعلومات، راجع التشغيل السريع - مكتبة عميل Azure Cosmos DB ل NoSQL Node.js.
استرداد تفاصيل الحاوية:
const containerResponse = await client.database('database').container('container').read();
تعيين وضع الفهرسة إلى متناسق:
containerResponse.body.indexingPolicy.indexingMode = "consistent";
إضافة مسار مضمن بما في ذلك فهرس مكاني:
containerResponse.body.indexingPolicy.includedPaths.push({
includedPaths: [
{
path: "/age/*",
indexes: [
{
kind: cosmos.DocumentBase.IndexKind.Range,
dataType: cosmos.DocumentBase.DataType.String
},
{
kind: cosmos.DocumentBase.IndexKind.Range,
dataType: cosmos.DocumentBase.DataType.Number
}
]
},
{
path: "/locations/*",
indexes: [
{
kind: cosmos.DocumentBase.IndexKind.Spatial,
dataType: cosmos.DocumentBase.DataType.Point
}
]
}
]
});
إضافة مسار مستبعد:
containerResponse.body.indexingPolicy.excludedPaths.push({ path: '/name/*' });
تحديث الحاوية بالتغييرات:
const replaceResponse = await client.database('database').container('container').replace(containerResponse.body);
لتعقب تقدم تحويل الفهرس على حاوية، قم بتمرير كائن RequestOptions يقوم بتعيين الخاصية populateQuotaInfo إلى true. استرداد القيمة من عنوان الاستجابة x-ms-documentdb-collection-index-transformation-progress .
// retrieve the container's details
const containerResponse = await client.database('database').container('container').read({
populateQuotaInfo: true
});
// retrieve the index transformation progress from the response headers
const indexTransformationProgress = replaceResponse.headers['x-ms-documentdb-collection-index-transformation-progress'];
استخدام Python عدة تطوير البرامج
عند استخدام Python SDK V3، تتم إدارة تكوين الحاوية كقاموس. من هذا القاموس، يمكنك الوصول إلى نهج الفهرسة وجميع سماته. لمزيد من المعلومات، راجع التشغيل السريع: مكتبة عميل Azure Cosmos DB ل NoSQL ل Python.
استرداد تفاصيل الحاوية:
containerPath = 'dbs/database/colls/collection'
container = client.ReadContainer(containerPath)
تعيين وضع الفهرسة إلى متناسق:
container['indexingPolicy']['indexingMode'] = 'consistent'
حدد نهج فهرسة بمسار مضمن وفهرس مكاني:
container["indexingPolicy"] = {
"indexingMode":"consistent",
"spatialIndexes":[
{"path":"/location/*","types":["Point"]}
],
"includedPaths":[{"path":"/age/*","indexes":[]}],
"excludedPaths":[{"path":"/*"}]
}
تعريف نهج فهرسة بمسار مستبعد:
container["indexingPolicy"] = {
"indexingMode":"consistent",
"includedPaths":[{"path":"/*","indexes":[]}],
"excludedPaths":[{"path":"/name/*"}]
}
إضافة فهرس مركب:
container['indexingPolicy']['compositeIndexes'] = [
[
{
"path": "/name",
"order": "ascending"
},
{
"path": "/age",
"order": "descending"
}
]
]
تحديث الحاوية بالتغييرات:
response = client.ReplaceContainer(containerPath, container)
الخطوات التالية
قراءة المزيد عن الفهرسة في المقالات التالية:
الملاحظات
قريبًا: خلال عام 2024، سنتخلص تدريجيًا من GitHub Issues بوصفها آلية إرسال ملاحظات للمحتوى ونستبدلها بنظام ملاحظات جديد. لمزيد من المعلومات، راجع https://aka.ms/ContentUserFeedback.
إرسال الملاحظات وعرضها المتعلقة بـ