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

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

العلامات العامة

تقبل أوامر StackQL العلامات العامة، لكن بعضها ينطبق على وضع معين فقط. حدّدها في سطر الأوامر أو، حيثما كان ذلك مدعومًا، في ملف تهيئة StackQL (.stackqlrc). ترد العلامات --pgsrv.* في خيارات خادم PostgreSQL.

العلامةنوع البياناتالوصفالافتراضي
--access.configstringتكوين وصول الجهة المستدعية، وهو مغلف JSON {"path": "/path/to/access.json"} (ويُقبل أيضًا مسار ملف مجرد). تؤدي إلى تمكين إدارة الوصول: تتم مصادقة الجهات المستدعية باستخدام JWT أو رمز مميز ثابت من نوع bearer أو TLS المتبادل أو هوية نظام التشغيل المحلي، ويتم تخويل الجمل وفقًا لقواعد السياسة. تتم قراءة بيانات اعتماد الرمز المميز المحلي من متغير البيئة STACKQL_CALLER_TOKEN. متاح في StackQL من الإصدار v1.0 فصاعدًا.
--allow-persistent-secretsflagالسماح للجلسة باختيار مخزن أسرار دائم في نظام التشغيل (macOS Keychain أو Linux Secret Service أو Windows Credential Manager) باستخدام SET "$.secret_store". يتم رفض المخازن القائمة على الملفات المسطحة حتى مع هذه العلامة. راجع جلسات الموفرين والأسرار. متاح في StackQL من الإصدار v1.0 فصاعدًا.false
--allow-secret-dereferenceflagالسماح بإلغاء مرجعية قيم الأسرار وبيانات الاعتماد في تعبيرات SQL ("$secrets.name" و"$auth.provider.field")، مما يعني أنها قد تظهر في النتائج والسجلات والملفات الناتجة المحفوظة للاستعلامات. غير مطلوب لمصادقة الموفرين العادية. راجع قيم الأسرار في SQL. متاح في StackQL من الإصدار v1.0 فصاعدًا.false
--apirequesttimeoutintegerمهلة طلب API بالثواني، و0 لعدم وجود مهلة45
--approotstringالمسار الجذر لتكوين التطبيق وذاكرة التخزين المؤقت{cwd}/.stackql
--approotfilemodeuint32وضع ملفات تكوين التطبيق وذاكرة التخزين المؤقت493
--authstringأزواج المفاتيح والقيم لسياق auth بتنسيق json
--cachekeycountintegerالعدد الأولي لمفاتيح ذاكرة التخزين المؤقت100
--configfilestringالمسار الكامل لملف التكوين{cwd}/.stackqlrc
--cpuprofilestringملف cpuprofile، لا يوجد ملف إذا كانت القيمة فارغةnull
--dataflow.dependency.maxintالحد الأقصى لعمق تبعيات تدفق البيانات لاستعلام معين50
--dataflow.components.maxintالحد الأقصى لعدد المكونات ضعيفة الاتصال في تدفق البيانات لاستعلام معين50
--dbInternalstringسلسلة نصية بتنسيق JSON / YAML لتكوين معالجة استعلامات الصيانة الداخلية في DBMS{}
-d, --delimiterstringالفاصل لإخراج csv. حرف واحد فقط. يتم تجاهله لكل إخراج غير csv,
--dryrunflagعلامة dryrun؛ تشغيل المعالج المسبق فقط، ويعاد الإخراج الناتج عن القوالبfalse
--env.filestringملف اختياري بنمط dotenv يتم تحميله في بيئة العملية عند بدء التشغيل (جميع الأوامر)؛ وتعيد الأداة reload_credentials في MCP تحميله عند الطلب. لا يعد غياب الملف خطأ؛ ويتم تخطي المفاتيح ذات القيم الفارغة؛ وتتم الكتابة فوق المتغيرات الموجودة. لا يؤخذ من الملف .stackqlrc. متاح في إصدارات StackQL بعد v0.10.542.null
--execution.concurrency.limitintحد التزامن لتنفيذ الاستعلامات1
--export.aliasstringبادئة الاسم المستعار للتصدير (مساحة الاسم أو المخطط)
--gcstringسلسلة نصية بتنسيق JSON / YAML تمثل تكوين GC{}
-H, --hideheadersflagيعطل رؤوس الأعمدة، وهو صالح فقط مع --output csv أو --output textfalse
--http.log.enabledflagعرض معلومات طلبات http في الوحدة الطرفيةfalse
--http.proxy.hoststringمضيف الخادم الوكيل (اتركه فارغًا لعدم استخدام خادم وكيل)null
--http.proxy.passwordstringكلمة مرور الخادم الوكيلnull
--http.proxy.portintegerمنفذ الخادم الوكيل، وأي رقم أقل من 0 أو يساويه يؤدي إلى استخدام المنفذ الافتراضي للبروتوكول المحدد (على سبيل المثال http -> 80)-1
--http.proxy.schemestringبروتوكول الخادم الوكيل، http أو httpshttp
--http.proxy.userstringمستخدم الخادم الوكيلnull
--http.response.maxResultsintegerالحد الأقصى للنتائج لكل طلب http، وأي رقم أقل من 0 أو يساويه يعني عدم وجود حد-1
--http.response.pageLimitintegerالحد الأقصى لعدد صفحات النتائج التي تعاد لكل مورد، وأي رقم أقل من 0 أو يساويه يعني عدم وجود حد20
--indirect.depth.maxintegerالحد الأقصى لعمق الاستعلامات غير المباشرة: طرق العرض والاستعلامات الفرعية5
-i, --infilestringملف الإدخال (ملف IQL) الذي تقرأ منه الاستعلامات{stdin}
-q, --iqldatastringملف السياق (البيانات) لاستخدام القوالب (ملف json أو jsonnet)
--loglevelstringمستوى السجل، ويجب أن يكون أحد {panic, fatal, error, warn, info, debug, trace} (ويُقبل warning كاسم مستعار لـ warn)fatal
--mcp.configstringكائن تكوين خادم MCP بتنسيق JSON / YAML (stackql mcp وstackql srv){}
--mcp.log.formatstringترميز سجل تدقيق MCP، jsonl أو otel (إدخالات سجل OTLP/JSON)؛ ويتجاوز server.audit.format في --mcp.config. راجع تنسيق السجل. متاح في StackQL من الإصدار v0.11.660 فصاعدًا.jsonl
--mcp.protocol.versionstringأحدث مراجعة لبروتوكول MCP يتم الإعلان عنها: auto أو 2026-07-28 (في وضع بدون جلسات فقط) أو مراجعة أقدم مثل 2025-11-25؛ ويتجاوز server.protocol_version في --mcp.config. راجع قفل المراجعة. متاح في StackQL من الإصدار v0.12.732 فصاعدًا.auto
--mcp.server.typestringنوع خادم MCP، أحد {http, stdio, reverse_proxy}. راجع نوع خادم MCP.http
--metadatattlintegerمدة صلاحية (TTL) مستندات بيانات التعريف المخزنة مؤقتًا، بالثواني3600
--namespacesstringسلسلة نصية بتنسيق JSON / YAML تمثل مساحات الأسماء للتخزين المؤقت وطرق العرض وغيرها{}
--offlineflagالعمل دون اتصال باستخدام البيانات المخزنة مؤقتًاfalse
-f, --outfilestringملف الإخراج الذي تكتب فيه النتائج{stdout}
-o, --outputstringتنسيق الإخراج، ويجب أن يكون أحد {json, jsonl, table, csv, text, otel} (ويُقبل ndjson كاسم مستعار لـ jsonl). يصدر التنسيق otel إدخالات سجل OpenTelemetry، راجع أوضاع الإخراج؛ وهو متاح في StackQL من الإصدار v0.11.660 فصاعدًا. عند تكوين exporter في --otel.config، يتم أيضًا دفع إدخالات otel إلى نقطة النهاية تلكtable
--otel.configstringسلسلة نصية بتنسيق JSON / YAML لتكوين تنسيق الإخراج otel؛ تدفع المفاتيح exporter.endpoint وexporter.headers وexporter.timeout_ms وexporter.batch_size الإدخالات إلى نقطة نهاية سجلات OTLP/HTTP، راجع الدفع إلى نقطة نهاية OTLP. متاح في StackQL من الإصدار v0.12.732 فصاعدًا{}
--previewstringسلسلة نصية بتنسيق JSON لتمكين ميزات المعاينة. يعرض {"unstable": true} العلاقات stackql_unstable_<provider>.<service>.<resource> المبنية على مستندات، والتي يحلها omnisdk ويشغلها مباشرة من مستندات الموفرين مع بث الصفوف فور إنتاجها؛ وتضبط المفاتيح المتبقية (batchSize وflushInterval وendpoint وinsecureSkipTLSVerify) تلك الواجهة الخلفية. ميزات المعاينة غير مستقرة: قد يتغير السلوك وبناء الجملة والإخراج أو يتعطل بين الإصدارات دون سابق إنذار، لذا لا تعتمد عليها في بيئة الإنتاج. من الإصدار v1.0، يعرض التفعيل الاختياري نفسه العلاقتين stackql_preview.iac.run وstackql_preview.iac.destroy، اللتين تطبقان مجموعة موارد معلنة وتزيلانها عبر omnisdk مع الاحتفاظ بالحالة تحت المسار الجذر للتطبيق. راجع ميزات المعاينة{}
--providerstringالموفر الافتراضي الأولي. على سبيل المثال، مع --provider github، يُحل repos.repos إلى github.repos.repos دون جملة USE سابقة. لا يجري المصادقة مع الموفر.لا يوجد
--querycachesizeintegerحجم ذاكرة التخزين المؤقت LRU لخطط الاستعلامات بعدد الإدخالات10000
--registrystringسلسلة نصية بتنسيق JSON / YAML لتكوين موقع سجل الموفرين والتحقق من توقيعات مستندات الموفرينراجع --registry
--sessionstringسلسلة نصية بتنسيق JSON / YAML تمثل تكوين الجلسة{}
--sqlBackendstringسلسلة نصية بتنسيق JSON / YAML تمثل تكوين نظام واجهة SQL الخلفيةراجع --sqlBackend
--store.txnstringسلسلة نصية بتنسيق JSON / YAML تمثل تكوين مخزن Txn{}
--tls.CABundlestringمسار حزمة شهادات CA، وإذا لم يتم تحديده تستخدم الإعدادات الافتراضية للنظام
--tls.allowInsecureflagالسماح بالثقة في الشهادات غير الآمنة (غير موصى به)
--upstream.errorsstringسياسة بتنسيق JSON / YAML للتسامح الصريح مع حالات استجابة HTTP عند القراءة من الموفرين. راجع --upstream.errors.{}
--varstringمتغيرات خارجية تقدم كأزواج مفاتيح وقيم لتحميلها في استعلامات StackQL من خلال ملفات بيانات jsonnet
-v, --verboseflagإخراج مفصل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. يفضل استخدام رمز حالة دقيق عندما لا تتوقع سوى فشل واحد.