Esta página foi traduzida do inglês com assistência de IA. Se houver diferenças entre as duas, a versão em inglês é a referência.
SET
Atribui uma variável de sessão ou define configurações de runtime para a sessão atual. Disponível a partir do StackQL v1.0.
Veja também:
[UNSET] [ Variáveis de sessão ] [ Sessões de provider ] [IDENTIFIER]
Sintaxe
setStatement::=
setExpression::=
SET [ SESSION ] <target> = { <literal> | DEFAULT | <reference> } [, <target> = { <literal> | DEFAULT | <reference> } ...];
target
Um identificador simples (region), um nome entre aspas duplas ("providers.saved") ou um caminho de configuração entre aspas duplas com prefixo de cifrão ("$.auth.aws.password").
literal
Uma string, um número, um booleano ou null. As strings ficam entre aspas simples. Arrays e objetos não são valores escalares; armazene um documento JSON como uma string.
DEFAULT
Redefine o alvo, o equivalente a UNSET. Um null explícito é um valor armazenado, não uma redefinição.
reference
Uma referência "$name" entre aspas duplas a uma variável existente, por exemplo SET "$.providers.production" = "$providers.saved";.
SESSION
Opcional, e o único escopo que o StackQL tem. SET SESSION name = ... e SET name = ... são a mesma instrução: toda atribuição pertence à sessão atual e a nada mais. A palavra-chave existe para que os scripts tenham a mesma leitura que em bancos de dados nos quais SET SESSION e SET GLOBAL são diferentes. SET GLOBAL é analisada sem erro, mas é rejeitada com configuration scope "global" is not supported; use SESSION, porque não há estado compartilhado entre sessões.
As atribuições de uma lista de SET são aplicadas em ordem e não formam uma transação: se a segunda atribuição de uma lista falhar, a primeira continua em vigor.
Alvos
| Alvo | Efeito |
|---|---|
name ou "name" | Armazena uma variável de sessão escalar, desreferenciada como $name nas instruções seguintes. Pontos, por si só, não selecionam configuração: "providers.saved" é uma variável chamada providers.saved. A grafia antiga "variables.name" é um alias de name. |
"$.auth.<provider>.<field>" | Define um campo do contexto de autenticação do provider nesta sessão. Os campos são as chaves do objeto --auth desse provider, por exemplo credentialsenvvar, password ou token_url. |
"$.providers.<alias>" | Vincula um alias de provider com credenciais, rótulo de tenancy, valores padrão de parâmetros e ajustes de desempenho próprios. O valor é um documento JSON em uma string; consulte Sessões de provider. |
"$.secrets.<name>" | Armazena um segredo no repositório de segredos da sessão. O valor é uma string literal, normalmente um documento JSON auth, referenciado a partir de um alias de provider como auth_secret. |
"$.secret_store" | Seleciona um repositório de segredos persistente do sistema operacional, {"backend":"os","namespace":"..."}. Requer a opção de operador --allow-persistent-secrets. |
Todas as formas afetam somente a sessão atual. Conexões independentes com um servidor srv não veem as atribuições umas das outras, e cada solicitação MCP é uma sessão própria; por isso, configure e consulte em um único lote de instruções ao usar o servidor MCP.
Exemplos
Definir variáveis de sessão
Cada instrução armazena um escalar com o nome informado, e o valor mantém seu tipo: region é uma string, minimum_count um inteiro e enabled um booleano. null é armazenado como valor, então $optional_value é resolvida depois como NULL do SQL em vez de falhar por não estar definida. A última instrução atribui duas variáveis em uma única lista.
SET region = 'ap-southeast-2';
SET minimum_count = 3;
SET enabled = true;
SET optional_value = null;
SET suffix = 'East', some_id = 42;
Tornar explícito o escopo da sessão
As duas primeiras instruções são idênticas: SESSION nomeia o único escopo que existe, e as duas atribuições duram até que a variável seja removida ou a sessão termine. Use a palavra-chave quando um script precisar ter a mesma leitura que em um banco de dados que diferencia configurações de sessão e configurações globais. A instrução comentada aparece para contraste: ela não atribui nada e falha com configuration scope "global" is not supported; use SESSION, porque nenhum estado é compartilhado entre sessões.
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
*/
Usar uma variável em uma consulta
Desreferencie uma variável com $name, sem aspas, em qualquer posição de expressão. Os valores mantêm seu tipo: as strings são escapadas como literais SQL, e números, booleanos e null são repassados sem alteração. As variáveis em uma cláusula WHERE são resolvidas antes que a solicitação seja planejada, então são enviadas ao provider como literais.
SET project = 'stackql-demo';
SET zone = 'australia-southeast1-a';
SELECT name, status FROM google.compute.instances
WHERE project = $project AND zone = $zone;
Redefinir uma variável
DEFAULT remove a variável, exatamente como UNSET faz, então um $region posterior falha com variable "$region" is not defined até que ela seja definida novamente; a consulta comentada mostra essa falha. Isso é diferente de atribuir null, que mantém a variável com o valor 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
*/
Copiar um valor de outra variável
O lado direito pode ser uma referência entre aspas duplas a uma variável existente, o que copia o valor que ela contém naquele momento. Aqui, uma vinculação de provider é primeiro armazenada como uma variável comum chamada providers.saved (os pontos não a tornam configuração) e depois ativada ao ser copiada para o caminho $.providers.production. Remover a cópia salva depois não afeta a vinculação ativa.
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";
Substituir um campo de credencial nesta sessão
O contexto de autenticação de um provider é o objeto fornecido para ele por meio de --auth na inicialização. Um caminho sob $.auth substitui um campo desse objeto pelo restante da sessão e mantém os outros campos como estavam. Aqui, o provider do GitHub passa a apontar para outra variável de ambiente, que contém um token de somente leitura; a variável é lida do ambiente do processo do StackQL, e as consultas seguintes em github.* a usam até que o campo seja removido ou a sessão termine.
SET "$.auth.github.credentialsenvvar" = 'GITHUB_TOKEN_READONLY';
Vincular um alias de provider
Um alias de provider é uma segunda instância de um provider, configurada de forma independente, usada no lugar do nome do provider nas consultas. O valor é um documento JSON em uma string: provider nomeia o provider subjacente, tenancy rotula a conta, auth é um bloco de credenciais no mesmo formato de --auth, e params fornece valores padrão para parâmetros de solicitação, como region. As consultas em production.s3.buckets passam então a ser executadas com essas credenciais, enquanto aws.s3.buckets mantém a configuração de inicialização. A lista completa de chaves está em Sessões de provider.
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;