Azure Cosmos DB لوظائف PostgreSQL

مقالة
10/27/2023

ينطبق على: Azure Cosmos DB ل PostgreSQL (مدعوم بملحق قاعدة بيانات Citus إلى PostgreSQL)

يحتوي هذا القسم على معلومات مرجعية للوظائف المعرفة من قبل المستخدم التي يوفرها Azure Cosmos DB ل PostgreSQL. تساعد هذه الوظائف في توفير وظائف موزعة إلى Azure Cosmos DB ل PostgreSQL.

إشعار

قد لا تقدم المجموعات التي تعمل بالإصدارات القديمة من Citus Engine جميع الوظائف المدرجة في هذه الصفحة.

Table وShard DDL

citus_schema_distribute

تحويل المخططات العادية الموجودة إلى مخططات موزعة. يتم اقتران المخططات الموزعة تلقائيا بمجموعات تجميع فردية. يتم تحويل الجداول التي تم إنشاؤها في هذه المخططات إلى جداول موزعة مهيأة بدون مفتاح جزء. تقوم عملية توزيع المخطط تلقائيا بتعيينه ونقله إلى عقدة موجودة في نظام المجموعة.

الوسيطات

schemaname: اسم المخطط، الذي يحتاج إلى توزيع.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

SELECT citus_schema_distribute('tenant_a');
SELECT citus_schema_distribute('tenant_b');
SELECT citus_schema_distribute('tenant_c');

لمزيد من الأمثلة، راجع كيفية التصميم للخدمات المصغرة.

citus_schema_undistribute

تحويل مخطط موزع موجود مرة أخرى إلى مخطط عادي. تؤدي العملية إلى نقل الجداول والبيانات من العقدة الحالية مرة أخرى إلى عقدة المنسق في نظام المجموعة.

الوسيطات

schemaname: اسم المخطط، الذي يحتاج إلى توزيع.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

SELECT citus_schema_undistribute('tenant_a');
SELECT citus_schema_undistribute('tenant_b');
SELECT citus_schema_undistribute('tenant_c');

لمزيد من الأمثلة، راجع كيفية التصميم للخدمات المصغرة.

create_distributed_table

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

تحل هذه الدالة محل استخدام master_create_distributed_table() متبوعة master_create_worker_shards().

الوسيطات

table_name: اسم الجدول الذي يجب توزيعه.

distribution_column: العمود الذي سيتم توزيع الجدول عليه.

distribution_type: (اختياري) الأسلوب الذي سيتم توزيع الجدول وفقًا له. القيم المسموح بها هي إلحاق أو تجزئة، بقيمة افتراضية هي "التجزئة".

colocate_with: (اختياري) تضمين الجدول الحالي في مجموعة الموقع المشترك لجدول آخر. بشكل افتراضي، يتم تخصيص الجداول عندما يتم توزيعها بواسطة أعمدة من نفس النوع، وتكون لها نفس عدد الأجزاء، وتكون لها نفس عامل النسخ المتماثل. القيم المحتملة لـ colocate_with هي default، none لبدء مجموعة توصيل جديدة، أو اسم جدول آخر للتكوين مع هذا الجدول. (راجع موقع الجدول.)

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

إذا لم يكن الجدول الموزع الجديد مرتبطاً بجداول أخرى، فمن الأفضل تحديد colocate_with => 'none'.

shard_count: (اختياري) عدد الأجزاء المراد إنشاؤها للجدول الموزع الجديد. عند تحديد shard_count لا يمكنك تحديد قيمة colocate_with أخرى غير لا شيء. لتغيير عدد الأجزاء لجدول موجود أو مجموعة تجميع، استخدم الدالة alter_distributed_table .

تتراوح القيم المحتملة ل shard_count بين 1 و64000. للحصول على إرشادات حول اختيار القيمة المثلى، راجع عدد الأجزاء.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

يعلم هذا المثال قاعدة البيانات بأنه يجب توزيع جدول github_events بواسطة التجزئة في العمود repo_id.

SELECT create_distributed_table('github_events', 'repo_id');

-- alternatively, to be more explicit:
SELECT create_distributed_table('github_events', 'repo_id',
                                colocate_with => 'github_repo');

create_distributed_table_concurrently

