الأدوات

يوفر الخادم 77 أداة: خمس أدوات جلسة، وأربع أدوات قراءة، و67 أداة تحرير، واحدة لكل عملية تحرير، وerd_batch التي تشغّل عدة أدوات تحرير بوصفها تعديلًا واحدًا.

تأخذ كل أداة باستثناء erd_list_documents مسار المستند path بوصفه وسيطتها الأولى، وتُغفله الجداول أدناه. الوسيطة التي تحمل العلامة ? اختيارية.

أدوات الجلسة

الأداة	الوسائط	ما تفعله
erd_list_documents		تسرد مستندات ERD مع path وopen وactive وdirty وreadonly: مستندات المحرر الذي يخدم مجلد العمل، وتشمل في بيئة تطوير JetBrains كل مشروع مفتوح، وإلا فملفات ERD الموجودة ضمن مجلد العمل.
erd_open_document	create?	تفتح مستندًا للتحرير، في ERD Editor التابع للمحرر الذي يخدمه، إن وُجد. مع create تنشئ الملف أولًا إن لم يكن موجودًا، ويُضاف .erd.json إلى الاسم الذي لا امتداد له.
erd_save		تحفظ مستندًا يحتفظ به محرر. يُبقي VS Code تعديلات الوكيل غير محفوظة إلى أن تُستدعى هذه الأداة؛ أما Obsidian وبيئة تطوير JetBrains فيحفظانها كما يحفظان تعديلاتك، وتكتبها هذه الأداة فورًا. في الوضع بدون واجهة، يكون كل تعديل مكتوبًا بالفعل، كما تُبيّن القيمة saved: true في نتيجته، ولا تفعل هذه الأداة شيئًا.
erd_undo		تتراجع عن آخر تعديل أجراه هذا الوكيل، ولا تتراجع أبدًا عن تعديلاتك. تتخطى الاستدعاءات التي لم تُنشئ إدخال تراجع وتذكر أسماءها.
erd_redo		تعيد تطبيق التعديل الذي تراجعت عنه erd_undo آخر مرة.

لمعرفة ما يفعله الحفظ والتراجع في كل وضع، راجع الوضع المباشر والوضع بدون واجهة.

قراءة مستند

الأداة	الوسائط	ما تفعله
erd_list	query?, offset?, limit?, namesOnly?	الإعدادات والأعداد، ثم صفحة من الجداول مع فهارسها وعلاقاتها، وكل جدول بمعرّفه وموضعه وحجمه على لوحة الرسم وعدد أعمدته واسمه المنطقي إن كان له اسم منطقي، ومجموعة الجداول التي ينتمي إليها إن كان في إحداها. ما لم تُجرِ بحثًا، تأتي بعد الجداول مجموعاتُ الجداول والملاحظات، ثم المجالات والمصطلحات والكلمات.
erd_get	tableIds?, tableNames?, relationshipIds?, indexIds?, memoIds?, tableGroupIds?, wordIds?, termIds?, domainIds?	الكيانات المسمّاة كاملةً: الجداول مع أعمدتها ومجموعة جداولها، والعلاقات مع أعمدتها وقيمتي onDelete وonUpdate الخاصتين بها، والفهارس مع أعمدتها، والملاحظات مع نصوصها، ومجموعات الجداول مع جداولها، والكلمات والمصطلحات والمجالات بكل حقولها.
erd_read	format, vendor?, statements?, header?, logicalNameAsComment?, tableIds?, tableNames?, groupNames?	المستند كله مرة واحدة بأحد أربعة تنسيقات، أو DDL بعض الجداول أو مجموعات الجداول فقط.
erd_list_checks	level?, tableIds?, tableNames?, offset?, limit?	ما ترصده قواميس الكلمات والمصطلحات والمجالات من أخطاء، كما تسرده الورقة Checks في علامة تبويب القاموس في المحرر، صفحةً صفحة. لا تغيّر شيئًا، راجع فحوصات القاموس.

يعثر الوكيل على المعرّفات باستخدام erd_list، ويقرأ الأعمدة وصفوف القواميس والتفاصيل الأخرى باستخدام erd_get، ثم يمرّر تلك المعرّفات إلى أدوات التحرير. حجم الجدول في erd_list هو المربع الذي يشغله على لوحة الرسم: الارتفاع دقيق والعرض تقريبي. تُسرد مجموعة الجداول بالمستطيل الذي تخزنه، مع اسمها ولونها وعدد الجداول التي تضمها. تُسرد كل علاقة مرة واحدة، مع أحد جدوليها. يُسرد صف القاموس بمعرّفه وname الخاص به وما يعطيه لاسم مادي أو لعمود: dataType للمجال، وphysicalName وdomainId للمصطلح، وabbreviation للكلمة. ويسرد كل قاموس صفوفه بالترتيب الذي تعرضه ورقته. الإعدادات التي تُبلغ عنها erd_list وerd_read هي تلك التي يحفظها الملف، راجع الإعدادات.

في erd_get والتنسيق snapshot في erd_read، يحمل كل جدول وعمود logicalName الخاص به، وهو سلسلة نصية فارغة إن لم يكن له اسم منطقي، وnameDerived، الذي تكون قيمته true ما دامت القواميس هي التي أعطت الاسم، فيشتقه الاسم المنطقي الجديد من جديد، راجع القواميس. ويحمل كل عمود domainId الخاص به، وكذلك كل مصطلح: سلسلة نصية فارغة إن لم يكن مرتبطًا بأي مجال، أو إن كان مرتبطًا بمجال لم يعد المستند يسرده.

تأخذ erd_read أحد أربعة تنسيقات:

format	ما تُرجعه
snapshot	JSON مضغوط يضم كل كيان ومعرّفه، بما في ذلك مجموعات الجداول وصفوف الكلمات والمصطلحات والمجالات، والإعدادات مع سكربتات مخطط SQL. يستبعد ما يختلف من مشاهد إلى آخر: عروض الجداول المقيسة وترتيب التراص وموضع العرض وعلامة التبويب وعرض الأسماء. يكون كبيرًا في المخططات الكبيرة.
sql	DDL لإحدى قواعد البيانات الثماني، Databricks أو MariaDB أو MSSQL أو MySQL أو Oracle أو PostgreSQL أو Snowflake أو SQLite. القيمة الافتراضية للوسيطة vendor هي قاعدة البيانات المضبوط عليها المستند. يتضمن DDL المستند كله سكربتاته قبل الجداول وبعدها. مع tableIds أو tableNames أو groupNames، تلك الجداول فقط، مع المفاتيح الخارجية التي تحملها، ودون سكربتات. تحمل المفاتيح الخارجية إجراءات ON DELETE وON UPDATE الخاصة بها، باستثناء ما تستبعده قاعدة البيانات المستهدفة، راجع ON DELETE وON UPDATE.
json	المستند كله تمامًا كما يكتب الحفظ الملف، بما في ذلك أي تعديلات لم يحفظها المحرر بعد، راجع صيغة التخزين.
scripts	سكربتات المستند قبل الجداول وبعدها وحدها، بالشكل {"before":"…","after":"…"}، وكلٌّ منها فارغ إن لم يُضبط، مهما كان حجم المخطط.

لا يأخذ vendor وstatements وheader وlogicalNameAsComment وtableIds وtableNames وgroupNames إلا التنسيق sql، ويرفضها أي تنسيق آخر.

