跳到主要内容
翻译页面

本页面由 AI 辅助从英文翻译而来。如两者存在差异，以英文版本为准。

全局标志

全局标志指定 StackQL 应用程序的运行时行为，这些标志在启动 StackQL 应用程序时（交互式 shell 模式或非交互式 exec 模式）在命令行中设置，或者从 StackQL 初始化文件（.stackqlrc）中读取。标志包括：

标志数据类型说明默认值
--access.configstring调用方访问配置，一个 JSON 封装对象 {"path": "/path/to/access.json"}（也接受直接传入文件路径）。启用访问管理：通过 JWT、静态 bearer 令牌、双向 TLS 或本地 OS 身份对调用方进行身份验证，并依据策略规则对语句进行授权。本地令牌凭据从 STACKQL_CALLER_TOKEN 读取。在 v1.0 及之后的 StackQL 发布版本中可用。
--acidstring表示 ACID 配置的 JSON / YAML 字符串{}
--allow-persistent-secretsflag允许会话通过 SET "$.secret_store" 选择持久化的 OS 机密存储（macOS Keychain、Linux Secret Service 或 Windows Credential Manager）。即使设置了该标志，平面文件存储也会被拒绝。参阅 Provider 会话与机密。在 v1.0 及之后的 StackQL 发布版本中可用。false
--allow-secret-dereferenceflag允许在 SQL 表达式中解引用机密和凭据的值（"$secrets.name"、"$auth.provider.field"），其后果是这些值可能进入结果、日志和持久化的查询产物。正常的 Provider 身份验证不需要此标志。参阅 SQL 中的机密值。在 v1.0 及之后的 StackQL 发布版本中可用。false
--apirequesttimeoutintegerAPI 请求超时时间，以秒为单位，0 表示不超时45
--approotstring应用程序配置和缓存的根路径{cwd}/.stackql
--approotfilemodeuint32应用程序配置和缓存的文件模式493
--authstringjson 形式的 auth 上下文键值对
--cachekeycountinteger缓存的初始键数量100
--configfilestring配置文件的完整路径{cwd}/.stackqlrc
--cpuprofilestringcpuprofile 文件，为空表示无null
--dataflow.dependency.maxint单个查询的最大数据流依赖深度50
--dataflow.components.maxint单个查询的最大数据流弱连通分量数50
--dbInternalstring用于配置 DBMS 内务查询处理方式的 JSON / YAML 字符串{}
-d, --delimiterstringcsv 输出的分隔符。仅限单个字符。对所有非 csv 输出均忽略,
--dryrunflagdryrun 标志；只运行预处理器，返回模板化后的输出false
--env.filestring可选的 dotenv 风格文件，启动时加载到进程环境中（所有命令）；MCP reload_credentials 工具按需重新加载它。文件不存在时不报错；值为空的键会被跳过；已有的变量会被覆盖。不从 .stackqlrc 读取。在 v0.10.542 之后的 StackQL 发布版本中可用。null
--execution.concurrency.limitint查询执行的并发上限1
--export.aliasstring导出别名前缀（命名空间或 schema）
--gcstring表示 GC 配置的 JSON / YAML 字符串{}
-H, --hideheadersflag禁用列标题，仅在使用 --output csv 或 --output text 时有效false
--http.log.enabledflag在终端中显示 http 请求信息false
--http.proxy.hoststring代理主机（留空表示不使用代理）null
--http.proxy.passwordstring代理密码null
--http.proxy.portinteger代理端口，任何小于或等于 0 的数字都会使用给定协议方案的默认端口（例如 http -> 80）-1
--http.proxy.schemestring代理协议方案，http 或 httpshttp
--http.proxy.userstring代理用户null
--http.response.maxResultsinteger每个 http 请求的最大结果数，任何小于或等于 0 的数字表示不限制-1
--http.response.pageLimitinteger每个资源返回的最大结果页数，任何小于或等于 0 的数字表示不限制20
--indirect.depth.maxinteger间接查询的最大深度：视图和子查询5
-i, --infilestring从中读取查询的输入文件（IQL 文件）{stdin}
-q, --iqldatastring用于模板化的上下文（数据）文件（json 或 jsonnet 文件）
--loglevelstring日志级别，必须是 fatal 之一fatal
--mcp.configstringMCP 服务器的 JSON / YAML 配置对象（stackql mcp 和 stackql srv）{}
--mcp.log.formatstringMCP 审计日志的编码，jsonl 或 otel（OTLP/JSON 日志记录）；覆盖 --mcp.config 中的 server.audit.format。参阅日志格式。在 v0.11.660 及之后的 StackQL 发布版本中可用。jsonl
--mcp.protocol.versionstring对外通告的最新 MCP 协议修订版本，auto、2026-07-28（仅无会话）或更早的修订版本，如 2025-11-25；覆盖 --mcp.config 中的 server.protocol_version。参阅固定修订版本。在 v0.12.732 及之后的 StackQL 发布版本中可用。auto
--mcp.server.typestringMCP 服务器类型，reverse_proxy 之一。参阅 MCP 服务器类型。http
--metadatattlinteger已缓存元数据文档的 TTL，以秒为单位3600
--namespacesstring表示缓存、视图等所用命名空间的 JSON / YAML 字符串{}
--offlineflag离线工作，使用缓存数据false
-f, --outfilestring写入结果的输出文件{stdout}
-o, --outputstring输出格式，必须是 otel 之一（ndjson 可作为 jsonl 的别名）。otel 输出 OpenTelemetry 日志记录，参阅输出模式；在 v0.11.660 及之后的 StackQL 发布版本中可用。在 --otel.config 中配置了导出器时，otel 记录还会推送到该端点table
--otel.configstring用于配置 otel 输出格式的 JSON / YAML 字符串；exporter.endpoint、exporter.headers、exporter.timeout_ms 和 exporter.batch_size 将记录推送到 OTLP/HTTP 日志端点，参阅推送到 OTLP 端点。在 v0.12.732 及之后的 StackQL 发布版本中可用{}
--previewstring启用预览功能的 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 应用和拆除一组声明的资源，状态保存在应用程序根路径下。参阅预览功能{}
--querycachesizeinteger查询计划 LRU 缓存的大小，以条目数计10000
--registrystring用于配置 Provider 注册表位置和 Provider 文档签名验证的 JSON / YAML 字符串参阅 --registry
--sessionstring表示会话配置的 JSON / YAML 字符串{}
--sqlBackendstring表示 SQL 后端系统配置的 JSON / YAML 字符串参阅 --sqlBackend
--store.txnstring表示 Txn 存储配置的 JSON / YAML 字符串{}
--tls.CABundlestringCA 证书包的路径，未指定时使用系统默认值
--tls.allowInsecureflag允许信任不安全的证书（不推荐）
--varstring以键/值对形式提供的外部变量，通过 jsonnet 数据文件引入 StackQL 查询
-v, --verboseflag详细输出false
-h, --helpstackql 的上下文相关帮助
--version显示 StackQL 程序的版本

