本頁面由英文在 AI 協助下翻譯而成。若兩者有出入,請以英文版本為準。
全域旗標
StackQL 命令都接受全域旗標,但部分旗標只適用於特定模式。可在命令列上設定這些旗標,或在支援的情況下,於 StackQL 初始化檔案(.stackqlrc)中設定。--pgsrv.* 旗標列於 PostgreSQL 伺服器選項。
| 旗標 | 資料型別 | 描述 | 預設值 |
|---|---|---|---|
--access.config | string | 呼叫端存取設定,為 JSON 封套 {"path": "/path/to/access.json"}(也接受單純的檔案路徑)。啟用存取管理:呼叫端透過 JWT、靜態 bearer 權杖、相互 TLS 或本機 OS 身分進行驗證,陳述式則依據政策規則進行授權。本機權杖憑證從 STACKQL_CALLER_TOKEN 讀取。自 StackQL v1.0 發行版本起提供。 | |
--allow-persistent-secrets | flag | 允許工作階段使用 SET "$.secret_store" 選取持續性 OS 祕密存放區(macOS Keychain、Linux Secret Service 或 Windows Credential Manager)。即使設定此旗標,平面檔案存放區仍會遭拒。請參閱 Provider 工作階段與祕密。自 StackQL v1.0 發行版本起提供。 | false |
--allow-secret-dereference | flag | 允許在 SQL 運算式中解除參考祕密和憑證值("$secrets.name"、"$auth.provider.field"),其後果是這些值可能進入結果、記錄和持續保存的查詢成品。一般的 Provider 驗證不需要此旗標。請參閱 SQL 中的祕密值。自 StackQL v1.0 發行版本起提供。 | false |
--apirequesttimeout | integer | API 要求逾時(秒),0 表示不逾時 | 45 |
--approot | string | 應用程式設定和快取的根路徑 | {cwd}/.stackql |
--approotfilemode | uint32 | 應用程式設定和快取的檔案模式 | 493 |
--auth | string | json 格式的 auth 內容鍵值對 | |
--cachekeycount | integer | 快取的初始鍵數量 | 100 |
--configfile | string | 設定檔的完整路徑 | {cwd}/.stackqlrc |
--cpuprofile | string | cpuprofile 檔案,若為空則不使用 | null |
--dataflow.dependency.max | int | 指定查詢的資料流相依性深度上限 | 50 |
--dataflow.components.max | int | 指定查詢的資料流弱連通元件數上限 | 50 |
--dbInternal | string | 用來設定 DBMS 內部維護查詢處理方式的 JSON / YAML 字串 | {} |
-d, --delimiter | string | csv 輸出的分隔符號。僅限單一字元。所有非 csv 輸出都會忽略此旗標 | , |
--dryrun | flag | dryrun 旗標;只執行前置處理器,並傳回範本化的輸出 | false |
--env.file | string | 選用的 dotenv 樣式檔案,會在啟動時載入處理程序環境(所有命令);MCP reload_credentials 工具會視需要重新載入此檔案。檔案不存在時不會出錯;值為空的鍵會略過;現有的變數會被覆寫。不會從 .stackqlrc 載入。在 StackQL v0.10.542 之後的發行版本中提供。 | null |
--execution.concurrency.limit | int | 查詢執行的並行限制 | 1 |
--export.alias | string | 匯出別名前置詞(命名空間或 schema) | |
--gc | string | 表示 GC 設定的 JSON / YAML 字串 | {} |
-H, --hideheaders | flag | 停用資料行標頭,僅在使用 --output csv 或 --output text 時有效 | false |
--http.log.enabled | flag | 在終端機中顯示 http 要求資訊 | false |
--http.proxy.host | string | Proxy 主機(留空表示不使用 Proxy) | null |
--http.proxy.password | string | Proxy 密碼 | null |
--http.proxy.port | integer | Proxy 連接埠,任何小於或等於 0 的數字都會使用指定協定的預設連接埠(例如 http -> 80) | -1 |
--http.proxy.scheme | string | Proxy 協定,http 或 https | http |
--http.proxy.user | string | Proxy 使用者 | 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 伺服器(stackql mcp 和 stackql srv)的 JSON / YAML 設定物件 | {} |
--mcp.log.format | string | MCP 稽核記錄的編碼,jsonl 或 otel(OTLP/JSON 記錄項目);會覆寫 --mcp.config 中的 server.audit.format。請參閱記錄格式。自 StackQL v0.11.660 發行版本起提供。 | jsonl |
--mcp.protocol.version | string | 宣告的最新 MCP 協定修訂版本,可為 auto、2026-07-28(僅限無工作階段模式)或較舊的修訂版本,例如 2025-11-25;會覆寫 --mcp.config 中的 server.protocol_version。請參閱固定修訂版本。自 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 發行版本起提供。若在 --otel.config 中設定了匯出工具,otel 記錄項目也會推送至該端點 | table |
--otel.config | string | 設定 otel 輸出格式的 JSON / YAML 字串;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 直接從 Provider 文件解析並執行,資料列會在產生時以串流方式傳回;其餘的鍵(batchSize、flushInterval、endpoint、insecureSkipTLSVerify)用於調整該後端。預覽功能並不穩定:行為、語法和輸出可能在發行版本之間變更或中斷,且不另行通知,因此請勿在生產環境中依賴此功能。自 v1.0 起,同一個選擇加入設定也會公開 stackql_preview.iac.run 和 stackql_preview.iac.destroy 關聯,這兩個關聯會透過 omnisdk 套用和拆除宣告的資源集,並將狀態保存在應用程式根目錄下。請參閱預覽功能 | {} |
--provider | string | 初始預設 Provider。例如,使用 --provider github 時,repos.repos 會解析為 github.repos.repos,不需要先執行 USE 陳述式。不會向 Provider 進行驗證。 | 無 |
--querycachesize | integer | 查詢計畫 LRU 快取的大小(項目數) | 10000 |
--registry | string | 設定 Provider 登錄庫位置和 Provider 文件簽章驗證的 JSON / YAML 字串 | 請參閱 --registry |
--session | string | 表示工作階段設定的 JSON / YAML 字串 | {} |
--sqlBackend | string | 表示 SQL 後端系統設定的 JSON / YAML 字串 | 請參閱 --sqlBackend |
--store.txn | string | 表示 Txn 存放區設定的 JSON / YAML 字串 | {} |
--tls.CABundle | string | CA 套件組合的路徑,未指定時使用系統預設值 | |
--tls.allowInsecure | flag | 允許信任不安全的憑證(不建議) | |
--upstream.errors | string | 用於在 Provider 讀取時明確容許特定 HTTP 回應狀態的 JSON / YAML 政策。請參閱 --upstream.errors。 | {} |
--var | string | 以鍵值對形式提供的外部變數,透過 jsonnet 資料檔案載入 StackQL 查詢 | |
-v, --verbose | flag | 詳細輸出 | false |
-h, --help | stackql 的內容相關說明 | ||
--version | 顯示 StackQL 程式的版本 |
--colorscheme 已淘汰,不再變更 shell 色彩。--usenonpreferredapis 仍可接受,但在目前的引擎中不會改變 API 的選擇。
--registry
--registry 旗標設定從何處讀取 Provider 文件,以及是否驗證其簽章。值為包含下列鍵的 JSON 字串:
| 鍵 | 描述 | 預設值 |
|---|---|---|
url | 登錄庫 URL。省略時使用公用 StackQL Provider 登錄庫。 | 公用登錄庫 |
localDocRoot | 存放 Provider 文件的本機目錄,會直接讀取,而非從登錄庫下載。用於開發 Provider 時。 | |
srcPrefix | 登錄庫根目錄下存放 Provider 來源文件的路徑前置詞。 | src |
verifyConfig.nopVerify | true 會略過簽章驗證。設為 false 時,每份讀取的 Provider 和服務文件都必須帶有內嵌的 ML-DSA-65(FIPS 204)簽章,包括以文件為基礎的預覽關聯。 | true |
verifyConfig.publicKeys | 將金鑰 ID 對應至十六進位編碼 ML-DSA-65 公開金鑰的 JSON 物件,適用於私人登錄庫。它會取代內嵌的生產環境金鑰;明確指定空物件會產生錯誤。 | 內嵌金鑰 |
範例:要求已簽署的 Provider 文件
針對從公用登錄庫讀取的每份 Provider 和服務文件啟用驗證,並以內嵌的生產環境金鑰進行檢查:
stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell
範例:從本機目錄讀取未簽署的文件
將登錄庫指向開發中的 Provider 文件目錄。這些文件未經簽署,因此驗證保持關閉:
stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell
簽章驗證自 StackQL v1.0 發行版本起提供,且預設為關閉。簽章涵蓋文件確切的 YAML 位元組,因此任何編輯(包括格式或換行字元的變更)都會使簽章失效;請使用登錄庫的 pqsig sign-doc 工具重新簽署。未簽署的本機開發文件必須保持 nopVerify: true。先前的憑證選項和 .sig sidecar 檔案已不再使用,僅以 sidecar 發行的封存檔必須重新發行,才能在驗證模式下使用。驗證會在讀取文件時確認其真實性;封存檔的下載和解壓縮不在涵蓋範圍內。
--sqlBackend
--sqlBackend 旗標為 StackQL 設定外部 SQL 後端,讓您使用外部資料庫引擎(例如 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
範例:使用 Databricks PostgreSQL 介面
Databricks 提供與 PostgreSQL 相容的介面,可作為 StackQL 的 SQL 後端。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
使用者名稱或密碼中的特殊字元(例如 @)必須在 DSN 中進行 URL 編碼(例如 @ 會變成 %40)。
--upstream.errors
使用 http.ignoreStatusCodes 列出 Provider 讀取時應明確容許的 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;"
在此測試中,某個存放庫的 collaborators 要求會傳回 HTTP 500。查詢仍會傳回其他存放庫的協作者資料列,而 stderr 會包含 ignoring upstream response: 500 INTERNAL SERVER ERROR。若預期只有一種失敗,建議使用確切的狀態碼。