• statements: create، وهي القيمة الافتراضية؛ أو ifNotExists، التي تكتب CREATE TABLE IF NOT EXISTS في MySQL وMariaDB وPostgreSQL وSQLite وDatabricks وعبارة CREATE TABLE العادية في البقية؛ أو recreate، التي تحذف الجداول قبل إنشائها، وفيها يكتب Snowflake بدلًا من ذلك CREATE OR REPLACE TABLE.
• header: none، وهي القيمة الافتراضية؛ أو use، التي تحدد قاعدة البيانات أو المخطط المسمّى باسم قاعدة البيانات في المستند؛ أو createAndUse، التي تنشئه أولًا. ليس لدى Oracle سوى use، لذا تكتب createAndUse فيه use، وليس لدى PostgreSQL سوى createAndUse، لذا لا تكتب use فيه أي ترويسة. لا يكتب SQLite أي ترويسة، ولا تكتب أي قاعدة بيانات ترويسة ما دام اسم قاعدة البيانات فارغًا أو ليس معرّفًا بسيطًا.
• logicalNameAsComment: تكتب true الاسم المنطقي للجدول أو العمود كتعليق له ما دام التعليق فارغًا أو لا يحوي إلا مسافات، حيث تكتب كل قاعدة بيانات التعليق وبالصيغة التي تكتبه بها، وتُبقي كل تعليق يحوي نصًا؛ أما false، وهي القيمة الافتراضية، فلا تكتب أي اسم منطقي، راجع الأسماء المنطقية كتعليقات.
• groupNames: جداول مجموعات الجداول المسمّاة، بالاسم دون مراعاة حالة الأحرف، مضمومةً إلى tableIds وtableNames. يُرفض الاسم الذي لا يطابق أي مجموعة بالرمز notFound. لا تضيف المجموعة التي لا تضم أي جدول شيئًا، والقراءة التي لا يتبقى فيها أي جدول على الإطلاق، كما حين تكون كل المجموعات المسمّاة فارغة ولا يُسمّى أي جدول، تُرفض بالرمز invalidArgs.

تنطبق الوسائط statements وheader وlogicalNameAsComment على DDL بعض الجداول أيضًا. وتعمل كالخيارين Statements وHeader ومفتاح التبديل Write logical names into empty comments في علامة تبويب مخطط SQL في المحرر، وإن كانت علامة التبويب تبدأ على القيمتين If not exists وCREATE + USE. ويبدأ مفتاح التبديل معطّلًا، كما تبدأ logicalNameAsComment. تُحاط الأسماء بنوع علامات الاقتباس الذي يحفظه الملف، أي النوع المقفل ما دام Bracket Type مقفلًا، راجع القفل.

المخططات الكبيرة

تعمل المخططات التي تضم مئات الجداول أو آلافها أيضًا. تُرجع القراءة 40,000 حرف على الأكثر، دون الحد الذي يضع عنده Claude Code نتيجة الأداة جانبًا في ملف.

• تُرجع erd_list صفحة من 100 عنصر افتراضيًا، الجداول أولًا، ثم مجموعات الجداول، والملاحظات، والمجالات، والمصطلحات، والكلمات، بإزاحة واحدة تسري عليها كلها، وتذكر أين تبدأ الصفحة التالية عبر nextOffset وnote. مرّر قيمة nextOffset تلك بوصفها offset، مع قيمة query نفسها.
• تعثر query على الجداول بكلمات في اسم جدول أو عمود أو اسمه المنطقي أو تعليقه، دون مراعاة حالة الأحرف. تأتي أولًا الجداول التي تحوي أسماؤها أو أسماؤها المنطقية عددًا أكبر من الكلمات. لا يسرد البحث أي مجموعات جداول أو ملاحظات أو صفوف قواميس.
• تسرد namesOnly أسماء الجداول وحدها، نحو 2,000 اسم قصير في استجابة واحدة.
• تأخذ erd_get وerd_read الوسيطة tableNames إلى جانب المعرّفات، وتأخذ erd_read الوسيطة groupNames، لذا فالوكيل الذي يُطلب منه استعلام SQL على مخطط كبير يقرأ DDL الجداول التي يحتاجها فقط.
• تأتي القواميس على أجزاء أيضًا: تتنقل erd_list صفحةً صفحة بين صفوفها بعد الجداول، وتعطي erd_get الصفوف كاملةً بحسب domainIds وtermIds وwordIds.
• تسرد erd_get المعرّفات والأسماء التي لا تشير إلى شيء ضمن missing، والمعرّفات التي لا تتسع لها استجابة واحدة ضمن notReturned، لطلبها مرة أخرى.
• تُرجع erd_list_checks النتائج صفحةً صفحة بالطريقة نفسها، راجع فحوصات القاموس.
• تُرفض القراءة الأكبر من أن تتسع لها استجابة واحدة بالرمز tooLarge، مع بيان كيفية تضييقها.

فحوصات القاموس

تسرد erd_list_checks فحوصات ورقة الفحوصات في المحرر، بالترتيب نفسه: فحوصات الكلمات أولًا، ثم فحوصات المصطلحات والمجالات، وكل قاموس بالترتيب الذي تعرضه ورقته، ثم كل جدول تليه أعمدته. وكما في الورقة، لا يجري الفحص إلا ما دام القاموس الذي يقرؤه يحمل صفًا. والمستند الذي لا تحمل قواميسه أي كلمة أو مصطلح أو مجال لا يُفحص على الإطلاق: تكون قيمة total هي 0، ويذكر note ذلك.

• level: error أو warning لذلك المستوى وحده؛ وكلاهما افتراضيًا.
• tableIds وtableNames: فحوصات تلك الجداول وأعمدتها فقط، والأسماء دون مراعاة حالة الأحرف، ما يستبعد صفوف القواميس نفسها. ويُرفض المعرّف أو الاسم الذي لا يشير إلى أي جدول بالرمز notFound.
• offset وlimit: صفحة من 100 فحص افتراضيًا، وتتوقف أيضًا حيث تمتلئ الاستجابة الواحدة. وما دامت هناك فحوصات أخرى تالية، يذكر nextOffset وnote أين تبدأ الصفحة التالية؛ مرّره بوصفه offset مع عوامل التصفية نفسها. وبعد إصلاح بعض الفحوصات، اسرد من جديد بدءًا من الإزاحة 0: فالفحص الذي أُصلح يغادر القائمة، لذا قد تتخطى إزاحة لاحقة فحوصات لم تُصلح بعد.

تحمل الاستجابة total، أي عدد الفحوصات التي تُبقيها عوامل التصفية؛ وcounts، أي عدد ما يخص كل رمز منها، مع استبعاد الرمز الذي ليس له أي فحص؛ والصفحة في checks. يعطي كل فحص level وcode الخاصين به، وkind وid لهدفه: table أو column أو word أو term أو domain. ويضيف فحص العمود tableId الخاص به واسم جدوله في table. name هو اسم الهدف، أي الاسم المادي للجدول أو العمود، مع logicalName الخاص به إن كان له اسم منطقي. وfield هو ما يقرؤه الفحص: name أو logicalName أو domainId. وtext هو ما عثر عليه هناك، وsuggestions، حيثما تقدّم القواميس أي اقتراح، هو ما يُستخدم بدلًا منه. لذا يمكن للوكيل إصلاح الفحص دون استدعاء erd_get:

{"level":"warning","code":"physicalNameMismatch","kind":"column","id":"8e1z0q4xk2m7cwd5tfb9h3ynp","tableId":"03h17be2plxpj5n59tqag7ogj","table":"users","name":"id","logicalName":"Member Number","field":"name","text":"id","suggestions":["MBR_NO"]}

code	level	Type في الورقة	ما يرصده
duplicateName	error	Duplicate name	اسم يتشاركه صفان من قاموس واحد. ويُسرد كل من الصفين.
unknownDomain	error	Unknown domain	عمود أو مصطلح مرتبط بمجال لم يعد المستند يسرده. وtext هو اسم ذلك المجال، أو معرّفه إن لم يكن اسمه معروفًا.
forbiddenWord	error	Forbidden word	كلمة تسردها كلمةٌ ما على أنها محظورة، في الاسم المنطقي لجدول أو عمود أو في اسم مصطلح. وsuggestions هي الكلمات القياسية.
unregisteredWord	warning	Unregistered word	نص لا تسرده أي كلمة، في المواضع نفسها.
synonymWord	warning	Synonym	مرادف مستخدم بدلًا من كلمة قياسية، في المواضع نفسها. وsuggestions هي الكلمات القياسية.
physicalNameMismatch	warning	Physical name mismatch	اسم مادي لجدول أو عمود يختلف عن الاسم الذي يعطيه مصطلح اسمه المنطقي. والاقتراح هو الاسم المادي للمصطلح، أو الاسم الذي تكوّنه كلماته ما دام المصطلح لا يحمل اسمًا ماديًا.
domainTypeMismatch	warning	Domain type mismatch	عمود لا يطابق نوع بياناته نوع المجال المرتبط به. وtext هو نوع العمود، والاقتراح نوع المجال.