هذه الدالة لها نفس الواجهة والغرض مثل create_distributed_function، ولكنها لا تحظر عمليات الكتابة أثناء توزيع الجدول.

ومع ذلك، create_distributed_table_concurrently هناك بعض القيود:

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

truncate_local_data_after_distributing_table

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

ERROR:  cannot truncate a table referenced in a foreign key constraint by a local table

يعد اقتطاع بيانات جدول عقدة المنسق المحلي آمناً للجداول الموزعة لأن صفوفها، إن وجدت، يتم نسخها إلى العقد العاملة خلال التوزيع.

الوسيطات

table_name: اسم الجدول الموزع الذي يجب اقتطاع نظيره المحلي على عقدة المنسق.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');

create_reference_table

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

الوسيطات

table_name: اسم البعد الصغير أو الجدول المرجعي الذي يجب توزيعه.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

يعلم هذا المثال قاعدة البيانات بأنه يجب تعريف جدول الأمة كجدول مرجعي

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

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

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

عند إلغاء تقسيم الجدول، يزيل Citus الجداول المحلية الناتجة من بيانات التعريف، ما يلغي هذه القيود على تلك الجداول.

الوسيطات

table_name: اسم الجدول على المنسق لإضافته إلى بيانات تعريف Citus.

cascade_via_foreign_keys: (اختياري) عند تعيين هذه الوسيطة إلى "صحيح"، يضيف citus_add_local_table_to_metadata جداول أخرى موجودة في علاقة مفتاح خارجي مع جدول معين إلى بيانات التعريف تلقائيا. استخدم الحذر مع هذه المعلمة، لأنها قد تؤثر على العديد من الجداول.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

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

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

يمكن استخدام الدالة alter_distributed_table() لتغيير عمود التوزيع أو عدد الأجزاء أو خصائص الموقع المشترك لجدول موزع.

الوسيطات

table_name: اسم الجدول الذي سيتم تغييره.

distribution_column: (اختياري) اسم عمود التوزيع الجديد.

shard_count: (اختياري) عدد الأجزاء الجديدة.

colocate_with: (اختياري) الجدول الذي سيتم تخصيص الجدول الموزع الحالي معه. القيم المحتملة هي default، none لبدء مجموعة colocation جديدة، أو اسم جدول آخر لتكوينه. (راجع موقع الجدول.)

cascade_to_colocated: (اختياري) عند تعيين هذه الوسيطة إلى "صحيح"، سيتم أيضاً تطبيق التغييرات shard_count وcolocate_with على كل الجداول التي تم تخصيصها مسبقاً مع الجدول، وسيتم الاحتفاظ بالتكوين المشترك. إذا كان "خطأ"، فسيتم قطع الموقع المشترك الحالي لهذا الجدول.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

-- change distribution column
SELECT alter_distributed_table('github_events', distribution_column:='event_id');

-- change shard count of all tables in colocation group
SELECT alter_distributed_table('github_events', shard_count:=6, cascade_to_colocated:=true);

-- change colocation
SELECT alter_distributed_table('github_events', colocate_with:='another_table');

update_distributed_table_colocation

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

لا تنقل هذه الدالة أي بيانات فعلياً.

الوسيطات

table_name: اسم موقع الجدول الذي سيتم تحديثه.

colocate_with: الجدول الذي يجب أن يتم تخصيص الجدول معه.

إذا كنت تريد قطع الموقع المشترك لجدول، يجب تحديد colocate_with => 'none'.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

يوضح هذا المثال أنه يتم تحديث colocation للجدول A كموضع مشترك للجدول B.

SELECT update_distributed_table_colocation('A', colocate_with => 'B');

افترض أن الجدول A والجدول B قد تم تخصيصهما (ربما ضمنياً)، إذا كنت تريد قطع التكوين:

SELECT update_distributed_table_colocation('A', colocate_with => 'none');

الآن، افترض أن الجدول A والجدول B والجدول C والجدول D متقاربان وتريد تجميع الجدول A والجدول B معا، والجدول C والجدول D معاً:

SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');

إذا كان لديك جدول تجزئة موزع باسم none وتريد تحديث colocation الخاص به، يمكنك القيام بما يلي:

SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');

undistribute_table

