تُعد المعلمات أداة قوية يمكن استخدامها في استعلامات مستكشف البيانات على Discourse. تسمح المعلمات باستعلامات أكثر ديناميكية وقابلية للتخصيص، وبدلاً من ترميز القيم بشكل ثابت في استعلاماتك، يمكنك تعريف متغيرات تطالب بالإدخال عند تشغيل الاستعلام.
تعريف معلمة
لتعريف معلمة، يمكنك استخدام الصيغة التالية:
-- [params]
-- int :parameter_name = 10
سيبدأ قسم المعلمة في الاستعلام دائمًا بـ -- [params]، متبوعًا بنوع كل معلمة في سطر جديد، حيث سيتم استبدال parameter_name بالاسم الخاص بمعلمتك.
سيؤدي هذا إلى إنشاء حقل يمكنك فيه إدخال قيم مختلفة في كل مرة تقوم فيها بتشغيل الاستعلام.
أنواع المعلمات
عند تعريف المعلمات في استعلامات مستكشف البيانات، يمكنك تحديد أنواع مختلفة من المدخلات. فيما يلي أنواع المعلمات المتاحة وأوصافها:
معلمات رقمية
int: يعرض إدخال رقم، ويصبح قيمة رقمية.intمقيد بالأرقام ذات 32 بت.bigint: مشابه لـint، ولكنه يمكن أن يكون أكبر.double: يسمح بالقيم العشرية.
سيتم التحقق من صحة المعلمات الرقمية على الواجهة الأمامية.
معلمات السلسلة النصية
string: مربع نص حر، يصبح قيمة نصية.
معلمات القائمة
int_list: أدخل أعدادًا صحيحة مفصولة بفواصل، وتصبح أعدادًا صحيحة مفصولة بفواصل في الاستعلام.string_list: مشابه لـint_list، ولكن للسلاسل النصية.
معلمات معرف محدد
post_id: إدخال رقمي؛ يضمن وجود المنشور المحدد في المنتدى قبل تشغيل الاستعلام.topic_id: مشابه لـpost_id، ولكن للمواضيع.badge_id: يضمن وجود الشارة المحددة.
معلمات منطقية
boolean: يعرض مربع اختيار.null boolean: يعرض قائمة منسدلة، تسمح بإدخال فارغ.
معلمات الوقت
time: يعرض إدخال منتقي الوقت.date: يعرض إدخال منتقي التاريخ.datetime: يعرض مربع إدخال يتضمن التاريخ والوقت.
معلمات الاختيار
user_id: يعرض مربع اختيار المستخدم في Discourse، ويصبح معرف المستخدم الرقمي.user_list: مشابه لـuser_id، ولكنه يسمح بعدة مستخدمين، ويصبح قائمة مفصولة بفواصل لمعرفات المستخدمين الرقمية.group_id: مشابه لـuser_id، ولكن للمجموعات.group_list: مشابه لـuser_list، ولكن للمجموعات.category_id: مشابه لـuser_id، ولكن للفئات.
استخدام معلمات القائمة
عند استخدام معلمات القائمة (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 إلى نوع المعلمة. هذا يعني أنه ليس من الضروري تقديم قيمة لتلك المعلمة عند تشغيل الاستعلام.
إليك بعض الأمثلة لكيفية تعريف هذه المعلمات:
-- [params]
-- null int :null_int
-- null boolean :null_boolean
-- null string :null_string
في 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. هذا يسمح باستعلامات أكثر مرونة حيث تكون بعض الشروط اختيارية.
التحقق من صحة الواجهة الأمامية
سيتم التحقق من صحة معظم أنواع المعلمات على الواجهة الأمامية. تشمل هذه التحققات المدخلات المطلوبة ولكن غير المكتملة، والمدخلات الرقمية غير الصالحة، والفئات أو المجموعات غير الموجودة، والأوقات المشوهة، وما إلى ذلك. بالنسبة للمدخلات غير الصالحة، سيتم عرض سبب الخطأ في النموذج، وسيتم رفض عملية تشغيل الاستعلام.
أمثلة إضافية
فيما يلي بعض الأمثلة الإضافية لتعريف أنواع مختلفة من المعلمات:
-- [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