كيفية قراءة كل فحص للاسم موضّحة في ما يرصده كل فحص.

أدوات التحرير

تأتي المعرّفات من erd_list وerd_get، أو من createdIds في الاستدعاء الذي أنشأ الكيان. يتكوّن المعرّف الجديد من 25 خانة من الأحرف الصغيرة والأرقام، مثل 03h17be2plxpj5n59tqag7ogj، بينما يحتفظ المعرّف الموجود في المستند مسبقًا بشكله، فلا تستنتج شيئًا من شكل المعرّف. x وy هما الحافتان اليسرى والعليا على لوحة الرسم، بالبكسل، واللون هو لون CSS سداسي عشري مثل #3b82f6، أو سلسلة نصية فارغة تزيل اللون.

الجداول

الأداة	الوسائط	ما تفعله
erd_add_table		تضيف جدولًا فارغًا في موضع شاغر وتُرجع معرّفه في createdIds.
erd_remove_table	tableId	تزيل جدولًا مع أعمدته وفهارسه وكل علاقة تتصل به.
erd_change_table_name	tableId, value	تعيد تسمية جدول. ويُعدّ الاسم عندئذ مكتوبًا يدويًا، لذا يتركه الاسم المنطقي اللاحق كما هو ما دام غير فارغ، راجع القواميس.
erd_change_table_comment	tableId, value	تضبط تعليق جدول. السلسلة النصية الفارغة تمسحه.
erd_set_table_logical_name	tableId, value	تضبط الاسم المنطقي لجدول. السلسلة النصية الفارغة تمسحه وتترك الاسم. وما دام اسم الجدول فارغًا أو مشتقًا، تشتقه القواميس من الاسم المنطقي، راجع القواميس. ولا يعطي المصطلحُ الجدولَ أي مجال.
erd_change_table_color	tableId, color	تضبط لون جدول.
erd_move_table	tableId, x, y	تنقل جدولًا إلى موضع على لوحة الرسم.
erd_move_tables	positions	تنقل عدة جداول في تعديل واحد، يتراجع عنه استدعاء erd_undo واحد. تحمل positions القيمة { tableId, x, y } لكل جدول، وكل جدول مرة واحدة على الأكثر.
erd_sort_tables		ترتّب كل الجداول في صفوف عبر لوحة الرسم، الأقل أعمدةً أولًا، كما ترتّبها erd_import_sql وerd_import_graphql وerd_import_dbml وerd_import_aml. تبقى جداول مجموعة الجداول معًا، ويُضبط مربع كل مجموعة ليحيط بها.

الأعمدة

الأداة	الوسائط	ما تفعله
erd_add_column	tableId	تضيف عمودًا فارغًا إلى جدول وتُرجع معرّفه في createdIds.
erd_remove_columns	tableId, columnIds	تزيل أعمدةً من جدول واحد، مع العلاقات وإدخالات الفهارس التي تستخدمها.
erd_change_column_name	tableId, columnId, value	تعيد تسمية عمود. ويُعدّ الاسم عندئذ مكتوبًا يدويًا، كما هو الحال مع اسم الجدول.
erd_change_column_data_type	tableId, columnId, value	تضبط نوع البيانات، مثل INT أو VARCHAR(255). ما دامت مزامنة نوع البيانات عبر العلاقات مفعّلة، يتبع التغيير العلاقات في الاتجاهين، كما يحدث في المحرر: يصل النوع serial إلى المفاتيح الخارجية بوصفه نوع العدد الصحيح الذي يخزنه، كما تنسخه erd_add_relationship، ويحتفظ مفتاح serial بنوعه حين يتغير أحد مفاتيحه الخارجية، فيتوقف التغيير عنده. تفعيل المزامنة أو تعطيلها متروك للمستخدم، وتُبلغ عنها erd_list بالاسم relationshipDataTypeSync. ويُفك ربط العمود المرتبط بمجال حين يُضبط على نوع غير نوع المجال، وكذلك كل عمود تصل إليه المزامنة ويختلف نوعه الجديد عن نوع مجاله، راجع فك الربط.
erd_change_column_default	tableId, columnId, value	تضبط القيمة الافتراضية، بوصفها نص SQL. السلسلة النصية الفارغة تمسحها.
erd_change_column_comment	tableId, columnId, value	تضبط التعليق. السلسلة النصية الفارغة تمسحه.
erd_set_column_logical_name	tableId, columnId, value	تضبط الاسم المنطقي لعمود. السلسلة النصية الفارغة تمسحه وتترك الاسم. وما دام اسم العمود فارغًا أو مشتقًا، تشتقه القواميس، ويُربط العمود بمجال المصطلح، فيأخذ نوع بيانات ذلك المجال، راجع القواميس.
erd_set_column_domain	tableId, columnId, domainId?, domainName?	تربط عمودًا بمجال، يُعطى بمعرّفه أو باسمه، بأحدهما فقط. ويأخذ العمود نوع بيانات المجال، الذي يتبع العلاقات ما دامت مزامنة نوع البيانات عبر العلاقات مفعّلة، مع فك الربط نفسه الذي تجريه erd_change_column_data_type. والقيمة null أو السلسلة النصية الفارغة في domainId، أو domainName الفارغة، تفك ربط العمود بالمجال وتُبقي نوعه.
erd_set_column_primary_key	tableId, columnId, value	القيمة true تجعل العمود جزءًا من المفتاح الأساسي، والقيمة false تُخرجه منه.
erd_set_column_unique	tableId, columnId, value	تضبط ما إذا كان العمود فريدًا.
erd_set_column_not_null	tableId, columnId, value	تضبط ما إذا كان العمود NOT NULL.
erd_set_column_auto_increment	tableId, columnId, value	تضبط ما إذا كان العمود يتزايد تلقائيًا.
erd_move_column	tableId, columnId, targetColumnId	تنقل عمودًا داخل جدوله إلى موضع عمود آخر.

العلاقات

تمثّل relationshipType التعددية عند طرف الجدول الفرعي: ZeroOne أو ZeroN أو OneOnly أو OneN. جدول البداية هو الجدول الأصل، أي الجانب المُشار إليه الذي يحمل المفتاح الأساسي، وجدول النهاية هو الجدول الفرعي. تمثّل onDelete وonUpdate إجراءي ON DELETE وON UPDATE للمفتاح الخارجي: none أو noAction أو cascade أو setNull أو setDefault أو restrict. لا تكتب القيمة none أي بند، فيُطبَّق السلوك الافتراضي لقاعدة البيانات، راجع ON DELETE وON UPDATE. الإجراء الذي لا يُذكر في erd_add_relationship أو erd_link_columns تكون قيمته none.

