跳到主要内容
翻译页面

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

开始使用 StackQL

本教程分 3 个阶段，从安装到实时查询：对 GitHub 公开数据进行未经身份验证的查询（无需凭据）、使用元命令进行 schema 发现，以及对 AWS 进行经过身份验证的云查询。

1. 安装​

macOS (Homebrew):

brew install stackql

Linux:

curl -L https://bit.ly/stackql-zip -O && unzip stackql-zip

Windows、安装包和 Docker 镜像的相关内容见下载页面。使用 stackql --version 进行验证，然后启动交互式 shell：

stackql shell

2. 第一个查询：无需凭据​

拉取 GitHub Provider 并查询一个公开组织：

REGISTRY PULL github;

SELECT name, description, language, stargazers_count
FROM github.repos.repos
WHERE org = 'stackql';

返回的行（包括 stackql 引擎仓库本身）是在查询时关系化的实时 GitHub API 响应。没有任何内容被同步、缓存或导入。（未经身份验证的 GitHub 访问限制为每小时 60 次请求；个人访问令牌可以提高这一限制。）

3. 发现 schema​

Provider 接口面是自描述的，你（或 AI 智能体）无需阅读 Provider 文档，就可以通过这种方式了解哪些内容可以查询：

SHOW PROVIDERS;                        -- installed providers
SHOW SERVICES IN github;               -- services in a provider
SHOW RESOURCES IN github.repos;        -- tables in a service
SHOW METHODS IN github.repos.repos;    -- operations + required parameters
DESCRIBE github.repos.repos;           -- columns

SHOW METHODS 是需要记住的那一个：它的 RequiredParams 列准确说明每个操作在 WHERE 子句中需要什么，以及由哪个 SQL 动词（SELECT、INSERT、UPDATE、DELETE、EXEC）调用该操作。

4. 查询云服务商​

导出凭据（此处以 AWS 为例；Azure 和 Google Cloud 的做法相同），拉取 Provider，然后查询：

export AWS_ACCESS_KEY_ID=YOURACCESSKEYID
export AWS_SECRET_ACCESS_KEY=YOURSECRETACCESSKEY
REGISTRY PULL aws;

SELECT instance_id, instance_type, launch_time
FROM aws.ec2.instances
WHERE region = 'us-east-1';

聚合会自动扇出，下面的查询以按区域并行的 API 调用方式运行：

SELECT region, COUNT(*) as num_instances
FROM aws.ec2.instances
WHERE region IN ('us-east-1','us-west-2','eu-west-1')
GROUP BY region;

5. 后续步骤​

  • 变更：SHOW INSERT INTO <resource> 生成创建模板；INSERT/UPDATE/DELETE 操作的是与查询相同的表。
  • 服务器模式：stackql srv 公开 PostgreSQL 线协议，供 psql、DBeaver、BI 工具和 pandas 使用。
  • AI 智能体：stackql mcp 运行内置的 MCP 服务器，请参阅如何将 StackQL 与 AI 智能体配合使用。
  • Python：pip install pystackql，用于 notebook 和数据管道。