تتراجع الدالة undistribute_table() عن إجراء create_distributed_table أو create_reference_table. يؤدي إلغاء التقسيم إلى نقل جميع البيانات من الأجزاء مرة أخرى إلى جدول محلي على عقدة المنسق (على افتراض أن البيانات يمكن احتوائها)، ثم يحذف الأجزاء.

لن يقوم Azure Cosmos DB ل PostgreSQL بإلغاء تحديد الجداول التي تحتوي على - أو يشار إليها بواسطة - مفاتيح خارجية، ما لم يتم تعيين الوسيطة cascade_via_foreign_keys إلى true. إذا كانت هذه الوسيطة خاطئة (أو تم حذفها)، يجب عليك إسقاط قيود المفتاح الخارجي المخالفة يدوياً قبل إلغاء الفرز.

الوسيطات

table_name: اسم الجدول الموزع أو المرجعي إلى إلغاء الفرز.

cascade_via_foreign_keys: (اختياري) عند تعيين هذه الوسيطة إلى "صحيح"، undistribute_table أيضاً إلغاء تعيين جميع الجداول المرتبطة table_name من خلال المفاتيح الخارجية. استخدم الحذر مع هذه المعلمة، لأنها قد تؤثر على العديد من الجداول.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

يوزع هذا المثال جدولاً github_events ثم يقوم بإلغاء توزيعه.

-- first distribute the table
SELECT create_distributed_table('github_events', 'repo_id');

-- undo that and make it local again
SELECT undistribute_table('github_events');

create_distributed_function

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

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

الوسيطات

function_name: اسم الدالة التي سيتم توزيعها. يجب أن يتضمن الاسم أنواع معلمات الدالة بين أقواس، لأنه يمكن أن يكون للدالات المتعددة نفس الاسم في PostgreSQL. على سبيل المثال، 'foo(int)' يختلف عن 'foo(int, text)'.

distribution_arg_name: (اختياري) اسم الوسيطة الذي سيتم التوزيع من خلاله. للراحة (أو إذا لم يكن لدى وسيطات الدالة أسماء)، يسمح بعنصر نائب موضعي، مثل '$1'. إذا لم يتم تحديد هذه المعلمة، يتم إنشاء الدالة المسماة بواسطة function_name فقط على العمال. إذا تمت إضافة العقد العاملة في المستقبل، فسيتم إنشاء الدالة تلقائيًا هناك أيضًا.

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

قيمة الإرجاع

‏‫غير متوفر‬

مثال

-- an example function which updates a hypothetical
-- event_responses table which itself is distributed by event_id
CREATE OR REPLACE FUNCTION
  register_for_event(p_event_id int, p_user_id int)
RETURNS void LANGUAGE plpgsql AS $fn$
BEGIN
  INSERT INTO event_responses VALUES ($1, $2, 'yes')
  ON CONFLICT (event_id, user_id)
  DO UPDATE SET response = EXCLUDED.response;
END;
$fn$;

-- distribute the function to workers, using the p_event_id argument
-- to determine which shard each invocation affects, and explicitly
-- colocating with event_responses which the function updates
SELECT create_distributed_function(
  'register_for_event(int, int)', 'p_event_id',
  colocate_with := 'event_responses'
);

alter_columnar_table_set

تقوم الدالة alter_columnar_table_set() بتغيير الإعدادات على جدول عمودي. يؤدي استدعاء هذه الدالة على جدول غير عمودي إلى حدوث خطأ. جميع الوسيطات باستثناء اسم الجدول اختيارية.

لعرض الخيارات الحالية لكافة الجداول العمودية، راجع هذا الجدول:

SELECT * FROM columnar.options;

يمكن تجاوز القيم الافتراضية للإعدادات العمودية للجداول التي تم إنشاؤها حديثًا باستخدام GUCs هذه:

columnar.compression
columnar.compression_level
columnar.stripe_row_count
columnar.chunk_row_count

الوسيطات

table_name: اسم الجدول العمودي.

chunk_row_count: (اختياري) الحد الأقصى لعدد الصفوف لكل مجموعة للبيانات المدرجة حديثاً. لن يتم تغيير مجموعات البيانات الموجودة وقد تحتوي على صفوف أكثر من هذه القيمة القصوى. القيمة الافتراضية هي 10000.