الأداة	الوسائط	ما تفعله
erd_add_relationship	startTableId, endTableId, relationshipType, onDelete?, onUpdate?	تربط جدولين بعلاقة. تنسخ المفتاح الأساسي للجدول الأصل إلى الجدول الفرعي بوصفه أعمدة مفتاح خارجي، وتنشئ عمود مفتاح أساسي أولًا إن لم يكن للجدول الأصل مفتاح أساسي. يُسمّى كل عمود مفتاح خارجي بالطريقة التي يسمّيه بها رسم علاقة في المحرر: المفتاح id في الجدول users يعطي users_id، ويحتفظ مفتاح مثل member_id باسمه، راجع أسماء أعمدة المفاتيح الخارجية. ينسخ كل منها نوع بيانات مفتاحه، إلا أن مفتاح serial يعطي نوع العدد الصحيح الذي يخزنه، مثل integer للنوع serial4، ويبقى النوع serial المجرد serial خارج PostgreSQL وMySQL وMariaDB، راجع العلاقات المُعرِّفة. ويأخذ كل منها أيضًا الاسم المنطقي لمفتاحه، ويرتبط بالمجال الذي يرتبط به مفتاحه ما لم يعطه مفتاح serial نوعًا آخر. تحمل createdIds عمود المفتاح الجديد ذاك إن أُنشئ، وأعمدة المفتاح الخارجي، ومعرّف العلاقة في الأخير.
erd_link_columns	startTableId, startColumnIds, endTableId, endColumnIds, relationshipType, onDelete?, onUpdate?	ترسم علاقة بين أعمدة موجودة بالفعل، فتقرن أعمدة البداية بأعمدة النهاية حسب موضعها. لا تعيد تسمية أي عمود ولا تغيّر أي نوع بيانات ولا تنسخ أي اسم منطقي أو مجال.
erd_remove_relationship	relationshipId	تزيل خط ربط علاقة. تبقى أعمدة المفتاح الخارجي الخاصة بها في الجدول.
erd_change_relationship_type	relationshipId, relationshipType	تغيّر تعددية علاقة.
erd_change_relationship_on_delete	relationshipId, onDelete	تضبط إجراء ON DELETE لعلاقة: ما يُحدثه حذف صف أصل في صفوفه الفرعية.
erd_change_relationship_on_update	relationshipId, onUpdate	تضبط إجراء ON UPDATE لعلاقة: ما يُحدثه تغيير مفتاح أصل في صفوفه الفرعية.

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

لا توجد أداة تغيّر أعمدة علاقة قائمة كما يفعل تعيين الأعمدة في المحرر. لتعيين علاقة على أعمدة أخرى، شغّل erd_remove_relationship، التي تُبقي أعمدة المفتاح الخارجي الخاصة بها في الجدول، وerd_link_columns مع الأعمدة المطلوبة، في دفعة erd_batch واحدة، يتراجع عنها استدعاء erd_undo واحد.

الفهارس

معرّف عمود الفهرس هو إدخال في قائمة أعمدة الفهرس التي تعطيها erd_get، وليس معرّف عمود الجدول.

الأداة	الوسائط	ما تفعله
erd_add_index	tableId	تضيف فهرسًا فارغًا إلى جدول وتُرجع معرّفه في createdIds.
erd_remove_index	indexId	تزيل فهرسًا.
erd_change_index_name	indexId, value	تعيد تسمية فهرس.
erd_set_index_unique	indexId, value	تضبط ما إذا كان الفهرس فريدًا.
erd_add_index_column	indexId, columnId	تضيف عمودًا من جدول الفهرس وتُرجع معرّف عمود الفهرس الجديد. العمود الموجود في الفهرس بالفعل يُترك كما هو.
erd_remove_index_column	indexId, indexColumnId	تزيل عمودًا واحدًا من فهرس.
erd_move_index_column	indexId, indexColumnId, targetIndexColumnId	تنقل عمودًا داخل فهرس إلى موضع عمود آخر من أعمدته.
erd_set_index_column_order	indexId, indexColumnId, orderType	تضبط ترتيب الفرز لعمود واحد في فهرس، ASC أو DESC.

الملاحظات

الأداة	الوسائط	ما تفعله
erd_add_memo		تضيف ملاحظة فارغة في موضع شاغر وتُرجع معرّفها في createdIds.
erd_remove_memo	memoId	تزيل ملاحظة.
erd_change_memo_value	memoId, value	تستبدل نص ملاحظة.
erd_change_memo_color	memoId, color	تضبط لون ملاحظة.
erd_move_memo	memoId, x, y	تنقل ملاحظة إلى موضع على لوحة الرسم.
erd_resize_memo	memoId, width, height	تغيّر حجم ملاحظة. يجب أن يكون العرض نحو 116 بكسل على الأقل والارتفاع 100 على الأقل. لا تُنشئ إدخال تراجع، لأن المحرر لا يسجّل تغيير حجم الملاحظة إلا من السحب.

أثناء إخفاء الملاحظات عبر View Option → Memos، تضيف erd_add_memo ملاحظةً رغم ذلك، وتبقى مخفيةً حتى تُظهَر الملاحظات من جديد. تسرد erd_list وerd_get الملاحظات المخفية أيضًا.

مجموعات الجداول

مجموعة الجداول مربع مسمّى يُرسم خلف جداولها، ويظهر لونها على المربع وعبر رؤوس جداولها، راجع مجموعات الجداول. ينتمي الجدول إلى مجموعة واحدة على الأكثر. لا تغيّر erd_move_table وerd_move_tables وerd_move_table_group أبدًا الجداول التي تضمها المجموعة، أينما وضعت جدولًا، بينما في المحرر ينضم الجدول إلى مجموعة أو يغادرها حيث يُفلَت، راجع إضافة الجداول وإزالتها. تضع erd_add_table_group وerd_set_table_group الجداول في مجموعة، وتترك erd_remove_table_group جداولها خارج أي مجموعة. تخزن المجموعة مستطيلًا لا يقل عرضه عن 160 بكسل وارتفاعه عن 100، بما في ذلك شريط العنوان، ويرسم المحرر المربع موسّعًا ليتسع لكل جدول من جداولها.

الأداة	الوسائط	ما تفعله
erd_add_table_group	name, color?, x?, y?, width?, height?, tableIds?	تضيف مجموعة وتُرجع معرّفها في createdIds. مرّر إما tableIds وإما مستطيلًا، أي x وy وwidth وheight معًا. مع tableIds، يغادر كل جدول أي مجموعة كان فيها، ويُضبط المستطيل ليحيط بها كما يضبطه تجميع الجداول المحددة. يضم المستطيل كل جدول لا ينتمي إلى أي مجموعة ويقع مركزه داخله، كما يفعل رسم مجموعة. إذا كانت name فارغة، تبقى المجموعة بلا اسم. استدعاء erd_undo واحد يزيل المجموعة ويعيد كل جدول إلى المجموعة التي كان فيها.
erd_remove_table_group	groupId	تزيل مجموعة. تبقى جداولها في أماكنها، خارج أي مجموعة.
erd_change_table_group_name	groupId, value	تعيد تسمية مجموعة. السلسلة النصية الفارغة تتركها بلا اسم.
erd_change_table_group_color	groupId, color	تضبط لون مجموعة.
erd_move_table_group	groupId, x, y	تنقل مجموعة بحيث يبدأ مستطيلها عند تلك النقطة، مع جداولها بالمقدار نفسه، كما يفعل سحب شريط عنوانها. النقل الذي يقل عن 20 بكسلًا، بجمع الإزاحتين الأفقية والرأسية، لا يُنشئ إدخال تراجع. منذ الخادم 1.2.0 يصل النقل إلى المحرر بوصفه النقاط التي تنتهي إليها المجموعة وجداولها، لذا مع إضافة VS Code بالإصدار 4.3.0 أو أحدث أو مكوّن Obsidian أو JetBrains الإضافي بالإصدار 1.3.0 أو أحدث، ينتهي نقل للمجموعة أو لأحد جداولها يتم هناك في اللحظة نفسها إلى أحد الموضعين، لا إلى مجموعهما، راجع التعديلات التي تتم في اللحظة نفسها.
erd_resize_table_group	groupId, x?, y?, width, height	تضبط مستطيل مجموعة، وتبقى جداولها في أماكنها. إغفال x وy يُبقي زاويتها. يُرفض المستطيل الذي لا يتسع لجداول المجموعة مع هوامشها الداخلية، مع رسالة تحدد المربع الذي يجب أن يتسع له.
erd_set_table_group	tableIds, groupId	تضع جداول في مجموعة، فيغادر كل منها أي مجموعة كان فيها. القيمة null أو السلسلة النصية الفارغة في groupId تُخرج الجداول من كل المجموعات.