--registry​

--registry 标志配置从何处读取 Provider 文档以及是否验证其签名。其值是一个包含以下键的 JSON 字符串：

键说明默认值
url注册表 URL。省略时使用公共 StackQL Provider 注册表。公共注册表
localDocRoot存放 Provider 文档的本地目录，直接从中读取而不从注册表下载。在开发 Provider 时使用。
srcPrefix注册表根目录下存放 Provider 源文档的路径前缀。src
verifyConfig.nopVerifytrue 跳过签名验证。设置为 false 时，读取的每个 Provider 和服务文档都必须带有嵌入的 ML-DSA-65（FIPS 204）签名，包括由文档支持的预览关系。true
verifyConfig.publicKeys一个 JSON 对象，将密钥 ID 映射到十六进制编码的 ML-DSA-65 公钥，用于私有注册表。它会替换嵌入的生产密钥；显式给出空对象属于错误。嵌入的密钥

示例：要求 Provider 文档带签名​

对从公共注册表读取的每个 Provider 和服务文档开启验证，并依据嵌入的生产密钥进行检查：

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

示例：从本地目录读取未签名的文档​

将注册表指向一个存放开发中 Provider 文档的目录。这些文档未签名，因此验证保持关闭：

stackql --registry '{"localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": {"nopVerify": true}}' shell
备注

签名验证在 v1.0 及之后的 StackQL 发布版本中可用，默认关闭。签名覆盖文档的确切 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）。