グローバルフラグ

グローバルフラグは、StackQL アプリケーションの実行時の動作を指定します。これらのフラグは、StackQL アプリケーションの起動時（対話型シェルモードまたは非対話型の exec モード）にコマンドラインで設定するか、StackQL の初期化ファイル（.stackqlrc）から読み込まれます。フラグは次のとおりです：

フラグ	データ型	説明	デフォルト
--access.config	string	呼び出し元のアクセス設定。JSON エンベロープ {"path": "/path/to/access.json"} で指定します（ファイルパスをそのまま指定することもできます）。アクセス管理を有効にします。呼び出し元は JWT、静的 Bearer トークン、相互 TLS、ローカル OS ID のいずれかで認証され、文はポリシールールに照らして認可されます。ローカルのトークン認証情報は STACKQL_CALLER_TOKEN から読み込まれます。StackQL v1.0 以降で利用できます。
--acid	string	ACID の設定を表す JSON / YAML 文字列	{}
--allow-persistent-secrets	flag	セッションが SET "$.secret_store" で永続的な OS シークレットストア（macOS Keychain、Linux Secret Service、Windows Credential Manager）を選択できるようにします。フラットファイルのストアは、このフラグがあっても拒否されます。プロバイダーセッションとシークレットを参照してください。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	JSON 形式の auth コンテキストのキーと値のペア
--cachekeycount	integer	キャッシュの初期キー数	100
--configfile	string	設定ファイルのフルパス	{cwd}/.stackqlrc
--cpuprofile	string	cpuprofile ファイル。空の場合はなし	null
--dataflow.dependency.max	int	1 つのクエリにおけるデータフロー依存関係の最大深度	50
--dataflow.components.max	int	1 つのクエリにおけるデータフローの弱連結成分の最大数	50
--dbInternal	string	DBMS のハウスキーピングクエリの処理を設定する JSON / YAML 文字列	{}
-d, --delimiter	string	CSV 出力の区切り文字。1 文字のみ。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	エクスポートのエイリアスのプレフィックス（名前空間またはスキーマ）
--gc	string	GC の設定を表す JSON / YAML 文字列	{}
-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	ログレベル。fatal のいずれかである必要があります	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 サーバータイプ。reverse_proxy のいずれかです。MCP サーバータイプを参照してください。	http
--metadatattl	integer	キャッシュされたメタデータドキュメントの TTL（秒）	3600
--namespaces	string	キャッシュ、ビューなどの名前空間を表す JSON / YAML 文字列	{}
--offline	flag	キャッシュされたデータを使用してオフラインで動作します	false
-f, --outfile	string	結果を書き込む出力ファイル	{stdout}
-o, --output	string	出力形式。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 によってプロバイダードキュメントから直接解決されて実行され、行は生成されるそばからストリーミングされます。残りのキー（batchSize、flushInterval、endpoint、insecureSkipTLSVerify）は、そのバックエンドを調整します。プレビュー版の機能は安定していません。動作、構文、出力はリリース間で予告なく変更されたり動作しなくなったりする可能性があるため、本番環境ではこれに依存しないでください。v1.0 以降では、同じオプトインによって stackql_preview.iac.run リレーションと stackql_preview.iac.destroy リレーションも公開されます。これらは omnisdk を通じて宣言されたリソースセットを適用および破棄し、ステートはアプリケーションルートの下に保持されます。プレビュー版の機能を参照してください	{}
--querycachesize	integer	クエリ計画の LRU キャッシュのサイズ（エントリ数）	10000
--registry	string	プロバイダーレジストリの場所と、プロバイダードキュメントの署名検証を設定する 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	安全でない証明書の信頼を許可します（非推奨）
--var	string	jsonnet データファイルを通じて StackQL クエリに取り込むための、キーと値のペアとして指定する外部変数
-v, --verbose	flag	詳細出力	false
-h, --help		stackql のコンテキストに応じたヘルプ
--version		StackQL プログラムのバージョンを表示します

--registry

--registry フラグは、プロバイダードキュメントの読み込み元と、その署名を検証するかどうかを設定します。値は、次のキーを持つ JSON 文字列です：

キー	説明	デフォルト
url	レジストリの URL。省略した場合は、StackQL の公開プロバイダーレジストリが使用されます。	公開レジストリ
localDocRoot	プロバイダードキュメントを格納するローカルディレクトリ。レジストリからダウンロードする代わりに、ここから読み込みます。プロバイダーを開発する際に使用します。
srcPrefix	プロバイダーのソースドキュメントが置かれている、レジストリルート配下のパスプレフィックス。	src
verifyConfig.nopVerify	true の場合は署名の検証をスキップします。false に設定すると、読み込まれるすべてのプロバイダードキュメントとサービスドキュメントに、組み込みの ML-DSA-65（FIPS 204）署名が必要になります。ドキュメントに基づくプレビュー版のリレーションも対象です。	true
verifyConfig.publicKeys	プライベートレジストリ用に、キー ID を 16 進エンコードされた ML-DSA-65 公開鍵にマッピングする JSON オブジェクト。組み込みの本番用キーを置き換えます。明示的な空のオブジェクトはエラーになります。	組み込みのキー

例：署名付きプロバイダードキュメントを必須にする

公開レジストリから読み込まれるすべてのプロバイダードキュメントとサービスドキュメントについて、検証を有効にします。検証には、組み込みの本番用キーが使用されます：

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 のままにする必要があります。以前の証明書オプションと .sig サイドカーファイルは使用されなくなりました。サイドカーのみで公開されたアーカイブは、検証付きで使用する前に再公開する必要があります。検証は、読み込み時にドキュメントを認証します。アーカイブのダウンロードと展開は対象外です。

--sqlBackend

--sqlBackend フラグは StackQL の外部 SQL バックエンドを設定し、デフォルトの組み込み SQL エンジンの代わりに、外部のデータベースエンジン（PostgreSQL など）を使用できるようにします。これは、クエリ処理、永続ストレージ、既存のデータベースインフラストラクチャとの統合に外部データベースを活用する場合に便利です。

値は、次のキーを持つ 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 は、StackQL の SQL バックエンドとして使用できる PostgreSQL 互換のインターフェイスを公開しています。DSN には、Databricks の認証情報を含む標準の PostgreSQL 接続文字列形式を使用します：

./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 になります）。