أثناء إخفاء المجموعات عبر View Option → Table Groups، تضيف هذه الأدوات المجموعات وتغيّرها رغم ذلك، وتبقى المجموعات مخفيةً حتى تُظهَر، راجع إخفاء المجموعات. تُبقي erd_sort_tables جداول كل مجموعة معًا، وتجلب erd_import_dbml وerd_import_json المجموعات — راجع الاستيراد — وتكتب erd_read نص DDL لمجموعات مختارة باستخدام groupNames. يُسقط أي إصدار من ERD Editor يسبق ظهور مجموعات الجداول مجموعاتِ الملف عند حفظه، كما تفعل إضافة VS Code قبل الإصدار 4.0.0 ومكوّنا Obsidian وJetBrains الإضافيان قبل الإصدار 1.0.0، راجع التحديث.

القواميس

تحرّر هذه الأدوات القواميس الثلاثة في علامة تبويب القاموس في المحرر، والتي يشتق منها الاسم المنطقي للجدول أو العمود اسمه المادي:

• الكلمة كلمة قياسية تتكوّن منها الأسماء المنطقية، مع الاختصار الذي تكتبه في الاسم المادي، مثل Member وMBR.
• المصطلح اسم منطقي كامل مع الاسم المادي الذي يعطيه، ومع المجال الذي يربط به العمودَ في حالة العمود، مثل Member Number مع MBR_NO وIdentifier.
• المجال نوع بيانات مسمّى تُربط به الأعمدة، مثل Identifier للنوع INT.

الأداة	الوسائط	ما تفعله
erd_add_word	name, abbreviation, englishName?, description?, synonyms?, forbiddenWords?	تضيف كلمة في نهاية قاموس الكلمات وتُرجع معرّفها في createdIds. تُفصل قيم synonyms وforbiddenWords بفواصل: وهي تهجئات أخرى للكلمة، وكلمات يجب ألا تُستخدم مكانها.
erd_update_word	wordId, name?, abbreviation?, englishName?, description?, synonyms?, forbiddenWords?	تغيّر الحقول المُمرَّرة وتترك البقية.
erd_remove_word	wordId	تزيل كلمة.
erd_add_term	name, physicalName?, domainId?, domainName?, description?, synonyms?	تضيف مصطلحًا في نهاية قاموس المصطلحات وتُرجع معرّفه في createdIds. ومن دون physicalName، تكوّن الكلمات اسمًا ماديًا إن استطاعت، مثل MBR_NO للمصطلح Member Number.
erd_update_term	termId, name?, physicalName?, domainId?, domainName?, description?, synonyms?	تغيّر الحقول المُمرَّرة وتترك البقية. والقيمة name المُمرَّرة ما دام المصطلح لا يحمل اسمًا ماديًا، أو مع physicalName فارغة، تكتب أيضًا الاسم المادي الذي تكوّنه كلماته، إن كوّنت اسمًا.
erd_remove_term	termId	تزيل مصطلحًا.
erd_add_domain	name, category?, dataType, description?	تضيف مجالًا في نهاية قاموس المجالات وتُرجع معرّفه في createdIds. تُصنّف category المجالات في مجموعات، مثل Number أو Text.
erd_update_domain	domainId, name?, category?, dataType?, description?	تغيّر الحقول المُمرَّرة وتترك البقية. ويصل dataType الجديد إلى كل عمود مرتبط بالمجال، ويتبع العلاقات ما دامت مزامنة نوع البيانات عبر العلاقات مفعّلة، مع فك الربط نفسه الذي تجريه erd_change_column_data_type.
erd_remove_domain	domainId	تزيل مجالًا. وتحتفظ الأعمدة المرتبطة به بنوع بياناتها، ولا تُظهر هي والمصطلحات المرتبطة به أي مجال: إذ تُقرأ domainId الخاصة بها سلسلةً نصية فارغة. وتعيد erd_undo هذه الروابط، ويستبعدها الحفظ من الملف.
erd_derive_physical_names	scope, tableId?, columnId?	تشتق الأسماء المادية من جديد من الأسماء المنطقية، كما يفعل الأمر إعادة اشتقاق الأسماء المادية في المحرر، لعمود واحد أو جدول واحد أو للمستند كله.

• يحمل القاموس كل اسم مرة واحدة، لذا يُرفض بالرمز invalidArgs الاسمُ الذي يحمله صف آخر في القاموس نفسه. وتُقارن الأسماء بعد حذف المسافات من طرفيها، مع مراعاة حالة الأحرف، لذا فإن Member وmember اسمان مختلفان.
• يحدد التحديث الصف بمعرّفه ويمرّر حقلًا واحدًا على الأقل. والقيم التي يحملها الصف بالفعل لا تغيّر شيئًا ولا تُنشئ إدخال تراجع؛ أما الإضافة أو الإزالة فتُنشئ إدخالًا دائمًا.
• يُعطى مجال المصطلح إما عبر domainId، مع null أو سلسلة نصية فارغة لعدم وجود مجال، وإما عبر domainName، مع سلسلة نصية فارغة لعدم وجود مجال. وتأخذ domainName أول مجال بذلك الاسم بترتيب القاموس، وتُقارن كما تُقارن الأسماء. ويُرفض تمرير الاثنين معًا، أو domainName لا يحمله أي مجال. وتأخذ erd_set_column_domain المجال بالطريقة نفسها.
• تغيير كلمة أو مصطلح أو إزالتهما لا يعيد تسمية أي شيء ولا يفك أي ربط بمجال: تبقى الأسماء والمجالات التي أعطاها كما هي. وتشتق erd_derive_physical_names الأسماء من جديد وتربط بالمجال الذي يعطيه المصطلح الآن، لكن العمود الذي لا يطابقه أي مصطلح الآن، أو الذي لا يعطي مصطلحه أي مجال، يحتفظ بالمجال المرتبط به. وتفك erd_set_column_domain مع domainId فارغة ربطه بالمجال.
• لا توجد أداة تستورد قاموسًا أو تصدّره بصيغة CSV، أو تفرز قاموسًا، أو تُدرج صفوفًا في موضع معين، كما تفعل علامة تبويب القاموس.

تسرد erd_list الصفوف، وتعطي erd_get كل حقل، ويحملها التنسيق snapshot في erd_read كلها، وتسرد erd_list_checks ما ترصده القواميس من أخطاء، راجع قراءة مستند.

تشتق erd_set_table_logical_name وerd_set_column_logical_name اسمًا ماديًا كما يفعل المحرر عند كتابة اسم منطقي، راجع اشتقاق الأسماء المادية:

• لا يُشتق الاسم إلا ما دام فارغًا أو كان هو نفسه مشتقًا، وهو ما تُظهره القراءات بالقيمة nameDerived: true. ويبقى الاسم غير الفارغ المكتوب يدويًا، ولا يُكتب إلا الاسم المنطقي. وكل الأسماء التي تكتبها erd_change_table_name وerd_change_column_name وعمليات استيراد SQL وGraphQL وDBML وAML، وأسماء أعمدة المفتاح الخارجي التي تسمّيها erd_add_relationship، تُعدّ مكتوبةً يدويًا. والاسم الذي أُعيدت تسميته إلى سلسلة نصية فارغة يُشتق من جديد بالاسم المنطقي التالي.
• يأتي أولًا المصطلح الذي يكون اسمه هو الاسم المنطقي، بمقارنة كمقارنة أسماء القاموس. ويعطي اسمه المادي، أو الاسم الذي تكوّنه كلماته ما دام لا يحمل اسمًا ماديًا. وفي حالة العمود، يُربط العمود أيضًا بمجال المصطلح، حتى عندما لا يُشتق أي اسم، ويأخذ العمود نوع بيانات المجال، متبعًا العلاقات ما دامت مزامنة نوع البيانات عبر العلاقات مفعّلة.
• وعند عدم وجود مثل هذا المصطلح، تكوّن الكلمات الاسم، باختصاراتها موصولةً بشرطات سفلية: Member Number يعطي MBR_NO. والأمر كله أو لا شيء: فالمرادف، أو الكلمة المحظورة، أو النص الذي لا تسرده أي كلمة، أو الكلمة التي لا اختصار لها، لا يكوّن شيئًا، ويبقى الاسم كما كان. ولا تربط الكلمات العمود بأي مجال، ولا يربطه كذلك المصطلح الذي لا مجال له، لذا يحتفظ العمود بالمجال المرتبط به.
• العمود الذي يحمل اسمَه المشتق عمودٌ آخر في جدوله بالفعل، دون مراعاة حالة الأحرف، يحتفظ باسمه وnameDerived الخاص به ومجاله.
• مسح الاسم المنطقي يترك الاسم المادي كما هو. والاستدعاء الذي يكون اسمه المنطقي، وما يشتقه، في مكانهما بالفعل لا يغيّر شيئًا ولا يُنشئ إدخال تراجع.

تأخذ erd_derive_physical_names الوسيطة scope: column، مع tableId وcolumnId، لذلك العمود؛ أو table، مع tableId، لاسم الجدول وكل عمود فيه؛ أو document، دون أي معرّف، لكل جدول وأعمدته. ويُرفض النطاق الذي ينقصه معرّف يحتاجه، أو الذي يُعطى معرّفًا لا يأخذه. يعود كل اسم مشمول له اسم منطقي إلى القواميس، بما في ذلك الاسم المكتوب يدويًا، ويأخذ ما تعطيه الآن: الاسم المادي للمصطلح، ومجاله ونوعه في حالة العمود، وإلا فما تكوّنه الكلمات، وهو ما يترك مجال العمود كما هو. والاسم المنطقي الذي لا يشتق شيئًا يترك الاسم كما هو، وتصبح قيمة nameDerived الآن true. ويبقى الاسم الذي لا اسم منطقيًا له كما هو، وكذلك العمود الذي يحمل اسمَه الجديد عمودٌ آخر في جدوله، مثل مفتاح خارجي ثانٍ إلى الجدول نفسه، والذي يحتفظ أيضًا بقيمة nameDerived الخاصة به. ويتراجع استدعاء erd_undo واحد عن الاستدعاء كله. أسماء المخطط المستورد مكتوبة يدويًا، لذا سمِّه من القواميس بضبط الأسماء المنطقية ثم استدعاء erd_derive_physical_names. ويعطي ذلك الاستدعاء الاسم المادي الخاص بالمصطلح، الذي لا يُعاد تكوينه عند تغيير كلمات المصطلح. لذا بعد تغيير كلمات مصطلح، حدّث المصطلح أولًا: مرّر name الخاص به مع physicalName فارغة لتكوّنه الكلمات من جديد، أو مرّر physicalName الجديد.

يُسقط أي إصدار من ERD Editor يسبق علامة تبويب القاموس الأسماءَ المنطقية للملف وروابط المجالات وصفوف القواميس عند حفظه، كما تفعل إضافة VS Code قبل الإصدار 4.2.0 ومكوّنا Obsidian وJetBrains الإضافيان قبل الإصدار 1.2.0. ومن بينها، لا تزال الإضافة بالإصدار 4.0.0 أو 4.1.0 والمكوّنان الإضافيان بالإصدار 1.0.0 أو 1.1.0 تحرر في الوضع المباشر مع الخادم، لكنها لا تُظهر الأسماء المنطقية وروابط المجالات وصفوف القواميس التي يكتبها الوكيل ولا تحتفظ بها، راجع التحديث.

الإعدادات

يضبط الوكيل إعدادات المخطط نفسه: قاعدة البيانات واسمها وسكربتات مخطط SQL. أما كل إعداد آخر يخزنه المستند فضبطه متروك للمستخدم في المحرر: عرض الأسماء، ومفاتيح تبديل خيارات العرض، وخيارات علامة تبويب الإعدادات، ولغة منشئ التعليمات البرمجية وأنماط التسمية فيه، ونوع علامات الاقتباس، والأقفال. لا تغيّرها أي أداة، باستثناء أدوات الاستيراد في الوضع replace: تجلب erd_import_json إعدادات المستند الذي تحمّله وأقفاله، وتعيد الأدوات الأربع الأخرى العرض إلى بداية لوحة الرسم، راجع الاستيراد. أزال الإصدار 1.0.0 من الخادم الأدوات التي كانت تضبطها: erd_set_language وerd_set_table_name_case وerd_set_column_name_case وerd_set_bracket_type وerd_set_relationship_data_type_sync وerd_set_relationship_optimization وerd_set_column_order وerd_set_max_width_comment وerd_set_ignore_save_settings وerd_set_show.

تُبلغ erd_list والتنسيق snapshot في erd_read عن الإعدادات كما يحفظها الملف، وتحمل lockSettings علامة واحدة لكل قفل: viewport وcanvasType وlanguage وtableNameCase وcolumnNameCase وbracketType وunlockNameViewMode. وتُقرأ العلامة الأخيرة بالعكس: تكون false ما دام القفل Name View مفعّلًا، كما هو الحال في المستند الجديد وفي الملف المحفوظ قبل وجود ذلك القفل، وtrue بمجرد أن يعطّل المستخدم القفل. يُبلَّغ عن اللغة أو نمط التسمية أو نوع علامات الاقتباس المقفل بقيمته المقفلة، وهي القيمة التي يحتفظ بها الملف ويُفتح عليها كل محرر، أيًّا كان ما تعرضه شاشة المحرر. ولا يُبلَّغ عن موضع العرض وعلامة التبويب وعرض الأسماء. ويقرأ الوكيل الأسماء المنطقية ويكتبها أيًّا كانت حالة عرض الأسماء.

تُنشئ erd_set_ddl_script إدخال تراجع. أما erd_set_database وerd_set_database_name فلا تُنشئان أي إدخال، لذا لا تستطيع erd_undo التراجع عنهما.

الأداة	الوسائط	ما تفعله
erd_set_database	value	تضبط قاعدة البيانات: MariaDB أو MSSQL أو MySQL أو Oracle أو PostgreSQL أو SQLite أو Databricks أو Snowflake. ويحدد ذلك أنواع بيانات قاعدة البيانات، ونص DDL الذي تكتبه erd_read حين لا تُعطى vendor.
erd_set_database_name	value	تضبط اسم قاعدة البيانات، الذي تذكره الترويستان use وcreateAndUse في erd_read.
erd_set_ddl_script	position, sql	تضبط أحد السكربتين اللذين يُكتبان حول الجداول، راجع السكربتات قبل الجداول وبعدها. قيمة position إما before، أي السكربت المكتوب قبل الجداول، مثل CREATE EXTENSION أو CREATE SCHEMA، وإما after، أي السكربت المكتوب بعدها، مثل GRANT أو CREATE VIEW. تستبدل sql السكربت كله، بحد أقصى 10,000 حرف، وتزيله السلسلة النصية الفارغة. اقرأ السكربت الحالي أولًا باستخدام التنسيق scripts في erd_read.

يدخل السكربت كما هو في DDL كل قاعدة بيانات، لذا اكتبه لقاعدة بيانات المستند. في MSSQL، يُضاف سطر GO بعد السكربت الذي لا يكون سطره الأخير GO. يُسقط أي إصدار من ERD Editor يسبق ظهور هذه السكربتات سكربتاتِ الملف عند حفظه، كما تفعل إضافة VS Code قبل الإصدار 4.0.0 ومكوّنا Obsidian وJetBrains الإضافيان قبل الإصدار 1.0.0، راجع التحديث.