stripe_row_count: (اختياري) الحد الأقصى لعدد الصفوف لكل شريط للبيانات المدرجة حديثاً. لن يتم تغيير خطوط البيانات الموجودة وقد يكون لها صفوف أكثر من هذه القيمة القصوى. القيمة الافتراضية هي 150000.

الضغط: (اختياري) [none|pglz|zstd|lz4|lz4hc] نوع الضغط للبيانات المدرجة حديثاً. لن تتم إعادة ضغط البيانات الموجودة أو إلغاء ضغطها. القيمة الافتراضية والمقترحة هي zstd (إذا تم تحويل الدعم برمجياً).

compression_level: (اختياري) تتراوح الإعدادات الصالحة من 1 إلى 19. إذا لم يدعم أسلوب الضغط المستوى المختار، فسيتم تحديد أقرب مستوى بدلاً من ذلك.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

SELECT alter_columnar_table_set(
  'my_columnar_table',
  compression => 'none',
  stripe_row_count => 10000);

alter_table_set_access_method

تقوم الدالة alter_table_set_access_method() بتغيير طريقة الوصول لجدول (على سبيل المثال، كومة الذاكرة المؤقتة أو عمودي).

الوسيطات

table_name: اسم الجدول الذي سيتغير أسلوب الوصول إليه.

access_method: اسم أسلوب الوصول الجديد.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

SELECT alter_table_set_access_method('github_events', 'columnar');

create_time_partitions

تنشئ الدالة create_time_partitions() أقساما لفاصل زمني معين لتغطية نطاق معين من الوقت.

الوسيطات

table_name: (regclass) الجدول الذي سيتم إنشاء أقسام جديدة له. يجب تقسيم الجدول على عمود واحد، من نوع التاريخ أو الطابع الزمني أو الطابع الزمني.

partition_interval: فاصل زمني، مثل '2 hours'، أو '1 month'، لاستخدامه عند تعيين النطاقات على أقسام جديدة.

end_at: (الطابع الزمني) إنشاء أقسام حتى هذا الوقت. سيحتوي القسم الأخير على نقطة end_at، ولن يتم إنشاء أقسام لاحقة.

start_from: (timestamptz، اختياري) اختر القسم الأول بحيث يحتوي على النقطة start_from. القيمة الافتراضية هي now().

قيمة الإرجاع

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

مثال

-- create a year's worth of monthly partitions
-- in table foo, starting from the current time

SELECT create_time_partitions(
  table_name         := 'foo',
  partition_interval := '1 month',
  end_at             := now() + '12 months'
);

drop_old_time_partitions

تزيل الدالة drop_old_time_partitions() جميع الأقسام التي تقع فواصلها الزمنية قبل طابع زمني معين. بالإضافة إلى استخدام هذه الدالة، قد تفكر في alter_old_partitions_set_access_method لضغط الأقسام القديمة مع التخزين العمودي.

الوسيطات

table_name: جدول (regclass) لإزالة الأقسام له. يجب تقسيم الجدول على عمود واحد، من نوع التاريخ أو الطابع الزمني أو الطابع الزمني.

older_than: (timestamptz) إسقاط الأقسام التي يكون نطاقها الأعلى أقل من أو يساوي older_than.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

-- drop partitions that are over a year old

CALL drop_old_time_partitions('foo', now() - interval '12 months');

alter_old_partitions_set_access_method

في حالة استخدام المؤقتات، غالبا ما يتم تقسيم الجداول حسب الوقت، ويتم ضغط الأقسام القديمة في تخزين عمودي للقراءة فقط.

الوسيطات

parent_table_name: جدول (regclass) لتغيير الأقسام له. يجب تقسيم الجدول على عمود واحد، من نوع التاريخ أو الطابع الزمني أو الطابع الزمني.

older_than: (timestamptz) تغيير الأقسام التي يكون نطاقها الأعلى أقل من أو يساوي older_than.

new_access_method: (الاسم) إما "كومة" للتخزين المستند إلى الصف، أو "عمودي" للتخزين العمودي.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

CALL alter_old_partitions_set_access_method(
  'foo', now() - interval '6 months',
  'columnar'
);

بيانات التعريف / معلومات التكوين

get_shard_id_for_distribution_column

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

الوسيطات

table_name: الجدول الموزع.

distribution_value: قيمة عمود التوزيع.

