ALTER TABLE ... COLUMN

مجموعة من الاستعلامات التي تتيح تغيير بنية الجدول.

الصيغة:

ALTER [TEMPORARY] TABLE [db].name [ON CLUSTER cluster] ADD|DROP|RENAME|CLEAR|COMMENT|{MODIFY|ALTER}|MATERIALIZE COLUMN ...

في الاستعلام، حدِّد قائمة تضم إجراءً واحدًا أو أكثر، مفصولة بفواصل. كل إجراء هو عملية تُجرى على عمود.

الإجراءات التالية مدعومة:

• ADD COLUMN — يضيف عمودًا جديدًا إلى الجدول.
• DROP COLUMN — يحذف العمود.
• RENAME COLUMN — يعيد تسمية عمود موجود.
• CLEAR COLUMN — يعيد تعيين قيم العمود.
• COMMENT COLUMN — يضيف تعليقًا نصيًا إلى العمود.
• MODIFY COLUMN — يغيّر نوع العمود، وتعبيره الافتراضي، وTTL، وإعدادات العمود.
• MODIFY COLUMN REMOVE — يزيل إحدى خصائص العمود.
• MODIFY COLUMN MODIFY SETTING - يغيّر إعدادات العمود.
• MODIFY COLUMN RESET SETTING - يعيد تعيين إعدادات العمود.
• MODIFY COLUMN ADD ENUM VALUES - يضيف قيمًا جديدة إلى Enum.
• MATERIALIZE COLUMN — يُجسِّد العمود في الأجزاء التي يكون فيها العمود مفقودًا. يَرِد وصف هذه الإجراءات بالتفصيل أدناه.

ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]

يضيف عمودًا جديدًا إلى الجدول باستخدام name وtype وcodec وdefault_expr المحددة (راجع قسم التعبيرات الافتراضية). ويمكن كتابة المعدلات التي تلي النوع بأي ترتيب، وكل منها مرة واحدة على الأكثر - راجع وصف العمود.

إذا كانت العبارة IF NOT EXISTS مضمنة، فلن يُرجع الاستعلام خطأً إذا كان العمود موجودًا بالفعل. وإذا حدّدت AFTER name_after (اسم عمود آخر)، فسيُضاف العمود بعد العمود المحدد في قائمة أعمدة الجدول. وإذا أردت إضافة عمود إلى بداية الجدول، فاستخدم العبارة FIRST. بخلاف ذلك، يُضاف العمود إلى نهاية الجدول. وفي سلسلة من الإجراءات، يمكن أن يكون name_after اسم عمود أُضيف في أحد الإجراءات السابقة.

إن إضافة عمود لا تغيّر سوى بنية الجدول، من دون تنفيذ أي إجراءات على البيانات. ولا تظهر البيانات على القرص بعد ALTER. وإذا كانت البيانات مفقودة لعمود ما عند القراءة من الجدول، فتُستكمل بالقيم الافتراضية (من خلال تنفيذ التعبير الافتراضي إن وُجد، أو باستخدام الأصفار أو السلاسل الفارغة). ويظهر العمود على القرص بعد دمج أجزاء البيانات (راجع MergeTree).

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

مثال:

ALTER TABLE alter_test ADD COLUMN Added1 UInt32 FIRST;
ALTER TABLE alter_test ADD COLUMN Added2 UInt32 AFTER NestedColumn;
ALTER TABLE alter_test ADD COLUMN Added3 UInt32 AFTER ToDrop;
DESC alter_test FORMAT TSV;

Added1  UInt32
CounterID       UInt32
StartDate       Date
UserID  UInt32
VisitID UInt32
NestedColumn.A  Array(UInt8)
NestedColumn.S  Array(String)
Added2  UInt32
ToDrop  UInt32
Added3  UInt32

DROP COLUMN [IF EXISTS] name

يحذف العمود الذي يحمل الاسم name. إذا تم تحديد العبارة IF EXISTS، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا.

يحذف البيانات من نظام الملفات. ونظرًا لأن هذا يحذف ملفات كاملة، يكتمل الاستعلام بشكل شبه فوري.

مثال:

ALTER TABLE visits DROP COLUMN browser

RENAME COLUMN [IF EXISTS] name to new_name

يعيد تسمية العمود name إلى new_name. إذا تم تحديد العبارة IF EXISTS، فلن يُرجع الاستعلام خطأً إذا كان العمود غير موجود. ونظرًا إلى أن إعادة التسمية لا تتضمن البيانات الفعلية، يكتمل الاستعلام بشكل شبه فوري.

ملاحظة: لا يمكن إعادة تسمية الأعمدة المحددة في تعبير مفتاح الجدول (سواء باستخدام ORDER BY أو PRIMARY KEY). وستؤدي محاولة تغيير هذه الأعمدة إلى ظهور SQL Error [524].

مثال:

ALTER TABLE visits RENAME COLUMN webBrowser TO browser

CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_name

يعيد ضبط جميع البيانات في عمود ضمن تقسيم محدد. اقرأ المزيد عن كيفية تحديد اسم التقسيم في قسم كيفية تعيين تعبير التقسيم.

إذا تم تحديد العبارة IF EXISTS، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا.

مثال:

ALTER TABLE visits CLEAR COLUMN browser IN PARTITION tuple()

COMMENT COLUMN [IF EXISTS] name 'Text comment'

يضيف تعليقًا إلى العمود. إذا جرى تحديد البند IF EXISTS، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا.

يمكن أن يكون لكل عمود تعليق واحد. إذا كان هناك تعليق للعمود بالفعل، فإن أي تعليق جديد سيستبدل التعليق السابق.

تُخزَّن التعليقات في العمود comment_expression الذي يعيده استعلام DESCRIBE TABLE.

مثال:

ALTER TABLE visits COMMENT COLUMN browser 'This column shows the browser used for accessing the site.'

MODIFY COLUMN [IF EXISTS] name
    [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )
ALTER COLUMN [IF EXISTS] name
    TYPE [type] [default_expr] [COMMENT 'comment for column'] [codec] [STATISTICS] [TTL] [settings] [AFTER name_after | FIRST]
    | ADD ENUM VALUES ( 'name' [= number] [, ...] )

يمكن كتابة المُعدِّلات التي تلي النوع بأي ترتيب، على ألا يتكرر أيٌّ منها أكثر من مرة — راجع وصف العمود.

يُغيّر هذا الاستعلام خصائص العمود name:

• النوع

• التعبير الافتراضي

• Codec الضغط

• TTL

• الإعدادات على مستوى العمود

• قيم Enum لأنواع Enum/Enum8/Enum16

للاطلاع على أمثلة على تعديل CODECS ضغط الأعمدة، راجع Column Compression Codecs.

للاطلاع على أمثلة على تعديل TTL للأعمدة، راجع Column TTL.

للاطلاع على أمثلة على تعديل الإعدادات على مستوى العمود، راجع Column-level Settings.

إذا تم تحديد العبارة IF EXISTS، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا.

عند تغيير النوع، تُحوَّل القيم كما لو كانت دوال toType قد طُبِّقت عليها. وإذا جرى تغيير التعبير الافتراضي فقط، فلن ينفّذ الاستعلام أي عمليات معقدة، ويكتمل تقريبًا على الفور.

مثال:

ALTER TABLE visits MODIFY COLUMN browser Array(String)

يُعدّ تغيير نوع العمود الإجراء المعقّد الوحيد، إذ يغيّر محتويات الملفات التي تتضمن البيانات. وقد يستغرق ذلك وقتًا طويلًا في الجداول الكبيرة.

يمكن للاستعلام أيضًا تغيير ترتيب الأعمدة باستخدام العبارة FIRST | AFTER، راجع وصف ADD COLUMN، ولكن يكون تحديد نوع العمود إلزاميًا في هذه الحالة.

مثال:

CREATE TABLE users (
    c1 Int16,
    c2 String
) ENGINE = MergeTree
ORDER BY c1;

DESCRIBE users;
┌

استعلام ALTER ذري. وبالنسبة إلى جداول MergeTree، فهو أيضًا يعمل من دون أقفال.

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

يزيل إحدى خصائص العمود التالية: DEFAULT, ALIAS, MATERIALIZED, CODEC, COMMENT, TTL, SETTINGS.

الصيغة:

ALTER TABLE table_name MODIFY COLUMN column_name REMOVE property;

مثال

إزالة TTL:

ALTER TABLE table_with_ttl MODIFY COLUMN column_ttl REMOVE TTL;

انظر أيضًا

• REMOVE TTL.

عدِّل إعدادات العمود.

الصيغة:

ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING name=value,...;

مثال

عدّل قيمة max_compress_block_size للعمود إلى 1MB:

ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING max_compress_block_size = 1048576;

أعد ضبط إعداد العمود، ويؤدي ذلك أيضًا إلى إزالة تعريف الإعداد من تعبير العمود في استعلام CREATE الخاص بالجدول.

الصيغة:

ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING name,...;

مثال

أعِد تعيين إعداد العمود max_compress_block_size إلى قيمته الافتراضية:

ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING max_compress_block_size;

يضيف قيماً جديدة إلى عمود من النوع Enum أو Enum8 أو Enum16 أو Nullable(Enum) أو Nullable(Enum8) أو Nullable(Enum16)

الصيغة:

ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('EnumName' [= number], ...);

مثال

أضف قيمتين إلى العمود enum_column_name:

ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('Hundred' = 100, 'HundredOne');