الاستيراد

تقرأ هذه الأدوات المخطط بالطريقة التي تقرؤه بها قائمة الاستيراد في المحرر، راجع استيراد الملفات وتصديرها. تأخذ كل منها النص في value، وmode: replace، وهي القيمة الافتراضية، أو append.

الأداة	الوسائط	ما تفعله
erd_import_sql	value, mode?	تحمّل DDL بلغة SQL، كعبارات CREATE TABLE وما شابهها.
erd_import_graphql	value, mode?	تحمّل SDL بلغة GraphQL.
erd_import_dbml	value, mode?	تحمّل DBML. يصبح كل TableGroup مجموعةَ جداول تضم الجداول التي يسمّيها، راجع DBML.
erd_import_aml	value, mode?	تحمّل AML.
erd_import_json	value, mode?	تحمّل مستند JSON من erd-editor، مثل ملف .erd.json آخر.

يستبدل الوضع replace المستند، وتستعيد erd_undo المستند الذي كان قبله:

• تستبدل erd_import_sql وerd_import_graphql وerd_import_dbml وerd_import_aml كل جدول وعلاقة وفهرس وملاحظة ومجموعة جداول. وتُبقي إعدادات المستند، بما فيها أقفاله، باستثناء العرض الذي يعود إلى بداية لوحة الرسم بمستوى تكبير 100%، وتُبقي قواميس الكلمات والمصطلحات والمجالات فيه. والجداول التي تجلبها ليس لها أسماء منطقية ولا ترتبط بأي مجال.
• تستبدل erd_import_json المستند كله، بما في ذلك إعداداته وقواميسه: تحل إعدادات JSON وأقفاله وكلماته ومصطلحاته ومجالاته محل ما في هذا المستند، وملف JSON الذي لا يسجّل أي أقفال يفعّل كل الأقفال ويضع العرض عند بداية لوحة الرسم. ويحتفظ كل مشاهد بعرض الأسماء الخاص به، ما لم يكن القفل Name View معطّلًا في JSON، فيجلب عندئذ عرض الأسماء المحفوظ فيه. للإبقاء على إعدادات هذا المستند، ابدأ من النص الذي يعطيه التنسيق json في erd_read. النص الفارغ يعطي مستندًا جديدًا، مثل الذي تنشئه erd_open_document مع create.

في محرر بإضافة VS Code بالإصدار 4.3.0 أو أحدث أو بمكوّن Obsidian أو JetBrains الإضافي بالإصدار 1.3.0 أو أحدث، ينهي replace وما يتبعه من erd_undo أو erd_redo رسم علاقة تجريها أيضًا، راجع الوضع المباشر.

يضيف الوضع append ما يُستورد إلى المستند، كما يفعل استيراد وإضافة في المحرر، ويزيل استدعاء erd_undo واحد الإضافة كلها:

• يدخل ما يحتويه النص بوصفه كيانات جديدة بمعرّفات جديدة، في كتلة أسفل كل ما يحويه المستند، بما في ذلك الملاحظات المخفية ومجموعات الجداول، ومحاذيةً لحافته اليسرى. يبقى كل جدول وإعداد موجود بالفعل، بما في ذلك الجدول الذي يحمل الاسم نفسه: لا يُدمج شيء بالاسم.
• لا تأتي العلاقات والفهارس إلا بين الجداول التي يجلبها الاستيراد، لذا يُسقَط المفتاح الخارجي المشير إلى جدول لا يصرّح به النص.
• تضيف erd_import_sql وerd_import_graphql وerd_import_aml الجداول مع علاقاتها وفهارسها، وتضيف erd_import_dbml مجموعات الجداول أيضًا. تضيف erd_import_json الجداول والعلاقات والفهارس والملاحظات ومجموعات الجداول، ولا تضيف إعدادات JSON أبدًا، وترفض النص الفارغ. وتجلب جداول JSON وأعمدته أسماءها المنطقية، لكن لا يرتبط أي عمود بمجال، ولا يدخل شيء من كلمات JSON أو مصطلحاته أو مجالاته.

يحتفظ مستند JSON بترتيبه الخاص، بما في ذلك مجموعات جداوله: حيث يضع جداوله مع replace، وداخل الكتلة المضافة مع append. تُرتَّب جداول SQL وGraphQL وDBML وAML في صفوف، الأقل أعمدةً أولًا مع إبقاء جداول كل مجموعة معًا، كما ترتّبها erd_sort_tables، ولا تُرتَّب أبدًا حسب Flow كما يرتّبها الاستيراد في المحرر نفسه حين يستطيع. ترفض هذه الأدوات الأربع النص الفارغ في كلا الوضعين.

erd_batch

تشغّل erd_batch عدة أدوات تحرير بالترتيب بوصفها تعديلًا واحدًا، كلها أو لا شيء.

• تحمل operations حتى 100 إدخال، كل منها { tool, as?, args? }، حيث tool أداة تحرير وargs هي وسائط الأداة دون path. وتُرفض أداة القراءة، مثل erd_list_checks.
• تُجرَّب العمليات على نسخة من المستند أولًا. تُذكر العملية المرفوضة باسمها، مثل operations[1] erd_remove_table: …، ولا يُطبَّق شيء.
• يتراجع استدعاء erd_undo واحد عن الدفعة كلها، باستثناء العمليات التي لا يستطيع التراجع عنها، والتي يذكرها undoNote في النتيجة: عمليات أداة لا تُنشئ إدخال تراجع، مثل erd_set_database، والعمليات التي غيّرت المستند دون إنشاء إدخال، مثل نقل قصير عبر erd_move_table_group. تتخطى erd_undo الدفعة التي لم تُنشئ أي إدخال تراجع على الإطلاق. يَعُدّ historyEntries في النتيجة إدخالات سجل المحرر داخل الدفعة، لا استدعاءات erd_undo.
• في الجلسة المباشرة، يقبل المحرر الدفعة كلها أو لا يقبل منها شيئًا.

لا يستطيع الوكيل معرفة المعرّفات التي تنشئها الدفعة قبل استدعائها، لذا تتيح العملية المسمّاة باستخدام as لعملية لاحقة الإشارة إليها: $name أو $name.0 لأول معرّف أنشأته، و$name.1 لثانيها، و$name.last لآخرها. يتكوّن الاسم من أحرف ASCII وأرقام وشرطات سفلية، ولا يبدأ برقم، ولا يسمّي إلا عملية واحدة. لا تُحَل الإشارة إلا حيث تأخذ الوسيطة معرّف كيان، بما في ذلك wordId وtermId وdomainId، لذا يبقى الاسم أو التعليق الذي نصه $x نصًا عاديًا. وقيمة domainName نص أيضًا، لكنها تُقرأ عند تشغيل عمليتها، لذا يمكنها تسمية مجال أضافته عملية سابقة في الدفعة.

جدول بأعمدته وعلاقة، في استدعاء واحد:

{
  "path": "shop.erd.json",
  "operations": [
    { "tool": "erd_add_table", "as": "users" },
    { "tool": "erd_change_table_name", "args": { "tableId": "$users", "value": "users" } },
    { "tool": "erd_add_column", "as": "uid", "args": { "tableId": "$users" } },
    { "tool": "erd_change_column_name", "args": { "tableId": "$users", "columnId": "$uid", "value": "id" } },
    { "tool": "erd_change_column_data_type", "args": { "tableId": "$users", "columnId": "$uid", "value": "BIGINT" } },
    { "tool": "erd_set_column_primary_key", "args": { "tableId": "$users", "columnId": "$uid", "value": true } },
    { "tool": "erd_add_table", "as": "orders" },
    { "tool": "erd_change_table_name", "args": { "tableId": "$orders", "value": "orders" } },
    { "tool": "erd_add_relationship", "args": { "startTableId": "$users", "endTableId": "$orders", "relationshipType": "ZeroN", "onDelete": "cascade" } }
  ]
}

