Pular para o conteúdo principal
Página traduzida

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.

Opções globais

As opções globais especificam o comportamento do programa em tempo de execução para a aplicação StackQL; essas opções são definidas na linha de comando quando a aplicação StackQL é iniciada (no modo interativo/shell ou no modo exec não interativo) ou são obtidas do arquivo de inicialização do StackQL (.stackqlrc). As opções incluem:

OpçãoTipo de dadosDescriçãoValor padrão
--access.configstringConfiguração de acesso de chamadores, um envelope JSON {"path": "/path/to/access.json"} (um caminho de arquivo simples também é aceito). Habilita o gerenciamento de acesso: os chamadores são autenticados por JWT, token bearer estático, TLS mútuo ou identidade local do SO, e as instruções são autorizadas com base em regras de política. As credenciais de token locais são lidas de STACKQL_CALLER_TOKEN. Disponível a partir do StackQL v1.0.
--acidstringString JSON / YAML que representa a configuração ACID{}
--allow-persistent-secretsflagPermite que uma sessão selecione um repositório de segredos persistente do SO (macOS Keychain, Linux Secret Service ou Windows Credential Manager) com SET "$.secret_store". Repositórios em arquivo simples são recusados mesmo com a opção. Consulte Sessões de provider e segredos. Disponível a partir do StackQL v1.0.false
--allow-secret-dereferenceflagPermite que valores de segredos e de credenciais sejam desreferenciados em expressões SQL ("$secrets.name", "$auth.provider.field"), com a consequência de que eles podem aparecer em resultados, logs e artefatos de consulta persistidos. Não é necessária para a autenticação normal de providers. Consulte Valores de segredos no SQL. Disponível a partir do StackQL v1.0.false
--apirequesttimeoutintegerTempo limite das solicitações de API em segundos, 0 para nenhum tempo limite45
--approotstringCaminho raiz da configuração e do cache da aplicação{cwd}/.stackql
--approotfilemodeuint32Modo de arquivo da configuração e do cache da aplicação493
--authstringPares chave-valor do contexto auth em formato json
--cachekeycountintegerNúmero inicial de chaves do cache100
--configfilestringCaminho completo do arquivo de configuração{cwd}/.stackqlrc
--cpuprofilestringArquivo cpuprofile, nenhum se vazionull
--dataflow.dependency.maxintProfundidade máxima de dependências do fluxo de dados para uma determinada consulta50
--dataflow.components.maxintNúmero máximo de componentes fracamente conexos do fluxo de dados para uma determinada consulta50
--dbInternalstringString JSON / YAML para configurar o tratamento das consultas de manutenção do SGBD{}
-d, --delimiterstringDelimitador para a saída csv. Somente um caractere. Ignorado em todas as saídas que não sejam csv,
--dryrunflagOpção dryrun; executa somente o pré-processador, e a saída processada pelo template é retornadafalse
--env.filestringArquivo opcional no estilo dotenv carregado no ambiente do processo na inicialização (todos os comandos); a ferramenta MCP reload_credentials o carrega novamente sob demanda. Um arquivo ausente é tolerado; chaves com valores vazios são ignoradas; variáveis existentes são sobrescritas. Não é carregado a partir do .stackqlrc. Disponível nas versões do StackQL posteriores à v0.10.542.null
--execution.concurrency.limitintLimite de concorrência para a execução de consultas1
--export.aliasstringPrefixo de alias de exportação (namespace ou esquema)
--gcstringString JSON / YAML que representa a configuração de GC{}
-H, --hideheadersflagDesabilita os cabeçalhos de coluna, válido somente com --output csv ou --output textfalse
--http.log.enabledflagExibe informações das solicitações http no terminalfalse
--http.proxy.hoststringHost do proxy (deixe em branco para não usar proxy)null
--http.proxy.passwordstringSenha do proxynull
--http.proxy.portintegerPorta do proxy; qualquer número menor ou igual a 0 resulta na porta padrão do esquema em questão (por exemplo, http -> 80)-1
--http.proxy.schemestringEsquema do proxy, http ou httpshttp
--http.proxy.userstringUsuário do proxynull
--http.response.maxResultsintegerNúmero máximo de resultados por solicitação http; qualquer número menor ou igual a 0 remove a limitação-1
--http.response.pageLimitintegerNúmero máximo de páginas de resultados retornadas por recurso; qualquer número menor ou igual a 0 remove a limitação20
--indirect.depth.maxintegerProfundidade máxima para consultas indiretas: views e subconsultas5
-i, --infilestringArquivo de entrada (arquivo IQL) do qual as consultas são lidas{stdin}
-q, --iqldatastringArquivo de contexto (dados) para o uso de templates (arquivo json ou jsonnet)
--loglevelstringNível de log, deve ser um de fatalfatal
--mcp.configstringObjeto de configuração JSON / YAML do servidor MCP (stackql mcp e stackql srv){}
--mcp.log.formatstringCodificação do log de auditoria do MCP, jsonl ou otel (registros de log OTLP/JSON); substitui server.audit.format em --mcp.config. Consulte Formato do log. Disponível a partir do StackQL v0.11.660.jsonl
--mcp.protocol.versionstringRevisão mais recente do protocolo MCP anunciada: auto, 2026-07-28 (somente sem sessão) ou uma revisão mais antiga, como 2025-11-25; substitui server.protocol_version em --mcp.config. Consulte Fixar a revisão. Disponível a partir do StackQL v0.12.732.auto
--mcp.server.typestringTipo de servidor MCP, um de reverse_proxy. Consulte Tipo de servidor MCP.http
--metadatattlintegerTTL dos documentos de metadados em cache, em segundos3600
--namespacesstringString JSON / YAML que representa namespaces para cache, views etc{}
--offlineflagTrabalha offline, usando dados em cachefalse
-f, --outfilestringArquivo de saída no qual os resultados são gravados{stdout}
-o, --outputstringFormato de saída, deve ser um de otel (ndjson é aceito como alias de jsonl). otel emite registros de log do OpenTelemetry, consulte Modos de saída; disponível a partir do StackQL v0.11.660. Com um exportador configurado em --otel.config, os registros otel também são enviados para esse endpointtable
--otel.configstringString JSON / YAML que configura o formato de saída otel; exporter.endpoint, exporter.headers, exporter.timeout_ms e exporter.batch_size enviam os registros para um endpoint de logs OTLP/HTTP, consulte Enviar para um endpoint OTLP. Disponível a partir do StackQL v0.12.732{}
--previewstringString JSON que habilita funcionalidades em versão prévia. {"unstable": true} expõe as relações stackql_unstable_<provider>.<service>.<resource> orientadas por documentos, que o omnisdk resolve e executa diretamente a partir dos documentos de provider, com as linhas transmitidas à medida que são produzidas; as demais chaves (batchSize, flushInterval, endpoint, insecureSkipTLSVerify) ajustam esse backend. As funcionalidades em versão prévia não são estáveis: o comportamento, a sintaxe e a saída podem mudar ou deixar de funcionar entre versões sem aviso prévio, portanto não dependa delas em produção. A partir da v1.0, a mesma ativação explícita expõe as relações stackql_preview.iac.run e stackql_preview.iac.destroy, que aplicam e desmontam um conjunto declarado de recursos por meio do omnisdk, com o estado mantido na raiz da aplicação. Consulte Funcionalidades em versão prévia{}
--querycachesizeintegerTamanho, em número de entradas, do cache LRU de planos de consulta10000
--registrystringString JSON / YAML que configura o local do registro de providers e a verificação de assinatura dos documentos de providerconsulte --registry
--sessionstringString JSON / YAML que representa a configuração da sessão{}
--sqlBackendstringString JSON / YAML que representa a configuração do sistema de backend SQLconsulte --sqlBackend
--store.txnstringString JSON / YAML que representa a configuração do armazenamento de transações{}
--tls.CABundlestringCaminho para o bundle de CAs; se não for especificado, os padrões do sistema são usados
--tls.allowInsecureflagPermite confiar em certificados inseguros (não recomendado)
--varstringVariáveis externas fornecidas como pares chave-valor para uso em consultas do StackQL por meio de arquivos de dados jsonnet
-v, --verboseflagSaída detalhadafalse
-h, --helpAjuda contextual do stackql
--versionExibe a versão do programa StackQL

