Перейти до основного вмісту
Перекладена сторінка

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

Глобальні прапорці

Команди 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 для налаштування обробки службових запитів СКБД{}
-d, --delimiterstringРоздільник для виводу csv. Лише один символ. Ігнорується для всіх форматів виводу, крім csv,
--dryrunflagПрапорець dryrun; виконується лише препроцесор, повертається вивід, сформований із шаблонуfalse
--env.filestringНеобов'язковий файл у стилі dotenv, який завантажується в середовище процесу під час запуску (для всіх команд); інструмент MCP reload_credentials повторно завантажує його на вимогу. Відсутність файлу допускається; ключі з порожніми значеннями пропускаються; наявні змінні перезаписуються. Не зчитується з .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Об'єкт конфігурації JSON / YAML для сервера MCP (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
--metadatattlintegerTTL кешованих документів метаданих, у секундах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 і новіших версіях. Якщо в --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 з такими ключами:

КлючОписЗа замовчуванням
urlURL реєстру. Якщо не вказано, використовується публічний реєстр провайдерів 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​

./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". Значення за замовчуванням {} не додає жодних винятків до звичайної обробки відповідей upstream у рушії. Це налаштування не виконує повторних спроб для невдалих запитів і не застосовується до змінення даних або обміну даними автентифікації.

Проігнорована відповідь не додає рядків. Інші операції читання в запиті все одно можуть повертати рядки, тому успішний запит може повернути неповні результати. 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;"

У тесті запит до API на отримання співавторів одного репозиторію повертає HTTP 500. Запит однаково повертає рядки співавторів для інших репозиторіїв, а stderr містить ignoring upstream response: 500 INTERNAL SERVER ERROR. Якщо очікується лише одна помилка, віддавайте перевагу точному коду статусу.