يُسمّى users ومفتاحه id قبل العلاقة، لذا يكون عمود المفتاح الخارجي الذي تضيفه العلاقة إلى orders هو users_id.

كلمات ومجال ومصطلح، ثم جدول يُسمّى منها عبر أسمائه المنطقية:

{
  "path": "shop.erd.json",
  "operations": [
    { "tool": "erd_add_word", "args": { "name": "Member", "abbreviation": "MBR" } },
    { "tool": "erd_add_word", "args": { "name": "Number", "abbreviation": "NO" } },
    { "tool": "erd_add_word", "args": { "name": "Name", "abbreviation": "NM" } },
    { "tool": "erd_add_domain", "as": "identifier", "args": { "name": "Identifier", "dataType": "INT" } },
    { "tool": "erd_add_term", "args": { "name": "Member Number", "domainId": "$identifier" } },
    { "tool": "erd_add_table", "as": "members" },
    { "tool": "erd_set_table_logical_name", "args": { "tableId": "$members", "value": "Member" } },
    { "tool": "erd_add_column", "as": "no", "args": { "tableId": "$members" } },
    { "tool": "erd_set_column_logical_name", "args": { "tableId": "$members", "columnId": "$no", "value": "Member Number" } },
    { "tool": "erd_add_column", "as": "nm", "args": { "tableId": "$members" } },
    { "tool": "erd_set_column_logical_name", "args": { "tableId": "$members", "columnId": "$nm", "value": "Member Name" } }
  ]
}

يكوّن المصطلح MBR_NO من كلماته، ويُسمّى الجدول MBR. ويأخذ العمود Member Number الاسم MBR_NO من المصطلح ومجاله، فيُربط بالمجال Identifier ويكون نوعه INT، أما Member Name، الذي لا يحمله أي مصطلح، فيُكوَّن اسمه MBR_NM.

النتائج

يُرجع التعديل سطرًا واحدًا من JSON:

{"tool":"erd_add_table","mode":"live","createdIds":["03h17be2plxpj5n59tqag7ogj"],"batches":1,"historyEntries":1}

الحقل	المعنى
mode	live أو headless، راجع الوضع المباشر والوضع بدون واجهة.
saved	true في نتيجة كل تعديل وerd_batch وerd_undo وerd_redo في الوضع بدون واجهة: إذ يحمل الملف التغيير بحلول الوقت الذي يُجيب فيه الاستدعاء، فلا يبقى شيء لحفظه. ولا تحمل النتيجة في الوضع المباشر saved، لأن المحرر هو الذي يحتفظ بالتغيير، راجع الحفظ.
createdIds	معرّفات ما أنشأه الاستدعاء، بالترتيب.
batches, historyEntries	عدد دفعات التغيير التي أرسلها الاستدعاء وعدد إدخالات سجل المحرر التي أنشأها.
undoable, undoNote	تكون قيمة undoable هي false حين ستتخطى erd_undo الاستدعاء، ويذكر undoNote السبب: الأداة لا تُنشئ إدخال تراجع، أو الاستدعاء غيّر المستند دون إنشاء إدخال، كما يفعل نقل عبر erd_move_table_group بأقل من 20 بكسلًا، أو المستند كان يحمل القيمة بالفعل. تحمل نتيجة erd_batch دائمًا undoNote. حين تُنشئ الدفعة إدخال تراجع، تذكر الملاحظة أن استدعاء erd_undo واحدًا يتراجع عن الدفعة وتسمّي أي عملية يتركها كما هي؛ وحين لا تُنشئ أي إدخال، تحمل النتيجة undoable: false وتذكر الملاحظة أن erd_undo تتخطاها.
mismatch	يظهر حين يُنشئ الاستدعاء عددًا من الدفعات أو إدخالات السجل يختلف عما تعلنه الأداة.
notes	يظهر حين يتغير شيء في الجلسة، مثل محرر أُغلق أو توقف عن خدمة المستند، أو ملف تغيّر على القرص.

الرفض نتيجة خطأ تحمل رمزًا ورسالةً تذكر ما يجب فعله:

{"error":{"code":"notFound","message":"tableId nope names no live table; read the document for current ids"}}

code	السبب
notFound	معرّف لا يشير إلى أي شيء موجود حاليًا، أو الملف غير موجود.
invalidArgs	وسيطة مفقودة أو ذات قيمة خاطئة.
invalidPath	المسار ليس مستند ERD. على Windows، يشمل أيضًا مسارًا فيه اسم لا يخزنه Windows كما كُتب، أو مسارًا يصل إلى مستند يحتفظ به محرر تحت مسار آخر، تذكره الرسالة.
invalidDocument	الملف ليس مستندًا يستطيع المحرر قراءته.
tooLarge	القراءة لا تتسع لها استجابة واحدة.
blocked	يحتفظ بالمستند محرر محوره معطّل. تذكر الرسالة كيفية تفعيله: في VS Code، ثق بمساحة العمل وفعّل dineug.erd-editor.agentHub.enabled، أو أعد تحميل النافذة؛ في Obsidian، فعّل Coding agents، أو أعد تحميل Obsidian؛ في بيئة تطوير JetBrains، فعّل Coding agents، أو أعد تشغيل بيئة التطوير إن كان مفعّلًا.
hubDisabled	لا تحتفظ بيئة تطوير JetBrains بالمستند إلا في مشروع لا تثق به. تظل القراءة ممكنة؛ ثق بالمشروع ليتمكن الوكيل من التحرير.
conflict	تغيّر الملف على القرص أثناء الاستدعاء. لم يُكتب شيء.
hubAppeared, hubGone	بدأ محرر يخدم مستندًا كان الوكيل يحرره على القرص، أو أن المحرر الذي كان يخدمه لا يزال يعمل لكن ملف القفل الخاص به واتصاله قد اختفيا. لم يُكتب شيء.
notSaved	لم تتمكن erd_save من حفظ مستند المحرر.
readonly	يحتفظ المحرر بالمستند للقراءة فقط، مثل ملف لا يستطيع الكتابة فيه أو لا يستطيع قراءته بوصفه مخططًا. في غياب المحرر، يكون الملف نفسه للقراءة فقط، مثل ملف Perforce أو TFVC لم يُسحب للتحرير. لم يُكتب شيء.
protocolMismatch	تستخدم إضافة ERD Editor أو مكوّنه الإضافي في المحرر والخادم إصدارين مختلفين من البروتوكول، مثل الخادم بالإصدار 1.0.0 أو أحدث مع إضافة VS Code بالإصدار 3.x. تُرفض القراءات أيضًا، وتذكر الرسالة الطرف الذي يجب تحديثه، راجع التحديث.
hubUnreachable, timeout, disconnected	لم يقبل محور المحرر الاتصال، أو لم يُجب خلال 30 ثانية، أو قطع الاتصال أثناء الاستدعاء. على Windows، يعني الرمز hubUnreachable أيضًا أن Windows منع الوكيل من الوصول إلى المحور: يعمل المحرر بصلاحيات أعلى من صلاحيات الوكيل، كأن يكون قد شُغّل بصفة مسؤول ولم يُشغَّل الوكيل كذلك، أو يعمل الوكيل في بيئة معزولة.

الرموز الأخرى أندر، وكل رفض يحمل رسالة تذكر ما حدث.

ترفض أدوات التحرير وerd_batch وأدوات القراءة الأربع أي وسيطة لا تعلنها، أو وسيطة من نوع خاطئ، بخطأ الوسائط غير الصالحة في JSON-RPC (-32602) قبل المساس بالمستند، لذا لا تُسقَط أبدًا وسيطة مكتوبة خطأً دون تنبيه. تتجاهل أدوات الجلسة الخمس الوسائط التي لا تعرفها.