قيمة الإرجاع

يرتبط معرف الجزء Azure Cosmos DB ل PostgreSQL بقيمة عمود التوزيع للجدول المحدد.

مثال

SELECT get_shard_id_for_distribution_column('my_table', 4);

 get_shard_id_for_distribution_column
--------------------------------------
                               540007
(1 row)

column_to_column_name

يترجم partkey عمود pg_dist_partition لاسم عمود نصي. الترجمة مفيدة لتحديد عمود التوزيع لجدول موزع.

للحصول على مناقشة أكثر تفصيلاً، راجع اختيار عمود توزيع.

الوسيطات

table_name: الجدول الموزع.

column_var_text: قيمة partkey في pg_dist_partition الجدول.

قيمة الإرجاع

اسم عمود توزيع table_name.

مثال

-- get distribution column name for products table

SELECT column_to_column_name(logicalrelid, partkey) AS dist_col_name
  FROM pg_dist_partition
 WHERE logicalrelid='products'::regclass;

إخراج:

┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id    │
└───────────────┘

citus_relation_size

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

الوسيطات

logicalrelid: اسم جدول موزع.

قيمة الإرجاع

الحجم بالبايت كعدد صحيح كبير.

مثال

SELECT pg_size_pretty(citus_relation_size('github_events'));

pg_size_pretty
--------------
23 MB

citus_table_size

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

الوسيطات

logicalrelid: اسم جدول موزع.

قيمة الإرجاع

الحجم بالبايت كعدد صحيح كبير.

مثال

SELECT pg_size_pretty(citus_table_size('github_events'));

pg_size_pretty
--------------
37 MB

citus_total_relation_size

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

الوسيطات

logicalrelid: اسم جدول موزع.

قيمة الإرجاع

الحجم بالبايت كعدد صحيح كبير.

مثال

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

pg_size_pretty
--------------
73 MB

citus_stat_statements_reset

إزالة كافة الصفوف من citus_stat_statements. تعمل هذه الدالة بشكل مستقل عن pg_stat_statements_reset(). لإعادة تعيين جميع الإحصائيات، قم باستدعاء كلتا الدالتين.

الوسيطات

‏‫غير متوفر‬

قيمة الإرجاع

بلا

citus_get_active_worker_nodes

ترجع الدالة citus_get_active_worker_nodes() قائمة بأسماء مضيفي العاملين النشطين وأرقام المنافذ.

الوسيطات

‏‫غير متوفر‬

قيمة الإرجاع

قائمة المجموعات حيث تحتوي كل مجموعة على المعلومات التالية:

node_name: اسم DNS لعقدة العامل

node_port: المنفذ على العقدة العاملة التي يستمع إليها خادم قاعدة البيانات

مثال

SELECT * from citus_get_active_worker_nodes();
 node_name | node_port
-----------+-----------
 localhost |      9700
 localhost |      9702
 localhost |      9701

(3 rows)

إدارة نظام المجموعة وإصلاحها

master_copy_shard_placement

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

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

الوسيطات

shard_id: معرف الجزء المراد إصلاحه.

source_node_name: اسم DNS للعقدة التي يوجد عليها موضع القطع الصحي (عقدة "المصدر").

source_node_port: المنفذ الموجود على عقدة العامل المصدر الذي يستمع إليه خادم قاعدة البيانات.

target_node_name: اسم DNS للعقدة التي يوجد عليها موضع الجزء غير الصالح (عقدة "الهدف").

target_node_port: المنفذ الموجود على عقدة العامل الهدف الذي يستمع إليه خادم قاعدة البيانات.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

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

SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);

master_move_shard_placement

تنقل هذه الدالة قطعة معينة (والأجزاء المقسمة معها) من عقدة إلى أخرى. عادة ما يتم استخدامه بشكل غير مباشر خلال إعادة التوازن للجزء بدلاً من استدعاؤه مباشرة من قبل مسؤول قاعدة البيانات.

هناك طريقتان لنقل البيانات: الحظر أو عدم الحظر. يعني نهج الحظر أنه أثناء النقل يتم إيقاف جميع التعديلات على الجزء مؤقتًا. تعتمد الطريقة الثانية، التي تتجنب حظر عمليات كتابة الجزء، على النسخ المتماثل المنطقي Postgres 10.

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

