المَعلمات (Parameters) هي أداة قوية يمكن استخدامها في استعلامات مستكشف البيانات (Data Explorer) على Discourse. تتيح المعلمات استعلامات أكثر ديناميكية وقابلية للتخصيص، وبدلاً من ترميز القيم بشكل ثابت في استعلاماتك، يمكنك تعريف متغيرات تطلب إدخالاً عند تشغيل الاستعلام.
تعريف مُعَلَّمة (Declaring a Parameter)
لتعريف مُعَلَّمة، يمكنك استخدام الصيغة التالية:
-- [params]
-- int :parameter_name = 10
سيبدأ قسم المُعَلَّمة في الاستعلام دائمًا بـ -- [params]، متبوعًا بكل نوع من أنواع المُعَلَّمات في سطر جديد، حيث يتم استبدال parameter_name بالاسم الذي تختاره للمُعَلَّمة.
سيؤدي هذا إلى إنشاء حقل يمكنك من خلاله إدخال قيم مختلفة في كل مرة تقوم فيها بتشغيل الاستعلام.
أنواع المُعَلَّمات (Types of Parameters)
عند تعريف المُعَلَّمات في استعلامات مستكشف البيانات (Data Explorer)، يمكنك تحديد أنواع إدخال مختلفة. فيما يلي أنواع المُعَلَّمات المتاحة وأوصافها:
المُعَلَّمات الرقمية (Numeric Parameters)
int: يعرض إدخالًا رقميًا، ويصبح قيمة رقمية. يقتصرintعلى الأرقام ذات 32 بت.bigint: مشابه لـint، ولكنه يمكن أن يكون أكبر.double: يسمح بالقيم العشرية.
سيتم التحقق من صحة المُعَلَّمات الرقمية في الواجهة الأمامية.
مُعَلَّمات السلسلة النصية (String Parameters)
string: مربع نص حر، يصبح قيمة نصية.
مُعَلَّمات القائمة (List Parameters)
int_list: أدخل أعدادًا صحيحة مفصولة بفواصل، وتصبح أعدادًا صحيحة مفصولة بفواصل في الاستعلام.string_list: مشابه لـint_list، ولكن للسلاسل النصية.
مُعَلَّمات مُعرّف محدد (Specific ID Parameters)
post_id: إدخال رقمي؛ يضمن وجود المنشور المحدد في المنتدى قبل تشغيل الاستعلام.topic_id: مشابه لـpost_id، ولكن للمواضيع.badge_id: يضمن وجود الشارة المحددة.
مُعَلَّمات منطقية (Boolean Parameters)
boolean: يعرض مربع اختيار.null boolean: يعرض قائمة منسدلة، تسمح بإدخال فارغ.
مُعَلَّمات الوقت (Time Parameters)
time: يعرض مدخل محدد الوقت.date: يعرض مدخل محدد التاريخ.datetime: يعرض مدخلًا يتضمن التاريخ والوقت معًا.
مُعَلَّمات التحديد (Selector Parameters)
user_id: يعرض مربع محدد مستخدمي Discourse، ويصبح مُعرّف المستخدم الرقمي.user_list: مشابه لـuser_id، ولكنه يسمح بعدة مستخدمين، ويصبح قائمة مفصولة بفواصل من مُعرّفات المستخدمين الرقمية.group_id: مشابه لـuser_id، ولكن للمجموعات.group_list: مشابه لـuser_list، ولكن للمجموعات.category_id: مشابه لـuser_id، ولكن للفئات.
المُعَلَّمات الداخلية (Internal Parameters)
current_user_id: لا يوجد واجهة مستخدم للإدخال؛ يضبط المتغير تلقائيًا على مُعرّف المستخدم الذي يقوم بتشغيل الاستعلام.
استخدام مُعَلَّمات القائمة (Using List Parameters)
عند استخدام مُعَلَّمات القائمة (int_list، string_list، user_list)، يجب توخي الحذر لتجنب أخطاء الصيغة. إليك مثال على الاستخدام الصحيح لمُعَلَّمة قائمة:
-- [params]
-- user_list :the_user_ids
SELECT SUM(length(bio_raw))
FROM user_profiles
WHERE user_id IN (:the_user_ids)
المُعَلَّمات الفارغة (Null Parameters)
يمكنك أيضًا السماح بإدخال فارغ عن طريق إضافة البادئة null إلى نوع المُعَلَّمة. هذا يعني أنه ليس من الضروري تقديم قيمة لتلك المُعَلَّمة عند تشغيل الاستعلام.
إليك بعض الأمثلة لكيفية تعريف مثل هذه المُعَلَّمات:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
-- null current_user_id :me
في استعلام SQL أعلاه، null_int و null_boolean و null_string هي مُعَلَّمات يمكن تركها فارغة عند تشغيل الاستعلام.
دعنا نرى كيف يمكن استخدام هذه الأنواع من المُعَلَّمات في استعلام:
-- [params]
-- null int :post_id
-- null string :username
SELECT *
FROM users
WHERE (id = :post_id OR :post_id IS NULL)
AND (username = :username OR :username IS NULL)
في هذا الاستعلام، إذا لم يتم توفير post_id أو username (أي تُركا كـ null)، سيتجاهل الاستعلام هذا الجزء من عبارة WHERE. يتيح هذا استعلامات أكثر مرونة حيث تكون بعض الشروط اختيارية.
التحقق من صحة الواجهة الأمامية (Front-end Validation)
سيتم التحقق من صحة معظم أنواع المُعَلَّمات في الواجهة الأمامية. تتضمن عمليات التحقق هذه المدخلات المطلوبة ولكن غير المعبأة، والإدخال الرقمي غير الصالح، والفئات أو المجموعات غير الموجودة، والأوقات ذات التنسيق الخاطئ، وما إلى ذلك. بالنسبة للإدخال غير الصالح، سيتم عرض سبب الخطأ في النموذج، وسيتم رفض عملية تشغيل الاستعلام.
أمثلة إضافية (Additional Examples)
فيما يلي بعض الأمثلة الإضافية لتعريف أنواع مختلفة من المُعَلَّمات:
-- [params]
-- int :int = 3
-- bigint :bigint = 12345678912345
-- boolean :boolean
-- null boolean :boolean_three = #null
-- string :string = little bunny foo foo
-- date :date = 14 jul 2015
-- time :time = 5:02 pm
-- datetime :datetime = 14 jul 2015 5:02 pm
-- double :double = 3.1415
-- string :inet = 127.0.0.1/8
-- user_id :user_id = system
-- post_id :post_id = http://localhost:3000/t/adsfdsfajadsdafdsds-sf-awerjkldfdwe/21/1?u=system
-- topic_id :topic_id = /t/-/21
-- int_list :int_list = 1,2,3
-- string_list :string_list = a,b,c
-- category_id :category_id = meta
-- group_id :group_id = admins
-- user_list :mul_users = system,discobot
-- current_user_id :me
