SET

セッション変数を割り当てるか、現在のセッションのランタイム設定を構成します。StackQL v1.0 以降で利用できます。

関連項目：
[UNSET] [ セッション変数 ] [ プロバイダーセッション ] [IDENTIFIER]

---

構文

setStatement::=

setExpression::=

 
 

SET [ SESSION ] <target> = { <literal> | DEFAULT | <reference> } [, <target> = { <literal> | DEFAULT | <reference> } ...];

target
プレーンな識別子（region）、二重引用符で囲んだ名前（"providers.saved"）、または二重引用符で囲み、ドル記号を接頭辞に持つ設定パス（"$.auth.aws.password"）のいずれかです。

literal
文字列、数値、ブール値、または null です。文字列は単一引用符で囲みます。配列とオブジェクトはスカラー値ではありません。JSON ドキュメントは文字列として保持してください。

DEFAULT
ターゲットをリセットします。UNSET と同等です。明示的な null は保存される値であり、リセットではありません。

reference
既存の変数への、二重引用符で囲んだ "$name" 形式の参照です。たとえば SET "$.providers.production" = "$providers.saved"; のように指定します。

SESSION
省略可能で、StackQL が持つ唯一のスコープです。SET SESSION name = ... と SET name = ... は同じ文です。すべての割り当ては現在のセッションに属し、それ以外には属しません。このキーワードは、SET SESSION と SET GLOBAL が異なるデータベースと同じようにスクリプトを読めるようにするために存在します。SET GLOBAL は解析されますが、セッション間で共有される状態がないため、configuration scope "global" is not supported; use SESSION というエラーで拒否されます。

1 つの SET リスト内の割り当ては順番に適用され、トランザクションではありません。リスト内の 2 番目の割り当てが失敗しても、1 番目の割り当ては有効なままです。

ターゲット

ターゲット	効果
name または "name"	スカラーのセッション変数を保存します。この変数は、後続の文で $name として参照します。ドットだけでは設定は選択されません。"providers.saved" は providers.saved という名前の変数です。古い "variables.name" という表記は name のエイリアスです。
"$.auth.<provider>.<field>"	このセッションについて、プロバイダーの認証コンテキストのフィールドを 1 つ設定します。フィールドは、そのプロバイダーの --auth オブジェクトのキーです（たとえば credentialsenvvar、password、token_url）。
"$.providers.<alias>"	独自の認証情報、テナンシーラベル、パラメーターのデフォルト値、チューニング設定を持つプロバイダーエイリアスをバインドします。値は文字列に格納した JSON ドキュメントです。プロバイダーセッションを参照してください。
"$.secrets.<name>"	セッションのシークレットストアにシークレットを保存します。値はリテラル文字列で、通常は JSON の auth ドキュメントです。プロバイダーエイリアスからは auth_secret として参照します。
"$.secret_store"	永続的な OS のシークレットストア（{"backend":"os","namespace":"..."}）を選択します。運用者が設定するフラグ --allow-persistent-secrets が必要です。

どの形式も現在のセッションにのみ影響します。srv サーバーへの独立した接続は、互いの割り当てを参照できません。また、MCP リクエストはそれぞれが独立したセッションです。そのため、MCP サーバーを使用する場合は、1 つの文のバッチで設定とクエリを行ってください。

---

例

セッション変数を設定する

各文は、指定した名前で 1 つのスカラーを保存し、値はその型を保持します。region は文字列、minimum_count は整数、enabled はブール値です。null は値として保存されるため、後で $optional_value は未定義として失敗するのではなく、SQL の NULL に解決されます。最後の文は、1 つのリストで 2 つの変数を割り当てます。

SET region = 'ap-southeast-2';
SET minimum_count = 3;
SET enabled = true;
SET optional_value = null;
SET suffix = 'East', some_id = 42;

セッションスコープを明示する

最初の 2 つの文は同一です。SESSION は存在する唯一のスコープを指定するもので、どちらの割り当ても、変数が解除されるかセッションが終了するまで有効です。セッション設定とグローバル設定を区別するデータベースと同じようにスクリプトを読めるようにしたい場合に、このキーワードを使用します。コメントアウトされた文は比較のために示しています。この文は何も割り当てず、セッション間で共有される状態がないため、configuration scope "global" is not supported; use SESSION というエラーで失敗します。