الوسيطات

shard_id: معرف الجزء المطلوب نقله.

source_node_name: اسم DNS للعقدة التي يوجد عليها موضع القطع الصحي (عقدة "المصدر").

source_node_port: المنفذ الموجود على عقدة العامل المصدر الذي يستمع إليه خادم قاعدة البيانات.

target_node_name: اسم DNS للعقدة التي يوجد عليها موضع الجزء غير الصالح (عقدة "الهدف").

target_node_port: المنفذ الموجود على عقدة العامل الهدف الذي يستمع إليه خادم قاعدة البيانات.

shard_transfer_mode: (اختياري) حدد أسلوب النسخ المتماثل، سواء لاستخدام النسخ المتماثل المنطقي PostgreSQL أو أمر COPY عبر العاملين. تشمل القيم المحتملة ما يلي:

auto: يتطلب هوية النسخ المتماثل إذا كان النسخ المتماثل المنطقي ممكنا، وإلا استخدم السلوك القديم (على سبيل المثال لإصلاح الجزء، PostgreSQL 9.6). وتكون هذه هي القيمة الافتراضية.

force_logical: استخدم النسخ المتماثل المنطقي حتى إذا لم يكن للجدول هوية نسخة متماثلة. ستفشل أي عبارات تحديث/حذف متزامنة إلى الجدول أثناء النسخ المتماثل.

block_writes: استخدم COPY (حظر عمليات الكتابة) للجداول التي تفتقر إلى المفتاح الأساسي أو هوية النسخة المتماثلة.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);

rebalance_table_shards

تعمل الدالة rebalance_table_shards() على نقل أجزاء الجدول المحدد لتوزيعها بالتساوي بين العمال. تحسب الدالة أولا قائمة التحركات التي تحتاج إلى القيام بها للتأكد من موازنة نظام المجموعة ضمن الحد المحدد. ثم ينقل مواضع الأجزاء واحدا تلو الآخر من العقدة المصدر إلى العقدة الوجهة ويحدث بيانات تعريف الجزء المقابلة لتعكس النقل.

يتم تعيين تكلفة لكل جزء عند تحديد ما إذا كانت الأجزاء "موزعة بالتساوي". بشكل افتراضي، يكون لكل جزء نفس التكلفة (قيمة 1)، لذلك فإن التوزيع لتحقيق المساواة بين التكلفة عبر العمال هو نفس معادلة عدد الأجزاء على كل منها. تسمى استراتيجية التكلفة الثابتة "by_shard_count" وهي استراتيجية إعادة التوازن الافتراضية.

استراتيجية "by_shard_count" مناسبة في ظل هذه الظروف:

القطع تقريبًا بنفس الحجم
تحصل القطع على نفس كمية نسبة استخدام الشبكة تقريبًا
العقد العاملة كلها بنفس الحجم/النوع
لم يتم تثبيت القطع لعمال معينين

إذا لم يتم الاحتفاظ بأي من هذه الافتراضات، فقد تؤدي إعادة التوازن "by_shard_count" إلى خطة سيئة.

استراتيجية إعادة التوازن الافتراضية هي "by_disk_size". يمكنك دائما تخصيص الاستراتيجية، باستخدام المعلمة rebalance_strategy .

من المستحسن استدعاء get_rebalance_table_shards_plan قبل تشغيل rebalance_table_shards، لمشاهدة الإجراءات التي سيتم تنفيذها والتحقق منها.

الوسيطات

table_name: (اختياري) اسم الجدول الذي يجب إعادة توازن أجزاءه. إذا كانت NULL، فأعادت توازن جميع مجموعات التوصيل الموجودة.

الحد: (اختياري) رقم عائم بين 0.0 و1.0 يشير إلى الحد الأقصى لنسبة الفرق لاستخدام العقدة من متوسط الاستخدام. على سبيل المثال، سيؤدي تحديد 0.1 إلى محاولة إعادة توازن الأجزاء لموازنة جميع العقد للاحتفاظ بنفس عدد الأجزاء ±10%. على وجه التحديد، سيحاول إعادة توازن الجزء تقارب استخدام جميع العقد العاملة إلى (1 - الحد) * average_utilization ... (1

الحد) * نطاق average_utilization.

