تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.
SET
تعين متغير جلسة، أو تحدد إعدادات وقت التشغيل للجلسة الحالية. متاح في StackQL من الإصدار v1.0 فصاعدًا.
راجع أيضًا:
[UNSET] [ متغيرات الجلسة ] [ جلسات الموفر ] [IDENTIFIER]
بناء الجملة
setStatement::=
setExpression::=
SET [ SESSION ] <target> = { <literal> | DEFAULT | <reference> } [, <target> = { <literal> | DEFAULT | <reference> } ...];
target
معرف عادي (region)، أو اسم بين علامتي اقتباس مزدوجتين ("providers.saved")، أو مسار تكوين مسبوق بعلامة الدولار بين علامتي اقتباس مزدوجتين ("$.auth.aws.password").
literal
سلسلة نصية أو رقم أو قيمة منطقية أو null. توضع السلاسل النصية بين علامتي اقتباس مفردتين. المصفوفات والكائنات ليست قيمًا عددية؛ احتفظ بمستند JSON كسلسلة نصية.
DEFAULT
يعيد تعيين الهدف، وهو ما يعادل UNSET. القيمة null الصريحة قيمة مخزنة، وليست إعادة تعيين.
reference
مرجع "$name" بين علامتي اقتباس مزدوجتين إلى متغير موجود، على سبيل المثال SET "$.providers.production" = "$providers.saved";.
SESSION
اختياري، وهو النطاق الوحيد في StackQL. SET SESSION name = ... وSET name = ... هما الجملة نفسها: ينتمي كل تعيين إلى الجلسة الحالية ولا ينتمي إلى أي شيء آخر. توجد هذه الكلمة الأساسية لكي تُقرأ البرامج النصية كما تُقرأ في قواعد البيانات التي تختلف فيها SET SESSION عن SET GLOBAL. يتم تحليل SET GLOBAL لكنها تُرفض مع الخطأ configuration scope "global" is not supported; use SESSION، لأنه لا توجد حالة مشتركة بين الجلسات.
تُطبق التعيينات في قائمة SET واحدة بالترتيب ولا تشكل معاملة: إذا فشل التعيين الثاني في القائمة، يظل التعيين الأول ساريًا.
الأهداف
| الهدف | التأثير |
|---|---|
name أو "name" | يخزن متغير جلسة عدديًا يتم إلغاء مرجعيته باستخدام $name في الجمل اللاحقة. النقاط وحدها لا تحدد التكوين: "providers.saved" متغير اسمه providers.saved. الكتابة الأقدم "variables.name" اسم مستعار لـ name. |
"$.auth.<provider>.<field>" | يعين حقلًا واحدًا من سياق المصادقة الخاص بالموفر لهذه الجلسة. الحقول هي مفاتيح الكائن --auth لذلك الموفر، على سبيل المثال credentialsenvvar أو password أو token_url. |
"$.providers.<alias>" | يربط اسمًا مستعارًا لموفر ببيانات اعتماد خاصة به وتسمية tenancy وقيم افتراضية للمعلمات وإعدادات الأداء. القيمة مستند JSON داخل سلسلة نصية، راجع جلسات الموفر. |
"$.secrets.<name>" | يخزن سرًا في مخزن الأسرار الخاص بالجلسة. القيمة قيمة حرفية نصية، وهي في العادة مستند auth بتنسيق JSON، ويشار إليها من الاسم المستعار للموفر بـ auth_secret. |
"$.secret_store" | يحدد مخزن الأسرار الدائم الخاص بنظام التشغيل، {"backend":"os","namespace":"..."}. يتطلب العلامة --allow-persistent-secrets التي يحددها المشغل. |
يؤثر كل شكل في الجلسة الحالية فقط. لا ترى الاتصالات المستقلة بخادم srv تعيينات الاتصالات الأخرى، وكل طلب MCP هو جلسة مستقلة بذاتها، لذا نفّذ التكوين والاستعلام في دفعة جمل واحدة عند استخدام خادم MCP.
أمثلة
تعيين متغيرات الجلسة
تخزن كل جملة قيمة عددية واحدة تحت الاسم المحدد، وتحتفظ القيمة بنوعها: region سلسلة نصية، وminimum_count عدد صحيح، وenabled قيمة منطقية. يتم تخزين null كقيمة، لذا يُحل $optional_value لاحقًا إلى NULL في SQL بدلًا من أن يفشل لكونه غير معرف. تعين الجملة الأخيرة متغيرين في قائمة واحدة.
SET region = 'ap-southeast-2';
SET minimum_count = 3;
SET enabled = true;
SET optional_value = null;
SET suffix = 'East', some_id = 42;
تحديد نطاق الجلسة صراحة
الجملتان الأوليان متطابقتان: تسمي SESSION النطاق الوحيد الموجود، ويستمر كلا التعيينين حتى يتم إلغاء تعيين المتغير أو تنتهي الجلسة. استخدم هذه الكلمة الأساسية عندما ينبغي أن يُقرأ البرنامج النصي كما يُقرأ في قاعدة بيانات تميز بين إعدادات الجلسة والإعدادات العامة. تُعرض الجملة الموجودة داخل كتلة التعليق للمقارنة: فهي لا تعين شيئًا وتفشل مع الخطأ configuration scope "global" is not supported; use SESSION، لأنه لا تتم مشاركة أي حالة بين الجلسات.
SET region = 'ap-southeast-2';
SET SESSION region = 'ap-southeast-2';
/*
SET GLOBAL region = 'ap-southeast-2';
-- FAILS with configuration scope "global" is not supported; use SESSION
*/
استخدام متغير في استعلام
استخدم $name بدون علامات اقتباس لإلغاء مرجعية متغير في أي موضع من مواضع التعبيرات. تحتفظ القيم بنوعها: تُدرج السلاسل النصية كقيم حرفية في SQL مع إلغاء أحرفها الخاصة، وتمرر الأرقام والقيم المنطقية وnull كما هي. يتم حل المتغيرات في عبارة WHERE قبل تخطيط الطلب، لذا يتم دفعها إلى الموفر مثل القيم الحرفية.
SET project = 'stackql-demo';
SET zone = 'australia-southeast1-a';
SELECT name, status FROM google.compute.instances
WHERE project = $project AND zone = $zone;
إعادة تعيين متغير
تزيل DEFAULT المتغير، تمامًا كما تفعل UNSET، لذا يفشل أي $region لاحق مع الخطأ variable "$region" is not defined حتى يتم تعيينه مرة أخرى؛ ويوضح الاستعلام الموجود داخل كتلة التعليق هذا الفشل. يختلف هذا عن تعيين null، الذي يترك المتغير في مكانه بقيمة NULL.
SET region = 'ap-southeast-2';
SET region = DEFAULT;
/*
SELECT name FROM aws.s3.buckets WHERE region = $region;
-- FAILS with variable "$region" is not defined
*/
نسخ قيمة من متغير آخر
يمكن أن يكون الطرف الأيمن مرجعًا بين علامتي اقتباس مزدوجتين إلى متغير موجود، وهو ما ينسخ القيمة التي يحملها ذلك المتغير في تلك اللحظة. هنا يتم أولًا تخزين ربط موفر كمتغير عادي اسمه providers.saved (النقاط لا تجعله تكوينًا)، ثم يتم تنشيطه بنسخه إلى المسار $.providers.production. لا تؤثر إزالة النسخة المحفوظة بعد ذلك في الربط النشط.
SET "providers.saved" = '{"provider":"aws","tenancy":"production-account","auth":{"type":"aws_signing_v4","access_key_id_env_var":"PRODUCTION_AWS_ACCESS_KEY_ID","secret_access_key_env_var":"PRODUCTION_AWS_SECRET_ACCESS_KEY"}}';
SET "$.providers.production" = "$providers.saved";
UNSET "providers.saved";
تجاوز حقل بيانات اعتماد لهذه الجلسة
سياق المصادقة الخاص بالموفر هو الكائن الذي يتم تمريره له عبر --auth عند بدء التشغيل. يستبدل المسار الموجود تحت $.auth حقلًا واحدًا من ذلك الكائن لبقية الجلسة ويترك الحقول الأخرى كما كانت. هنا يتم توجيه موفر GitHub إلى متغير بيئة مختلف يحمل رمزًا مميزًا للقراءة فقط؛ تتم قراءة المتغير من بيئة عملية StackQL، وتستخدمه الاستعلامات اللاحقة على github.* حتى يتم إلغاء تعيين الحقل أو تنتهي الجلسة.
SET "$.auth.github.credentialsenvvar" = 'GITHUB_TOKEN_READONLY';
ربط اسم مستعار لموفر
الاسم المستعار للموفر هو مثيل ثان من الموفر يتم تكوينه بشكل مستقل، ويُستخدم بدلًا من اسم الموفر في الاستعلامات. القيمة مستند JSON داخل سلسلة نصية: يسمي provider الموفر الأساسي، ويعطي tenancy تسمية للحساب، وauth كتلة بيانات اعتماد بالشكل نفسه المستخدم في --auth، ويوفر params قيمًا افتراضية لمعلمات الطلب مثل region. بعد ذلك تعمل الاستعلامات على production.s3.buckets باستخدام بيانات الاعتماد هذه، بينما يحتفظ aws.s3.buckets بتكوين بدء التشغيل. توجد القائمة الكاملة للمفاتيح في جلسات الموفر.
SET "$.providers.production" = '{
"provider": "aws",
"tenancy": "production-account",
"auth": {
"type": "aws_signing_v4",
"access_key_id_env_var": "PRODUCTION_AWS_ACCESS_KEY_ID",
"secret_access_key_env_var": "PRODUCTION_AWS_SECRET_ACCESS_KEY"
},
"params": {"region": "ap-southeast-2"}
}';
SELECT name FROM production.s3.buckets;