SET region = 'ap-southeast-2';
SET SESSION region = 'ap-southeast-2';

/*
SET GLOBAL region = 'ap-southeast-2';
-- FAILS with configuration scope "global" is not supported; use SESSION
*/

クエリで変数を使用する

任意の式の位置で、引用符を付けずに $name で変数を参照します。値はその型を保持します。文字列は SQL リテラルとしてエスケープされ、数値、ブール値、null はそのまま渡されます。WHERE 句の変数はリクエストの計画が作成される前に解決されるため、リテラルと同様にプロバイダーにプッシュされます。

SET project = 'stackql-demo';
SET zone = 'australia-southeast1-a';

SELECT name, status FROM google.compute.instances
WHERE project = $project AND zone = $zone;

変数をリセットする

DEFAULT は UNSET とまったく同じように変数を削除します。そのため、再び設定されるまで、後続の $region は variable "$region" is not defined というエラーで失敗します。コメントアウトされたクエリはその失敗を示しています。これは null を割り当てる場合とは異なります。その場合、変数は NULL 値を持ったまま残ります。

SET region = 'ap-southeast-2';
SET region = DEFAULT;

/*
SELECT name FROM aws.s3.buckets WHERE region = $region;
-- FAILS with variable "$region" is not defined
*/

別の変数から値をコピーする

右辺には、既存の変数への二重引用符で囲んだ参照を指定できます。この場合、その時点で変数が保持している値がコピーされます。ここでは、まずプロバイダーのバインディングを providers.saved という名前の通常の変数として保存し（ドットがあっても設定にはなりません）、次にそれを $.providers.production パスにコピーして有効にします。その後で保存したコピーを削除しても、有効なバインディングには影響しません。

SET "providers.saved" = '{"provider":"aws","tenancy":"production-account","auth":{"type":"aws_signing_v4","access_key_id_env_var":"PRODUCTION_AWS_ACCESS_KEY_ID","secret_access_key_env_var":"PRODUCTION_AWS_SECRET_ACCESS_KEY"}}';
SET "$.providers.production" = "$providers.saved";
UNSET "providers.saved";

このセッションで認証情報フィールドを上書きする

プロバイダーの認証コンテキストは、起動時に --auth で渡されるオブジェクトです。$.auth の下のパスは、セッションの残りの期間、そのオブジェクトのフィールドを 1 つ置き換え、他のフィールドはそのまま残します。ここでは、GitHub プロバイダーが、読み取り専用のトークンを保持する別の環境変数を参照するように設定します。この変数は StackQL プロセスの環境から読み取られます。フィールドが解除されるかセッションが終了するまで、以降の github.* に対するクエリではこの変数が使用されます。

SET "$.auth.github.credentialsenvvar" = 'GITHUB_TOKEN_READONLY';

プロバイダーエイリアスをバインドする

プロバイダーエイリアスは、独立して構成されたプロバイダーの 2 つ目のインスタンスで、クエリではプロバイダー名の代わりに使用します。値は文字列に格納した JSON ドキュメントです。provider は基になるプロバイダーを指定し、tenancy はアカウントのラベルを指定します。auth は --auth と同じ形の認証情報ブロックで、params は region などのリクエストパラメーターのデフォルト値を指定します。その後、production.s3.buckets に対するクエリはその認証情報で実行され、aws.s3.buckets は起動時の構成を維持します。キーの完全な一覧はプロバイダーセッションにあります。

SET "$.providers.production" = '{
  "provider": "aws",
  "tenancy": "production-account",
  "auth": {
    "type": "aws_signing_v4",
    "access_key_id_env_var": "PRODUCTION_AWS_ACCESS_KEY_ID",
    "secret_access_key_env_var": "PRODUCTION_AWS_SECRET_ACCESS_KEY"
  },
  "params": {"region": "ap-southeast-2"}
}';

SELECT name FROM production.s3.buckets;