max_shard_moves: (اختياري) الحد الأقصى لعدد الأجزاء المراد نقلها.

excluded_shard_list: (اختياري) معرفات الأجزاء التي لا يجب نقلها أثناء عملية إعادة التوازن.

auto: يتطلب هوية النسخ المتماثل إذا كان النسخ المتماثل المنطقي ممكنا، وإلا استخدم السلوك القديم (على سبيل المثال لإصلاح الجزء، PostgreSQL 9.6). وتكون هذه هي القيمة الافتراضية.

force_logical: استخدم النسخ المتماثل المنطقي حتى إذا لم يكن للجدول هوية نسخة متماثلة. ستفشل أي عبارات تحديث/حذف متزامنة إلى الجدول أثناء النسخ المتماثل.

block_writes: استخدم COPY (حظر عمليات الكتابة) للجداول التي تفتقر إلى المفتاح الأساسي أو هوية النسخة المتماثلة.

drain_only: (اختياري) عندما يكون صحيحًا، انقل الأجزاء من العقد العاملة التي تم shouldhaveshards تعيينها إلى خطأ في pg_dist_node؛ لا تنقل أي أجزاء أخرى.

rebalance_strategy: (اختياري) اسم الاستراتيجية في pg_dist_rebalance_strategy. إذا تم حذف هذه الوسيطة، تختار الدالة الاستراتيجية الافتراضية، كما هو موضح في الجدول.

قيمة الإرجاع

‏‫غير متوفر‬

مثال

سيحاول المثال أدناه إعادة توازن أجزاء الجدول github_events ضمن الحد الافتراضي.

SELECT rebalance_table_shards('github_events');

سيحاول مثال الاستخدام هذا إعادة توازن جدول github_events دون نقل الأجزاء ذات المعرف 1 و2.

SELECT rebalance_table_shards('github_events', excluded_shard_list:='{1,2}');

get_rebalance_table_shards_plan

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

الوسيطات

نفس الوسيطات مثل rebalance_table_shards: العلاقة والحد وmax_shard_moves وexcluded_shard_list وdrain_only. راجع وثائق هذه الدالة لمعرفة معنى الوسيطات.

قيمة الإرجاع

المجموعات التي تحتوي على هذه الأعمدة:

table_name: الجدول الذي ستتحرك أجزاءه
shardid: الجزء المعني
shard_size: الحجم بالبايت
sourcename: اسم المضيف للعقدة المصدر
sourceport: منفذ العقدة المصدر
targetname: اسم المضيف للعقدة الوجهة
targetport: منفذ العقدة الوجهة

get_rebalance_progress

بمجرد بدء إعادة توازن الجزء، تسرد الدالة get_rebalance_progress() تقدم كل جزء معني. يراقب التحركات المخططة والمنفذة بواسطة rebalance_table_shards().

الوسيطات

‏‫غير متوفر‬

قيمة الإرجاع

المجموعات التي تحتوي على هذه الأعمدة:

sessionid: Postgres PID لمراقبة إعادة التوازن
table_name: الجدول الذي تتحرك أجزاءه
shardid: الجزء المعني
shard_size: الحجم بالبايت
sourcename: اسم المضيف للعقدة المصدر
sourceport: منفذ العقدة المصدر
targetname: اسم المضيف للعقدة الوجهة
targetport: منفذ العقدة الوجهة
التقدم: 0 = في انتظار النقل؛ 1 = نقل؛ 2 = مكتمل

مثال

SELECT * FROM get_rebalance_progress();

┌───────────┬────────────┬─────────┬────────────┬───────────────┬────────────┬───────────────┬────────────┬──────────┐
│ sessionid │ table_name │ shardid │ shard_size │  sourcename   │ sourceport │  targetname   │ targetport │ progress │
├───────────┼────────────┼─────────┼────────────┼───────────────┼────────────┼───────────────┼────────────┼──────────┤
│      7083 │ foo        │  102008 │    1204224 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102009 │    1802240 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102018 │     614400 │ n2.foobar.com │       5432 │ n4.foobar.com │       5432 │        1 │
│      7083 │ foo        │  102019 │       8192 │ n3.foobar.com │       5432 │ n4.foobar.com │       5432 │        2 │
└───────────┴────────────┴─────────┴────────────┴───────────────┴────────────┴───────────────┴────────────┴──────────┘