--registry​

A opção --registry configura de onde os documentos de provider são lidos e se as assinaturas deles são verificadas. O valor é uma string JSON com as seguintes chaves:

ChaveDescriçãoValor padrão
urlURL do registro. Quando ela é omitida, o StackQL usa o registro público de providers do StackQL.registro público
localDocRootUm diretório local com documentos de provider, lidos no lugar do download a partir do registro. Usado ao desenvolver um provider.
srcPrefixPrefixo de caminho, sob a raiz do registro, onde ficam os documentos de origem dos providers.src
verifyConfig.nopVerifytrue ignora a verificação de assinatura. Defina como false para exigir uma assinatura ML-DSA-65 (FIPS 204) incorporada em todos os documentos de provider e de serviço lidos, incluindo as relações em versão prévia baseadas em documentos.true
verifyConfig.publicKeysUm objeto JSON que mapeia IDs de chave para chaves públicas ML-DSA-65 codificadas em hexadecimal, para registros privados. Ele substitui as chaves de produção incorporadas; um objeto vazio explícito é um erro.chaves incorporadas

Exemplo: exigir documentos de provider assinados​

Ativa a verificação para todos os documentos de provider e de serviço lidos do registro público, com as chaves de produção incorporadas:

stackql --registry '{"verifyConfig": {"nopVerify": false}}' shell

