> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > توثيق COLUMN # التعامل مع الأعمدة مجموعة من الاستعلامات التي تتيح تغيير بنية الجدول. الصيغة: ```sql theme={null} ALTER [TEMPORARY] TABLE [db].name [ON CLUSTER cluster] ADD|DROP|RENAME|CLEAR|COMMENT|{MODIFY|ALTER}|MATERIALIZE COLUMN ... ``` في الاستعلام، حدِّد قائمة تضم إجراءً واحدًا أو أكثر، مفصولة بفواصل. كل إجراء هو عملية تُجرى على عمود. الإجراءات التالية مدعومة: * [ADD COLUMN](#add-column) — يضيف عمودًا جديدًا إلى الجدول. * [DROP COLUMN](#drop-column) — يحذف العمود. * [RENAME COLUMN](#rename-column) — يعيد تسمية عمود موجود. * [CLEAR COLUMN](#clear-column) — يعيد تعيين قيم العمود. * [COMMENT COLUMN](#comment-column) — يضيف تعليقًا نصيًا إلى العمود. * [MODIFY COLUMN](#modify-column) — يغيّر نوع العمود، وتعبيره الافتراضي، وTTL، وإعدادات العمود. * [MODIFY COLUMN REMOVE](#modify-column-remove) — يزيل إحدى خصائص العمود. * [MODIFY COLUMN MODIFY SETTING](#modify-column-modify-setting) - يغيّر إعدادات العمود. * [MODIFY COLUMN RESET SETTING](#modify-column-reset-setting) - يعيد تعيين إعدادات العمود. * [MODIFY COLUMN ADD ENUM VALUES](#modify-column-add-enum-values) - يضيف قيمًا جديدة إلى Enum. * [MATERIALIZE COLUMN](#materialize-column) — يُجسِّد العمود في الأجزاء التي يكون فيها العمود مفقودًا. يَرِد وصف هذه الإجراءات بالتفصيل أدناه.
## ADD COLUMN
```sql theme={null} ADD COLUMN [IF NOT EXISTS] name [type] [default_expr] [codec] [AFTER name_after | FIRST] ``` يضيف عمودًا جديدًا إلى الجدول باستخدام `name` و`type` و[`codec`](/ar/reference/statements/create/table#column_compression_codec) و`default_expr` المحددة (راجع قسم [التعبيرات الافتراضية](/ar/reference/statements/create/table#default_values)). إذا كانت العبارة `IF NOT EXISTS` مضمنة، فلن يُرجع الاستعلام خطأً إذا كان العمود موجودًا بالفعل. وإذا حدّدت `AFTER name_after` (اسم عمود آخر)، فسيُضاف العمود بعد العمود المحدد في قائمة أعمدة الجدول. وإذا أردت إضافة عمود إلى بداية الجدول، فاستخدم العبارة `FIRST`. بخلاف ذلك، يُضاف العمود إلى نهاية الجدول. وفي سلسلة من الإجراءات، يمكن أن يكون `name_after` اسم عمود أُضيف في أحد الإجراءات السابقة. إن إضافة عمود لا تغيّر سوى بنية الجدول، من دون تنفيذ أي إجراءات على البيانات. ولا تظهر البيانات على القرص بعد `ALTER`. وإذا كانت البيانات مفقودة لعمود ما عند القراءة من الجدول، فتُستكمل بالقيم الافتراضية (من خلال تنفيذ التعبير الافتراضي إن وُجد، أو باستخدام الأصفار أو السلاسل الفارغة). ويظهر العمود على القرص بعد دمج أجزاء البيانات (راجع [MergeTree](/ar/reference/engines/table-engines/mergetree-family/mergetree)). يتيح هذا النهج إكمال الاستعلام `ALTER` على الفور، من دون زيادة حجم البيانات القديمة. مثال: ```sql theme={null} 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; ``` ```text theme={null} 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
```sql theme={null} DROP COLUMN [IF EXISTS] name ``` يحذف العمود الذي يحمل الاسم `name`. إذا تم تحديد العبارة `IF EXISTS`، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا. يحذف البيانات من نظام الملفات. ونظرًا لأن هذا يحذف ملفات كاملة، يكتمل الاستعلام بشكل شبه فوري. لا يمكنك حذف عمود إذا كان مُشارًا إليه بواسطة [عرض مادي](/ar/reference/statements/create/view). وإلا فسيُرجع خطأً. مثال: ```sql theme={null} ALTER TABLE visits DROP COLUMN browser ```
## RENAME COLUMN
```sql theme={null} RENAME COLUMN [IF EXISTS] name to new_name ``` يعيد تسمية العمود `name` إلى `new_name`. إذا تم تحديد العبارة `IF EXISTS`، فلن يُرجع الاستعلام خطأً إذا كان العمود غير موجود. ونظرًا إلى أن إعادة التسمية لا تتضمن البيانات الفعلية، يكتمل الاستعلام بشكل شبه فوري. **ملاحظة**: لا يمكن إعادة تسمية الأعمدة المحددة في تعبير مفتاح الجدول (سواء باستخدام `ORDER BY` أو `PRIMARY KEY`). وستؤدي محاولة تغيير هذه الأعمدة إلى ظهور `SQL Error [524]`. مثال: ```sql theme={null} ALTER TABLE visits RENAME COLUMN webBrowser TO browser ```
## CLEAR COLUMN
```sql theme={null} CLEAR COLUMN [IF EXISTS] name IN PARTITION partition_name ``` يعيد ضبط جميع البيانات في عمود ضمن تقسيم محدد. اقرأ المزيد عن كيفية تحديد اسم التقسيم في قسم [كيفية تعيين تعبير التقسيم](/ar/reference/statements/alter/partition#how-to-set-partition-expression). إذا تم تحديد العبارة `IF EXISTS`، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا. مثال: ```sql theme={null} ALTER TABLE visits CLEAR COLUMN browser IN PARTITION tuple() ```
## COMMENT COLUMN
```sql theme={null} COMMENT COLUMN [IF EXISTS] name 'Text comment' ``` يضيف تعليقًا إلى العمود. إذا جرى تحديد البند `IF EXISTS`، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا. يمكن أن يكون لكل عمود تعليق واحد. إذا كان هناك تعليق للعمود بالفعل، فإن أي تعليق جديد سيستبدل التعليق السابق. تُخزَّن التعليقات في العمود `comment_expression` الذي يعيده استعلام [DESCRIBE TABLE](/ar/reference/statements/describe-table). مثال: ```sql theme={null} ALTER TABLE visits COMMENT COLUMN browser 'This column shows the browser used for accessing the site.' ```
## MODIFY COLUMN
```sql theme={null} MODIFY COLUMN [IF EXISTS] name [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST] | ADD ENUM VALUES ( 'name' [= number] [, ...] ) ALTER COLUMN [IF EXISTS] name TYPE [type] [default_expr] [codec] [TTL] [settings] [AFTER name_after | FIRST] | ADD ENUM VALUES ( 'name' [= number] [, ...] ) ``` يُغيّر هذا الاستعلام خصائص العمود `name`: * النوع * التعبير الافتراضي * Codec الضغط * TTL * الإعدادات على مستوى العمود * قيم Enum لأنواع Enum/Enum8/Enum16 للاطلاع على أمثلة على تعديل CODECS ضغط الأعمدة، راجع [Column Compression Codecs](/ar/reference/statements/create/table#column_compression_codec). للاطلاع على أمثلة على تعديل TTL للأعمدة، راجع [Column TTL](/ar/reference/engines/table-engines/mergetree-family/mergetree#mergetree-column-ttl). للاطلاع على أمثلة على تعديل الإعدادات على مستوى العمود، راجع [Column-level Settings](/ar/reference/engines/table-engines/mergetree-family/mergetree#column-level-settings). إذا تم تحديد العبارة `IF EXISTS`، فلن يُرجع الاستعلام خطأً إذا لم يكن العمود موجودًا. عند تغيير النوع، تُحوَّل القيم كما لو كانت دوال [toType](/ar/reference/functions/regular-functions/type-conversion-functions) قد طُبِّقت عليها. وإذا جرى تغيير التعبير الافتراضي فقط، فلن ينفّذ الاستعلام أي عمليات معقدة، ويكتمل تقريبًا على الفور. مثال: ```sql theme={null} ALTER TABLE visits MODIFY COLUMN browser Array(String) ``` يُعدّ تغيير نوع العمود الإجراء المعقّد الوحيد، إذ يغيّر محتويات الملفات التي تتضمن البيانات. وقد يستغرق ذلك وقتًا طويلًا في الجداول الكبيرة. يمكن للاستعلام أيضًا تغيير ترتيب الأعمدة باستخدام العبارة `FIRST | AFTER`، راجع وصف [ADD COLUMN](#add-column)، ولكن يكون تحديد نوع العمود إلزاميًا في هذه الحالة. مثال: ```sql theme={null} CREATE TABLE users ( c1 Int16, c2 String ) ENGINE = MergeTree ORDER BY c1; DESCRIBE users; ┌─name─┬─type───┬ │ c1 │ Int16 │ │ c2 │ String │ └──────┴────────┴ ALTER TABLE users MODIFY COLUMN c2 String FIRST; DESCRIBE users; ┌─name─┬─type───┬ │ c2 │ String │ │ c1 │ Int16 │ └──────┴────────┴ ALTER TABLE users ALTER COLUMN c2 TYPE String AFTER c1; DESCRIBE users; ┌─name─┬─type───┬ │ c1 │ Int16 │ │ c2 │ String │ └──────┴────────┴ ``` استعلام `ALTER` ذري. وبالنسبة إلى جداول MergeTree، فهو أيضًا يعمل من دون أقفال. استعلام `ALTER` الخاص بتغيير الأعمدة مُكرَّر. تُحفَظ التعليمات في ZooKeeper، ثم تطبّقها كل نسخة متماثلة. وتُنفَّذ جميع استعلامات `ALTER` بالترتيب نفسه. وينتظر الاستعلام حتى تكتمل الإجراءات المناسبة على النسخ المتماثلة الأخرى. ومع ذلك، يمكن مقاطعة استعلام تغيير الأعمدة في جدول مُكرَّر، وستُنفَّذ جميع الإجراءات بشكل غير متزامن. يُرجى توخّي الحذر عند تغيير عمود من نوع Nullable إلى Non-Nullable. تأكّد من أنه لا يحتوي على أي قيم NULL، وإلا فسيتسبب ذلك في مشكلات عند القراءة منه. في هذه الحالة، يكون الحل البديل هو إيقاف الـ mutation بالقوة ثم إعادة العمود إلى النوع Nullable.
## MODIFY COLUMN REMOVE
يزيل إحدى خصائص العمود التالية: `DEFAULT`, `ALIAS`, `MATERIALIZED`, `CODEC`, `COMMENT`, `TTL`, `SETTINGS`. الصيغة: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name REMOVE property; ``` **مثال** إزالة TTL: ```sql theme={null} ALTER TABLE table_with_ttl MODIFY COLUMN column_ttl REMOVE TTL; ``` **انظر أيضًا** * [REMOVE TTL](/ar/reference/statements/alter/ttl).
## MODIFY COLUMN MODIFY SETTING
عدِّل إعدادات العمود. الصيغة: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING name=value,...; ``` **مثال** عدّل قيمة `max_compress_block_size` للعمود إلى `1MB`: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name MODIFY SETTING max_compress_block_size = 1048576; ```
## MODIFY COLUMN RESET SETTING
أعد ضبط إعداد العمود، ويؤدي ذلك أيضًا إلى إزالة تعريف الإعداد من تعبير العمود في استعلام CREATE الخاص بالجدول. الصيغة: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING name,...; ``` **مثال** أعِد تعيين إعداد العمود `max_compress_block_size` إلى قيمته الافتراضية: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN column_name RESET SETTING max_compress_block_size; ```
## MODIFY COLUMN ADD ENUM VALUES
يضيف قيماً جديدة إلى عمود من النوع `Enum` أو `Enum8` أو `Enum16` أو `Nullable(Enum)` أو `Nullable(Enum8)` أو `Nullable(Enum16)` الصيغة: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('EnumName' [= number], ...); ``` **مثال** أضف قيمتين إلى العمود `enum_column_name`: ```sql theme={null} ALTER TABLE table_name MODIFY COLUMN enum_column_name ADD ENUM VALUES ('Hundred' = 100, 'HundredOne'); ```
## MATERIALIZE COLUMN
يُحوِّل العمود إلى عمود materialized باستخدام تعبير قيمة `DEFAULT` أو `MATERIALIZED`. عند إضافة عمود materialized باستخدام `ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED`، لا تُملأ تلقائيًا الصفوف الحالية التي لا تحتوي على قيم materialized. ويمكن استخدام التعليمة `MATERIALIZE COLUMN` لإعادة كتابة بيانات العمود الحالية بعد إضافة تعبير `DEFAULT` أو `MATERIALIZED` أو تحديثه (إذ لا يؤدّي ذلك إلا إلى تحديث البيانات الوصفية، من دون تغيير البيانات الحالية). لاحظ أن تحويل عمود ضمن مفتاح الفرز إلى عمود materialized عملية غير صالحة، لأنها قد تؤدي إلى كسر ترتيب الفرز. ويُنفَّذ ذلك على هيئة [mutation](/ar/reference/statements/alter/index#mutations). بالنسبة إلى الأعمدة التي تحتوي على تعبير قيمة `MATERIALIZED` جديد أو محدَّث، يُعاد كتابة جميع الصفوف الحالية. أما الأعمدة التي تحتوي على تعبير قيمة `DEFAULT` جديد أو محدَّث، فيعتمد سلوكها على إصدار ClickHouse: * في ClickHouse \< v24.2، يُعاد كتابة جميع الصفوف الحالية. * في ClickHouse >= v24.2، يميّز ClickHouse بين ما إذا كانت قيمة صف في عمود ذي تعبير قيمة `DEFAULT` قد حُدِّدت صراحةً عند insert أم لا، أي ما إذا كانت قد حُسبت من تعبير قيمة `DEFAULT`. فإذا كانت القيمة قد حُدِّدت صراحةً، يُبقيها ClickHouse كما هي. أما إذا كانت القيمة قد حُسبت، فإن ClickHouse يغيّرها إلى تعبير قيمة `MATERIALIZED` الجديد أو المحدَّث. الصياغة: ```sql theme={null} ALTER TABLE [db.]table [ON CLUSTER cluster] MATERIALIZE COLUMN col [IN PARTITION partition | IN PARTITION ID 'partition_id']; ``` * إذا حدّدت PARTITION، فسيُخزَّن العمود فعليًا للتقسيم المحدد فقط. **مثال** ```sql theme={null} 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); ┌─groupArray(x)─┬─groupArray(s)─────────┐ │ [0,1,2,3,4] │ ['0','1','2','3','4'] │ └───────────────┴───────────────────────┘ ALTER TABLE tmp MODIFY COLUMN s String MATERIALIZED toString(round(100/x)); INSERT INTO tmp SELECT * FROM system.numbers LIMIT 5,5; SELECT groupArray(x), groupArray(s) FROM tmp; ┌─groupArray(x)─────────┬─groupArray(s)──────────────────────────────────┐ │ [0,1,2,3,4,5,6,7,8,9] │ ['0','1','2','3','4','20','17','14','12','11'] │ └───────────────────────┴────────────────────────────────────────────────┘ ALTER TABLE tmp MATERIALIZE COLUMN s; SELECT groupArray(x), groupArray(s) FROM tmp; ┌─groupArray(x)─────────┬─groupArray(s)─────────────────────────────────────────┐ │ [0,1,2,3,4,5,6,7,8,9] │ ['inf','100','50','33','25','20','17','14','12','11'] │ └───────────────────────┴───────────────────────────────────────────────────────┘ ``` **انظر أيضًا** * [MATERIALIZED](/ar/reference/statements/create/view#materialized-view).
## القيود
يتيح لك استعلام `ALTER` إنشاء العناصر المنفصلة (الأعمدة) وحذفها داخل بُنى البيانات المتداخلة، لكنه لا يدعم إنشاء بُنى البيانات المتداخلة أو حذفها بالكامل. ولإضافة بنية بيانات متداخلة، يمكنك إضافة أعمدة باسم مثل `name.nested_name` وبنوع `Array(T)`. وتُعد بنية البيانات المتداخلة مكافئة لعدة أعمدة مصفوفات تشترك أسماؤها في البادئة نفسها قبل النقطة. دعم إعادة تسمية الأعمدة التي تتضمن أسماؤها نقاطًا هو دعم جزئي. فالنقاط محجوزة للوصول إلى العمود الفرعي [Nested](/ar/reference/data-types/nested-data-structures/index)، لذلك يجب أن تظل البادئة (اسم الأصل) كما هي. ولا يمكن تغيير سوى اللاحقة (اسم العمود الفرعي). على سبيل المثال، يمكن إعادة تسمية `a.b` إلى `a.c`، لكن لا يُسمح بإعادة تسمية `a.b` إلى `b.d` لأن ذلك يغيّر بادئة الأصل في Nested. لا يوجد دعم لحذف الأعمدة الموجودة في المفتاح الأساسي أو مفتاح أخذ العينات (أي الأعمدة المستخدمة في تعبير `ENGINE`). ولا يمكن تغيير نوع الأعمدة المضمّنة في المفتاح الأساسي إلا إذا كان هذا التغيير لا يؤدي إلى تعديل البيانات (على سبيل المثال، يُسمح بإضافة قيم إلى Enum أو تغيير النوع من `DateTime` إلى `UInt32`). إذا لم يكن استعلام `ALTER` كافيًا لإجراء تغييرات الجدول التي تحتاج إليها، فيمكنك إنشاء جدول جديد، ونسخ البيانات إليه باستخدام استعلام [INSERT SELECT](/ar/reference/statements/insert-into#inserting-the-results-of-select)، ثم تبديل الجدولين باستخدام استعلام [RENAME](/ar/reference/statements/rename#rename-table) وحذف الجدول القديم. يحظر استعلام `ALTER` جميع عمليات القراءة والكتابة على الجدول. وبعبارة أخرى، إذا كان استعلام `SELECT` طويلًا قيد التنفيذ وقت تشغيل استعلام `ALTER`، فسوف ينتظر استعلام `ALTER` حتى يكتمل. وفي الوقت نفسه، ستنتظر جميع الاستعلامات الجديدة على الجدول نفسه طوال فترة تنفيذ `ALTER`. بالنسبة إلى الجداول التي لا تخزّن البيانات بنفسها (مثل [Merge](/ar/reference/statements/alter/index) و[Distributed](/ar/reference/statements/alter/index))، فإن `ALTER` يغيّر بنية الجدول فقط، ولا يغيّر بنية الجداول التابعة. على سبيل المثال، عند تشغيل `ALTER` على جدول `Distributed`، ستحتاج أيضًا إلى تشغيل `ALTER` على الجداول الموجودة على جميع الخوادم البعيدة.