citus_add_rebalance_strategy

إلحاق صف pg_dist_rebalance_strategy .

الوسيطات

لمزيد من التفاصيل حول هذه الوسيطات، راجع قيم العمود المقابلة في pg_dist_rebalance_strategy.

الاسم: معرف الاستراتيجية الجديدة

shard_cost_function: يحدد الدالة المستخدمة لتحديد "التكلفة" لكل جزء

node_capacity_function: يحدد الدالة لقياس سعة العقدة

shard_allowed_on_node_function: يحدد الدالة التي تحدد الأجزاء التي يمكن وضعها على العقد

default_threshold: حد النقطة العائمة الذي يضبط مدى دقة تكلفة القطع التراكمية التي يجب أن تكون متوازنة بين العقد

minimum_threshold: (اختياري) عمود حماية يحتوي على الحد الأدنى للقيمة المسموح بها لوسيطة الحد rebalance_table_shards(). القيمة الافتراضية هي 0

قيمة الإرجاع

‏‫غير متوفر‬

citus_set_default_rebalance_strategy

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

الوسيطات

name: اسم الاستراتيجية في pg_dist_rebalance_strategy

قيمة الإرجاع

‏‫غير متوفر‬

مثال

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

تعرض الدالة citus_remote_connection_stats() عدد الاتصالات النشطة بكل عقدة بعيدة.

الوسيطات

‏‫غير متوفر‬

مثال

SELECT * from citus_remote_connection_stats();

    hostname    | port | database_name | connection_count_to_node
----------------+------+---------------+--------------------------
 citus_worker_1 | 5432 | postgres      |                        3
(1 row)

isolate_tenant_to_new_shard

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

الوسيطات

table_name: اسم الجدول للحصول على جزء جديد.

tenant_id: قيمة عمود التوزيع الذي سيتم تعيينه إلى الجزء الجديد.

cascade_option: (اختياري) عند التعيين إلى "CASCADE"، يقوم أيضًا بعزل جزء من كافة الجداول في مجموعة الموقع المشترك للجدول الحالي.

قيمة الإرجاع

shard_id: ترجع الدالة المعرف الفريد المعين للجزء الذي تم إنشاؤه حديثًا.

الأمثلة

إنشاء جزء جديد للاحتفاظ بـ lineitems للمستأجر 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│                      102240 │
└─────────────────────────────┘

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

تقوم العديد من الدالات في هذه المقالة بتعديل جداول بيانات تعريف النظام
تقوم معلمات الخادم بتخصيص سلوك بعض الوظائف

مشاركة عبر

Azure Cosmos DB لوظائف PostgreSQL

Table وShard DDL

citus_schema_distribute

الوسيطات

قيمة الإرجاع

مثال

citus_schema_undistribute

الوسيطات

قيمة الإرجاع

مثال

create_distributed_table

الوسيطات

قيمة الإرجاع

مثال

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

الوسيطات

قيمة الإرجاع

مثال

create_reference_table

الوسيطات

قيمة الإرجاع

مثال

citus_add_local_table_to_metadata

الوسيطات

قيمة الإرجاع

مثال

alter_distributed_table

الوسيطات

قيمة الإرجاع

مثال

update_distributed_table_colocation

الوسيطات

قيمة الإرجاع

مثال

undistribute_table

الوسيطات

قيمة الإرجاع

مثال

create_distributed_function

الوسيطات

قيمة الإرجاع

مثال

alter_columnar_table_set

الوسيطات

قيمة الإرجاع

مثال

alter_table_set_access_method

الوسيطات

قيمة الإرجاع

مثال

create_time_partitions

الوسيطات

قيمة الإرجاع

مثال

drop_old_time_partitions

الوسيطات

قيمة الإرجاع

مثال

alter_old_partitions_set_access_method

الوسيطات

قيمة الإرجاع

مثال

بيانات التعريف / معلومات التكوين

get_shard_id_for_distribution_column

الوسيطات

قيمة الإرجاع

مثال

column_to_column_name

الوسيطات

قيمة الإرجاع

مثال

citus_relation_size

الوسيطات

قيمة الإرجاع

مثال

citus_table_size

الوسيطات

قيمة الإرجاع