تُرجمت هذه الصفحة من الإنجليزية بمساعدة الذكاء الاصطناعي. إذا اختلفت النسختان، فالمرجع هو النسخة الإنجليزية.
العلامات العامة
تقبل أوامر StackQL العلامات العامة، لكن بعضها ينطبق على وضع معين فقط. حدّدها في سطر الأوامر أو، حيثما كان ذلك مدعومًا، في ملف تهيئة StackQL (.stackqlrc). ترد العلامات --pgsrv.* في خيارات خادم PostgreSQL.
| العلامة | نوع البيانات | الوصف | الافتراضي |
|---|---|---|---|
--access.config | string | تكوين وصول الجهة المستدعية، وهو مغلف JSON {"path": "/path/to/access.json"} (ويُقبل أيضًا مسار ملف مجرد). تؤدي إلى تمكين إدارة الوصول: تتم مصادقة الجهات المستدعية باستخدام JWT أو رمز مميز ثابت من نوع bearer أو TLS المتبادل أو هوية نظام التشغيل المحلي، ويتم تخويل الجمل وفقًا لقواعد السياسة. تتم قراءة بيانات اعتماد الرمز المميز المحلي من متغير البيئة STACKQL_CALLER_TOKEN. متاح في StackQL من الإصدار v1.0 فصاعدًا. | |
--allow-persistent-secrets | flag | السماح للجلسة باختيار مخزن أسرار دائم في نظام التشغيل (macOS Keychain أو Linux Secret Service أو Windows Credential Manager) باستخدام SET "$.secret_store". يتم رفض المخازن القائمة على الملفات المسطحة حتى مع هذه العلامة. راجع جلسات الموفرين والأسرار. متاح في StackQL من الإصدار v1.0 فصاعدًا. | false |
--allow-secret-dereference | flag | السماح بإلغاء مرجعية قيم الأسرار وبيانات الاعتماد في تعبيرات SQL ("$secrets.name" و"$auth.provider.field")، مما يعني أنها قد تظهر في النتائج والسجلات والملفات الناتجة المحفوظة للاستعلامات. غير مطلوب لمصادقة الموفرين العادية. راجع قيم الأسرار في SQL. متاح في StackQL من الإصدار v1.0 فصاعدًا. | false |
--apirequesttimeout | integer | مهلة طلب API بالثواني، و0 لعدم وجود مهلة | 45 |
--approot | string | المسار الجذر لتكوين التطبيق وذاكرة التخزين المؤقت | {cwd}/.stackql |
--approotfilemode | uint32 | وضع ملفات تكوين التطبيق وذاكرة التخزين المؤقت | 493 |
--auth | string | أزواج المفاتيح والقيم لسياق auth بتنسيق json | |
--cachekeycount | integer | العدد الأولي لمفاتيح ذاكرة التخزين المؤقت | 100 |
--configfile | string | المسار الكامل لملف التكوين | {cwd}/.stackqlrc |
--cpuprofile | string | ملف cpuprofile، لا يوجد ملف إذا كانت القيمة فارغة | null |
--dataflow.dependency.max | int | الحد الأقصى لعمق تبعيات تدفق البيانات لاستعلام معين | 50 |
--dataflow.components.max | int | الحد الأقصى لعدد المكونات ضعيفة الاتصال في تدفق البيانات لاستعلام معين | 50 |
--dbInternal | string | سلسلة نصية بتنسيق JSON / YAML لتكوين معالجة استعلامات الصيانة الداخلية في DBMS | {} |
-d, --delimiter | string | الفاصل لإخراج csv. حرف واحد فقط. يتم تجاهله لكل إخراج غير csv | , |
--dryrun | flag | علامة dryrun؛ تشغيل المعالج المسبق فقط، ويعاد الإخراج الناتج عن القوالب | false |
--env.file | string | ملف اختياري بنمط dotenv يتم تحميله في بيئة العملية عند بدء التشغيل (جميع الأوامر)؛ وتعيد الأداة reload_credentials في MCP تحميله عند الطلب. لا يعد غياب الملف خطأ؛ ويتم تخطي المفاتيح ذات القيم الفارغة؛ وتتم الكتابة فوق المتغيرات الموجودة. لا يؤخذ من الملف .stackqlrc. متاح في إصدارات StackQL بعد v0.10.542. | null |
--execution.concurrency.limit | int | حد التزامن لتنفيذ الاستعلامات | 1 |
--export.alias | string | بادئة الاسم المستعار للتصدير (مساحة الاسم أو المخطط) | |
--gc | string | سلسلة نصية بتنسيق JSON / YAML تمثل تكوين GC | {} |
-H, --hideheaders | flag | يعطل رؤوس الأعمدة، وهو صالح فقط مع --output csv أو --output text | false |
--http.log.enabled | flag | عرض معلومات طلبات http في الوحدة الطرفية | false |
--http.proxy.host | string | مضيف الخادم الوكيل (اتركه فارغًا لعدم استخدام خادم وكيل) | null |
--http.proxy.password | string | كلمة مرور الخادم الوكيل | null |
--http.proxy.port | integer | منفذ الخادم الوكيل، وأي رقم أقل من 0 أو يساويه يؤدي إلى استخدام المنفذ الافتراضي للبروتوكول المحدد (على سبيل المثال http -> 80) | -1 |
--http.proxy.scheme | string | بروتوكول الخادم الوكيل، http أو https | http |
--http.proxy.user | string | مستخدم الخادم الوكيل | null |
--http.response.maxResults | integer | الحد الأقصى للنتائج لكل طلب http، وأي رقم أقل من 0 أو يساويه يعني عدم وجود حد | -1 |
--http.response.pageLimit | integer | الحد الأقصى لعدد صفحات النتائج التي تعاد لكل مورد، وأي رقم أقل من 0 أو يساويه يعني عدم وجود حد | 20 |
--indirect.depth.max | integer | الحد الأقصى لعمق الاستعلامات غير المباشرة: طرق العرض والاستعلامات الفرعية | 5 |
-i, --infile | string | ملف الإدخال (ملف IQL) الذي تقرأ منه الاستعلامات | {stdin} |
-q, --iqldata | string | ملف السياق (البيانات) لاستخدام القوالب (ملف json أو jsonnet) | |
--loglevel | string | مستوى السجل، ويجب أن يكون أحد {panic, fatal, error, warn, info, debug, trace} (ويُقبل warning كاسم مستعار لـ warn) | fatal |
--mcp.config | string | كائن تكوين خادم MCP بتنسيق JSON / YAML (stackql mcp وstackql srv) | {} |
--mcp.log.format | string | ترميز سجل تدقيق MCP، jsonl أو otel (إدخالات سجل OTLP/JSON)؛ ويتجاوز server.audit.format في --mcp.config. راجع تنسيق السجل. متاح في StackQL من الإصدار v0.11.660 فصاعدًا. | jsonl |
--mcp.protocol.version | string | أحدث مراجعة لبروتوكول MCP يتم الإعلان عنها: auto أو 2026-07-28 (في وضع بدون جلسات فقط) أو مراجعة أقدم مثل 2025-11-25؛ ويتجاوز server.protocol_version في --mcp.config. راجع قفل المراجعة. متاح في StackQL من الإصدار v0.12.732 فصاعدًا. | auto |
--mcp.server.type | string | نوع خادم MCP، أحد {http, stdio, reverse_proxy}. راجع نوع خادم MCP. | http |
--metadatattl | integer | مدة صلاحية (TTL) مستندات بيانات التعريف المخزنة مؤقتًا، بالثواني | 3600 |
--namespaces | string | سلسلة نصية بتنسيق JSON / YAML تمثل مساحات الأسماء للتخزين المؤقت وطرق العرض وغيرها | {} |
--offline | flag | العمل دون اتصال باستخدام البيانات المخزنة مؤقتًا | false |
-f, --outfile | string | ملف الإخراج الذي تكتب فيه النتائج | {stdout} |
-o, --output | string | تنسيق الإخراج، ويجب أن يكون أحد {json, jsonl, table, csv, text, otel} (ويُقبل ndjson كاسم مستعار لـ jsonl). يصدر التنسيق otel إدخالات سجل OpenTelemetry، راجع أوضاع الإخراج؛ وهو متاح في StackQL من الإصدار v0.11.660 فصاعدًا. عند تكوين exporter في --otel.config، يتم أيضًا دفع إدخالات otel إلى نقطة النهاية تلك | table |
--otel.config | string | سلسلة نصية بتنسيق JSON / YAML لتكوين تنسيق الإخراج otel؛ تدفع المفاتيح exporter.endpoint وexporter.headers وexporter.timeout_ms وexporter.batch_size الإدخالات إلى نقطة نهاية سجلات OTLP/HTTP، راجع الدفع إلى نقطة نهاية OTLP. متاح في StackQL من الإصدار v0.12.732 فصاعدًا | {} |
--preview | string | سلسلة نصية بتنسيق JSON لتمكين ميزات المعاينة. يعرض {"unstable": true} العلاقات stackql_unstable_<provider>.<service>.<resource> المبنية على مستندات، والتي يحلها omnisdk ويشغلها مباشرة من مستندات الموفرين مع بث الصفوف فور إنتاجها؛ وتضبط المفاتيح المتبقية (batchSize وflushInterval وendpoint وinsecureSkipTLSVerify) تلك الواجهة الخلفية. ميزات المعاينة غير مستقرة: قد يتغير السلوك وبناء الجملة والإخراج أو يتعطل بين الإصدارات دون سابق إنذار، لذا لا تعتمد عليها في بيئة الإنتاج. من الإصدار v1.0، يعرض التفعيل الاختياري نفسه العلاقتين stackql_preview.iac.run وstackql_preview.iac.destroy، اللتين تطبقان مجموعة موارد معلنة وتزيلانها عبر omnisdk مع الاحتفاظ بالحالة تحت المسار الجذر للتطبيق. راجع ميزات المعاينة | {} |
--provider | string | الموفر الافتراضي الأولي. على سبيل المثال، مع --provider github، يُحل repos.repos إلى github.repos.repos دون جملة USE سابقة. لا يجري المصادقة مع الموفر. | لا يوجد |
--querycachesize | integer | حجم ذاكرة التخزين المؤقت LRU لخطط الاستعلامات بعدد الإدخالات | 10000 |
--registry | string | سلسلة نصية بتنسيق JSON / YAML لتكوين موقع سجل الموفرين والتحقق من توقيعات مستندات الموفرين | راجع --registry |
--session | string | سلسلة نصية بتنسيق JSON / YAML تمثل تكوين الجلسة | {} |
--sqlBackend | string | سلسلة نصية بتنسيق JSON / YAML تمثل تكوين نظام واجهة SQL الخلفية | راجع --sqlBackend |
--store.txn | string | سلسلة نصية بتنسيق JSON / YAML تمثل تكوين مخزن Txn | {} |
--tls.CABundle | string | مسار حزمة شهادات CA، وإذا لم يتم تحديده تستخدم الإعدادات الافتراضية للنظام | |
--tls.allowInsecure | flag | السماح بالثقة في الشهادات غير الآمنة (غير موصى به) | |
--upstream.errors | string | سياسة بتنسيق JSON / YAML للتسامح الصريح مع حالات استجابة HTTP عند القراءة من الموفرين. راجع --upstream.errors. | {} |
--var | string | متغيرات خارجية تقدم كأزواج مفاتيح وقيم لتحميلها في استعلامات StackQL من خلال ملفات بيانات jsonnet | |
-v, --verbose | flag | إخراج مفصل | false |
-h, --help | تعليمات خاصة بالسياق لـ stackql | ||
--version | يعرض إصدار برنامج StackQL |
العلامة --colorscheme مهملة ولم تعد تغير ألوان واجهة الأوامر. ويتم قبول العلامة --usenonpreferredapis لكنها لا تغير اختيار واجهة API في المحرك الحالي.
--registry
تستخدم العلامة --registry لتكوين المكان الذي تقرأ منه مستندات الموفرين، وما إذا كان يتم التحقق من توقيعاتها. القيمة سلسلة نصية بتنسيق JSON تحتوي على المفاتيح التالية:
| المفتاح | الوصف | الافتراضي |
|---|---|---|
url | عنوان URL للسجل. يتم استخدام سجل الموفرين العام الخاص بـ StackQL عند حذفه. | السجل العام |
localDocRoot | دليل محلي يحتوي على مستندات الموفرين، تتم قراءتها بدلًا من تنزيلها من السجل. يستخدم عند تطوير موفر. | |
srcPrefix | بادئة المسار تحت جذر السجل حيث توجد مستندات المصدر للموفرين. | src |
verifyConfig.nopVerify | تؤدي القيمة true إلى تخطي التحقق من التوقيع. عيّن القيمة إلى false لاشتراط توقيع ML-DSA-65 (FIPS 204) مضمن في كل مستند موفر وخدمة تتم قراءته، بما في ذلك علاقات المعاينة المبنية على مستندات. | true |
verifyConfig.publicKeys | كائن JSON يربط معرفات المفاتيح بمفاتيح ML-DSA-65 عامة مرمزة بالنظام الست عشري، للسجلات الخاصة. يحل محل مفاتيح الإنتاج المضمنة؛ أما تحديد كائن فارغ صراحة فهو خطأ. | المفاتيح المضمنة |
مثال: اشتراط مستندات موفرين موقعة رقميًا
تمكين التحقق لكل مستند موفر وخدمة تتم قراءته من السجل العام، مع التحقق منه مقابل مفاتيح الإنتاج المضمنة:
stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell
مثال: قراءة مستندات غير موقعة من دليل محلي
يوجه هذا الأمر السجل إلى دليل يحتوي على مستندات موفرين قيد التطوير. وهي غير موقعة، لذا لا يتم تمكين التحقق:
stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell
التحقق من التوقيع متاح في StackQL من الإصدار v1.0 فصاعدًا، وهو معطل افتراضيًا. تغطي التوقيعات بايتات YAML الدقيقة للمستند، لذا فإن أي تعديل، بما في ذلك تغيير في التنسيق أو في الأسطر الجديدة، يبطلها؛ أعد التوقيع باستخدام الأداة pqsig sign-doc الخاصة بالسجل. يجب أن تحتفظ مستندات التطوير المحلية غير الموقعة بالقيمة nopVerify: true. لم تعد خيارات الشهادات السابقة وملفات sidecar ذات الامتداد .sig مستخدمة، ويجب إعادة نشر الملفات المضغوطة التي نشرت مع ملفات sidecar فقط قبل استخدامها مع التحقق. يجري التحقق مصادقة كل مستند عند قراءته؛ ولا يشمل تنزيل الملفات المضغوطة واستخراجها.
--sqlBackend
تستخدم العلامة --sqlBackend لتكوين واجهة SQL خلفية خارجية لـ StackQL، مما يتيح لك استخدام محرك قاعدة بيانات خارجي (مثل PostgreSQL) بدلًا من محرك SQL المضمن الافتراضي. يفيد هذا في الاستفادة من قاعدة بيانات خارجية لمعالجة الاستعلامات أو للتخزين الدائم أو للتكامل مع البنية التحتية الحالية لقواعد البيانات.
القيمة سلسلة نصية بتنسيق JSON تحتوي على المفاتيح التالية:
| المفتاح | الوصف | أمثلة على القيم |
|---|---|---|
dbEngine | نوع محرك قاعدة البيانات | postgres_tcp |
sqlDialect | لهجة SQL المراد استخدامها | postgres |
dsn | اسم مصدر البيانات (سلسلة الاتصال) لقاعدة البيانات | راجع الأمثلة أدناه |
مثال: استخدام PostgreSQL كواجهة SQL خلفية
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user:password@hostname:port/dbname?sslmode=require"}' \
shell
مثال: استخدام واجهة PostgreSQL في Databricks
يعرض Databricks واجهة متوافقة مع PostgreSQL يمكن استخدامها كواجهة SQL خلفية لـ StackQL. تستخدم قيمة DSN التنسيق القياسي لسلسلة اتصال PostgreSQL مع بيانات اعتماد Databricks الخاصة بك:
./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user%40domain.com:your-access-token@your-databricks-host.cloud.databricks.com/databricks_postgres?sslmode=require"}' \
shell
يجب ترميز الأحرف الخاصة في اسم المستخدم أو كلمة المرور (مثل @) بتنسيق URL في قيمة DSN (على سبيل المثال، يصبح @ هو %40).
--upstream.errors
استخدم المفتاح http.ignoreStatusCodes لسرد حالات استجابة HTTP التي يجب أن تتسامح معها عملية القراءة من الموفر صراحة. الإدخالات سلاسل نصية: استخدم رمزًا دقيقًا مثل "503" أو فئة مثل "5xx". لا تضيف القيمة الافتراضية {} أي استثناءات إلى المعالجة العادية التي يجريها المحرك لاستجابات المصدر. لا يعيد هذا الإعداد محاولة الطلبات الفاشلة، ولا ينطبق على عمليات تعديل البيانات أو عمليات تبادل المصادقة.
لا تساهم الاستجابة التي يتم تجاهلها بأي صفوف. يمكن لعمليات القراءة الأخرى في الاستعلام أن تعيد صفوفًا مع ذلك، لذا قد يعيد الاستعلام الناجح نتائج غير مكتملة. يبلغ StackQL عن حالة HTTP التي تم تجاهلها كرسالة تشخيصية.
على سبيل المثال، يستخدم اختبار ربط GitHub باستخدام المحاكاة هذا الخيار:
stackql exec --upstream.errors='{"http":{"ignoreStatusCodes":["5xx"]}}' \
"SELECT r.name, c.login FROM github.repos.repos r
JOIN github.repos.collaborators c ON c.repo = r.name
WHERE r.org = 'example-org' AND c.owner = 'example-org'
ORDER BY r.name;"
في الاختبار، يعيد طلب المتعاونين لأحد المستودعات HTTP 500. ومع ذلك يعيد الاستعلام صفوف المتعاونين للمستودعات الأخرى، ويتضمن stderr السطر ignoring upstream response: 500 INTERNAL SERVER ERROR. يفضل استخدام رمز حالة دقيق عندما لا تتوقع سوى فشل واحد.