Exemplo: ler documentos não assinados de um diretório local​

Aponta o registro para um diretório de documentos de provider em desenvolvimento. Esses documentos não são assinados, portanto a verificação permanece desativada:

stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell
observação

A verificação de assinatura está disponível a partir do StackQL v1.0 e vem desativada por padrão. As assinaturas cobrem os bytes YAML exatos de um documento, portanto qualquer edição, incluindo uma alteração de formatação ou de quebra de linha, as invalida; assine novamente com a ferramenta pqsig sign-doc do registro. Documentos de desenvolvimento locais não assinados devem manter nopVerify: true. As antigas opções de certificado e os arquivos sidecar .sig não são mais usados, e os arquivos compactados publicados somente com sidecars precisam ser publicados novamente antes do uso com verificação. A verificação autentica os documentos quando eles são lidos; o download e a extração de arquivos compactados não estão cobertos.

--sqlBackend​

A opção --sqlBackend configura um backend SQL externo para o StackQL, o que permite usar um mecanismo de banco de dados externo (como o PostgreSQL) em vez do mecanismo SQL incorporado padrão. Isso é útil para aproveitar um banco de dados externo no processamento de consultas, no armazenamento persistente ou na integração com uma infraestrutura de banco de dados existente.

O valor é uma string JSON com as seguintes chaves:

ChaveDescriçãoValores de exemplo
dbEngineO tipo de mecanismo de banco de dadospostgres_tcp
sqlDialectO dialeto SQL a ser usadopostgres
dsnO nome da fonte de dados (string de conexão) do banco de dadosConsulte os exemplos abaixo

Exemplo: usar um backend PostgreSQL​

./stackql \
--sqlBackend='{"dbEngine": "postgres_tcp", "sqlDialect": "postgres", "dsn": "postgres://user:password@hostname:port/dbname?sslmode=require"}' \
shell

Exemplo: usar a interface PostgreSQL do Databricks​

O Databricks expõe uma interface compatível com PostgreSQL que pode ser usada como backend SQL do StackQL. O DSN usa o formato padrão de string de conexão do PostgreSQL com as suas credenciais do 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

observação

Caracteres especiais no nome de usuário ou na senha (como @) devem ser codificados para URL no DSN (por exemplo, @ se torna %40).