يُجسِّد العمود إلى عمود مادي باستخدام تعبير قيمة DEFAULT أو MATERIALIZED. عند إضافة عمود مادي باستخدام ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED، لا تُملأ تلقائيًا الصفوف الحالية التي لا تحتوي على قيم مادية. ويمكن استخدام التعليمة MATERIALIZE COLUMN لإعادة كتابة بيانات العمود الحالية بعد إضافة تعبير DEFAULT أو MATERIALIZED أو تحديثه (إذ لا يؤدّي ذلك إلا إلى تحديث البيانات الوصفية، من دون تغيير البيانات الحالية). لاحظ أن تحويل عمود ضمن مفتاح الفرز إلى عمود مادي عملية غير صالحة، لأنها قد تؤدي إلى كسر ترتيب الفرز. ويُنفَّذ ذلك على هيئة mutation.

بالنسبة إلى الأعمدة التي تحتوي على تعبير قيمة MATERIALIZED جديد أو محدَّث، يُعاد كتابة جميع الصفوف الحالية.

أما الأعمدة التي تحتوي على تعبير قيمة DEFAULT جديد أو محدَّث، فيعتمد سلوكها على إصدار ClickHouse:

• في ClickHouse < v24.2، يُعاد كتابة جميع الصفوف الحالية.
• في ClickHouse >= v24.2، يميّز ClickHouse بين ما إذا كانت قيمة صف في عمود ذي تعبير قيمة DEFAULT قد حُدِّدت صراحةً عند insert أم لا، أي ما إذا كانت قد حُسبت من تعبير قيمة DEFAULT. فإذا كانت القيمة قد حُدِّدت صراحةً، يُبقيها ClickHouse كما هي. أما إذا كانت القيمة قد حُسبت، فإن ClickHouse يغيّرها إلى تعبير قيمة MATERIALIZED الجديد أو المحدَّث.

الصياغة:

ALTER TABLE [db.]table [ON CLUSTER cluster] MATERIALIZE COLUMN col [IN PARTITION partition | IN PARTITION ID 'partition_id'];

• إذا حدّدت PARTITION، فسيُجسَّد العمود للتقسيم المحدد فقط.

مثال

DROP TABLE IF EXISTS tmp;
SET mutations_sync = 2;
CREATE TABLE tmp (x Int64) ENGINE = MergeTree() ORDER BY tuple() PARTITION BY tuple();
INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5;
ALTER TABLE tmp ADD COLUMN s String MATERIALIZED toString(x);

ALTER TABLE tmp MATERIALIZE COLUMN s;

SELECT groupArray(x), groupArray(s) FROM (select x,s from tmp order by x);

┌

انظر أيضًا

• MATERIALIZED.
• MATERIALIZE INDEX.

يتيح لك استعلام ALTER إنشاء العناصر المنفصلة (الأعمدة) وحذفها داخل بُنى البيانات المتداخلة، لكنه لا يدعم إنشاء بُنى البيانات المتداخلة أو حذفها بالكامل. ولإضافة بنية بيانات متداخلة، يمكنك إضافة أعمدة باسم مثل name.nested_name وبنوع Array(T). وتُعد بنية البيانات المتداخلة مكافئة لعدة أعمدة مصفوفات تشترك أسماؤها في البادئة نفسها قبل النقطة.

دعم إعادة تسمية الأعمدة التي تتضمن أسماؤها نقاطًا هو دعم جزئي. فالنقاط محجوزة للوصول إلى العمود الفرعي Nested، لذلك يجب أن تظل البادئة (اسم الأصل) كما هي. ولا يمكن تغيير سوى اللاحقة (اسم العمود الفرعي). على سبيل المثال، يمكن إعادة تسمية a.b إلى a.c، لكن لا يُسمح بإعادة تسمية a.b إلى b.d لأن ذلك يغيّر بادئة الأصل في Nested.

لا يوجد دعم لحذف الأعمدة الموجودة في المفتاح الأساسي أو مفتاح أخذ العينات (أي الأعمدة المستخدمة في تعبير ENGINE). ولا يمكن تغيير نوع الأعمدة المضمّنة في المفتاح الأساسي إلا إذا كان هذا التغيير لا يؤدي إلى تعديل البيانات (على سبيل المثال، يُسمح بإضافة قيم إلى Enum أو تغيير النوع من DateTime إلى UInt32).

إذا لم يكن استعلام ALTER كافيًا لإجراء تغييرات الجدول التي تحتاج إليها، فيمكنك إنشاء جدول جديد، ونسخ البيانات إليه باستخدام استعلام INSERT SELECT، ثم تبديل الجدولين باستخدام استعلام RENAME وحذف الجدول القديم.

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

بالنسبة إلى الجداول التي لا تخزّن البيانات بنفسها (مثل Merge وDistributed)، فإن ALTER يغيّر بنية الجدول فقط، ولا يغيّر بنية الجداول التابعة. على سبيل المثال، عند تشغيل ALTER على جدول Distributed، ستحتاج أيضًا إلى تشغيل ALTER على الجداول الموجودة على جميع الخوادم البعيدة.