إنتقل إلى المحتوى الرئيسي
صفحة مترجمة

تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.

متغيرات الجلسة

راجع أيضًا:
[SET] [UNSET] [ جلسات الموفر ] [ استخدام المتغيرات ]

متغيرات الجلسة قيم مفردة تحتفظ بها الجلسة الحالية وتشير إليها الجمل اللاحقة. وهي متاحة في StackQL من الإصدار v1.0 فصاعدًا، وتعمل في واجهة الأوامر التفاعلية، وفي البرامج النصية لـ exec، وعبر بروتوكول الاتصال الخاص بـ PostgreSQL، ومن خلال خادم MCP.

تختلف متغيرات الجلسة عن متغيرات القوالب الموضحة في استخدام المتغيرات. يتم تمرير متغيرات القوالب إلى stackql exec عبر --iqldata و--var، ويتم إنشاء نص البرنامج النصي من القالب بقيمها قبل تحليله. أما متغيرات الجلسة فتُحل داخل الجملة بعد تحليلها، وتحتفظ بنوعها، ويمكن تغييرها بين الجمل.

تعيين المتغيرات وإزالتها​

تعين الجملة SET سلسلة نصية أو رقما أو قيمة منطقية أو null. تزيل الجملة UNSET متغيرا؛ والجملة SET name = DEFAULT مكافئة لها. القيمة null الصريحة قيمة مخزنة، وليست إعادة تعيين.

SET region = 'ap-southeast-2';
SET minimum_count = 3;
SET enabled = true;
SET optional_value = null;
UNSET region;

المصفوفات والكائنات ليست قيمًا مفردة. للاحتفاظ بمستند JSON، خزّنه كسلسلة نصية:

SET "providers.saved" = '{"provider":"aws","tenancy":"production"}';

إلغاء مرجعية متغير​

استخدم $name، دون علامات اقتباس، في أي موضع للتعبير. تُكتب السلاسل النصية كقيم حرفية في SQL مع إلغاء أحرفها الخاصة؛ وتحتفظ الأرقام والقيم المنطقية وnull بنوعها. القيمة '$name' بين علامتي اقتباس مفردتين هي النص الحرفي $name، وليست إلغاء مرجعية. يفشل المرجع إلى متغير غير موجود قبل إرسال أي طلب إلى الموفر.

يمكن استخدام القيم التي تم حلها في تعبيرات SQL العادية، بما في ذلك CAST وCONVERT والدمج باستخدام || واستدعاءات الدوال:

SET some_id = 42;
SET suffix = 'East';

SELECT CAST($some_id AS TEXT) AS id_text,
CONVERT($some_id, TEXT) || '-' || lower($suffix) AS label,
md5(lower(CONVERT($some_id, TEXT) || '-' || $suffix)) AS digest,
'$some_id' AS literal_text;

لا تقبل عمليات التعيين إلا القيم الحرفية المفردة أو المراجع المباشرة؛ طبّق التحويلات والتعبيرات الأخرى في الموضع الذي يستخدم فيه المتغير، لا في جملة SET.

المتغيرات في الشروط​

يُحل المتغير في عبارة WHERE قبل تخطيط الجملة، لذا يتم توجيهه إلى واجهة API الخاصة بالموفر تمامًا كما توجه القيمة الحرفية. لذلك يمكن توفير المعلمات المطلوبة من المتغيرات:

SET project = 'stackql-demo';
SET zone = 'australia-southeast1-a';

SELECT name, status
FROM google.compute.instances
WHERE project = $project AND zone = $zone;

تتم مقارنة القيم ذات الأنواع وفق نوعها. يؤدي الشرط WHERE active = $enabled مع SET enabled = false إلى التصفية حسب القيمة المنطقية، والشرط WHERE id = CAST($some_id AS TEXT) هو الشكل الذي يجب استخدامه عندما يكون عمود الموفر سلسلة نصية والمتغير رقما.

المتغيرات كأسماء للكائنات​

يمكن للمتغيرات أن تسمي العلاقات والأعمدة إلى جانب القيم. يتم تحويل الأسماء إلى معرفات في الجملة بعد تحليلها ولا تدرج أبدًا في نص SQL، لذا يتم رفض القيمة التي تحتوي على جملة، أو الفارغة، أو التي ليست سلسلة نصية قبل أي وصول إلى الموفر.

الموضعالشكل
عبارة FROMFROM $relation_name، أو حسب المكونات، FROM $provider.$service.$resource
عمود في تعبيرIDENTIFIER($column_name)، راجع IDENTIFIER
اسم مستعار لعمود أو جدولAS "$alias_name"
ORDER BYORDER BY IDENTIFIER($column_name)
LIMITLIMIT $row_count
أسماء أعمدة DDL، وقوائم أعمدة INSERT، وأهداف UPDATEالشكل "$name" بين علامتي اقتباس مزدوجتين

SET relation_name = 'aws.s3.buckets';
SET column_name = 'name';
SET output_name = 'bucket';
SET row_count = 10;

SELECT IDENTIFIER($column_name) AS "$output_name"
FROM $relation_name
WHERE region = 'ap-southeast-2'
ORDER BY IDENTIFIER($column_name)
LIMIT $row_count;

تحل عمليات الربط وتعبيرات CTE والاستعلامات الفرعية متغيرات العلاقات الخاصة بها بالشكل نفسه. تتكون قيم العلاقات المفصولة بنقاط من أربعة مكونات كحد أقصى. المتغيرات ليست أجزاء عشوائية من SQL: لا يمكن استبدال كلمة أساسية أو قائمة أعمدة مفصولة بفواصل أو عبارة WHERE كاملة بمتغير.

النطاق والعزل​

تنتمي المتغيرات إلى الجلسة التي عينتها. للاتصالات المنفصلة بخادم stackql srv متغيرات منفصلة، وكذلك الحال لاستدعاءات exec المنفصلة. كل طلب MCP جلسة مستقلة بذاته، لذا يجب إرسال SET والاستعلام الذي يستخدمه في دفعة الجمل نفسها. تبدأ الجلسات الجديدة دون أي متغيرات.

الجلسة هي النطاق الوحيد. الجملتان SET SESSION وUNSET SESSION مقبولتان وتعنيان تمامًا ما تعنيه SET وUNSET؛ وتوجد الكلمة الأساسية من أجل البرامج النصية التي يجب أن تبدو بالشكل نفسه كما في قواعد البيانات التي تختلف فيها إعدادات الجلسة عن الإعدادات العامة. يتم رفض GLOBAL، لأنه لا توجد حالة مشتركة بين الجلسات.

تحل الجمل المعدة مسبقًا المتغيرات عند تنفيذها، لا عند إعدادها، ولا يعاد استخدام الخطة التي تحتوي على قيم جلسة مرتبطة عبر عمليات التنفيذ.

عند تمكين إدارة الوصول، تتطلب قراءة متغير الإذن session/variables:read، ويتطلب تعيينه أو إعادة تعيينه الإذن session/config:write. لا يمنح حل متغير إلى اسم كائن أي إذن على ذلك الكائن؛ إذ يتم تخويل العلاقة التي تم حلها قبل التنفيذ كالمعتاد.