从安装到你的第一条 SQL

01 / 开始使用

下载安装

选择目标电脑的系统与芯片。下面的链接来自官网同一份正式版本清单。

sudo apt install ./Bamboo-0.2.2-linux-x64.deb

02 / 连接数据

打开本地或云端文件

Bamboo 没有接收你数据的后端服务器。本地文件、SQL 和查询处理留在你的电脑上；云端数据由你的电脑直接从所配置的 S3 或 R2 按需读取。

本地文件与文件夹

1. 点击「打开数据 → 本机 → 打开文件」，选择 .parquet、.csv 或 .tsv 文件；也可将文件拖入欢迎页的放置区域。
2. 打开文件后，在「探索数据」查看预览，在「结构」查看列名与类型。当前文件在 SQL 中叫 data。
3. 要查询多个文件，选择「打开数据 → 本机 → 打开文件夹」。展开侧栏目录，或点击工作区名称进入独立 SQL 编辑器。

重新启动或升级后，已打开的工作区、独立文件和活动选择会恢复。主动关闭的项目不会自动重开；暂时离线或无权限的记录会保留。恢复时只预览数据，不会自动运行历史 SQL。

CSV/TSV 读取选项

支持本地 UTF-8 CSV/TSV，包括 BOM、引号内分隔符和多行字段；云端本轮仍仅支持 Parquet。默认将首条记录作为表头并保留文本值，可在「读取选项」选择分隔符、关闭表头或启用保守类型推断。选项按文件保存，也适用于工作区查询。无表头文件请关闭表头，以免首行被解释为列名。

CSV 默认自动检测分隔符，TSV 默认制表符；空字段为 NULL，带引号的空文本保持为空字符串。推断仅尝试布尔、整数和日期，可能改变前导零；精确小数和时间文本可在 SQL 中显式 CAST。非法 UTF-8、格式错误或超出记录预算会报错，不静默跳行。不支持 Excel/JSON 输入、其他编码或通过任意路径调用 CSV reader。

云端连接

从「打开数据 → 云存储」选择提供商。「测试并连接」会打开工作区；在「设置 → 云连接」添加并保存的连接，可以稍后再打开。

凭据保存到系统凭据库：macOS 钥匙串、Windows Credential Manager 或 Linux Secret Service。编辑连接时，所有凭据字段留空可保留现有凭据；更换时提供完整的新凭据。

关闭工作区会保留连接配置。删除连接需要确认，只移除本机保存的配置和凭据，不会删除云端文件。修改桶、前缀或 endpoint 前先关闭工作区。

03 / 探索数据

SQL 语法使用

Bamboo 使用 DuckDB SQL 的只读查询能力。下面的订单字段和文件名为示例，请替换为你的实际数据。

输入 SQL 后点击「运行查询」，或按 ⌘ Enter（macOS）/ Ctrl Enter（Windows、Linux）。可以在运行过程中取消。

查询当前文件

打开一个文件后，data 指向该文件。仅选中工作区、没有打开文件时，请使用下一节的 workspace 引用。

SELECT * FROM data LIMIT 100;

SELECT order_id, city, amount
FROM data
WHERE amount >= 100 AND city = 'Shanghai'
ORDER BY amount DESC
LIMIT 50;

字符串用单引号，列名用双引号。NULL 使用 IS NULL / IS NOT NULL 判断，空字符串使用 = ''；二者不同。

SELECT "order id", note
FROM data
WHERE note IS NULL OR note = '';

分组与聚合

SELECT city, COUNT(*) AS orders, SUM(amount) AS total
FROM data
GROUP BY city
HAVING COUNT(*) > 1
ORDER BY total DESC;

同一工作区内跨文件查询

使用 workspace."相对路径.parquet"，保留扩展名和子目录。文件不必先在侧栏打开；「工作区表」可把已发现的文件名插入光标处。每条查询限同一工作区，最多引用 32 个不同文件。

SELECT o.order_id, o.amount, c.customer_name
FROM workspace."orders.parquet" AS o
JOIN workspace."nested/customers.parquet" AS c
  ON o.customer_id = c.customer_id
ORDER BY o.order_id;

SELECT * FROM workspace."2025/orders.parquet"
UNION ALL BY NAME
SELECT * FROM workspace."2026/orders.parquet";

同样的引用语法适用于本地文件夹、S3 和 R2 工作区。不能在一条查询里跨越独立工作区，也不能用 ../、任意路径或 URL 读取未授权文件。

用 CTE 组织查询

WITH paid AS (
  SELECT city, amount FROM data WHERE fulfilled = true
)
SELECT city, SUM(amount) AS total
FROM paid
GROUP BY city;

结果、导出与边界

列很多时，预览页行数可能自动减少，所有列仍可横向滚动。「导出」可选当前页或完整结果，支持 CSV、TSV、JSON、JSONL。完整导出重新执行最后成功查询，保留筛选、排序和列投影，显示进度并可取消；不覆盖已有文件，失败时不发布不完整文件。

JSON 保留列名、类型及字符串/NULL 行值。JSONL 首行为列元数据，之后每行为一个 row 数组记录。精确数字以字符串传递，不经 JavaScript 浮点数。CSV/TSV 为公式样式的文本加单引号保护，但 NULL 和空文本均为空字段；需保留这种区别时选择 JSON/JSONL。

按需列统计与透视

成功查询后点击「分析」，选择列并主动计算总行数、NULL 数、不同非 NULL 值、最小/最大值和频次最高的 20 个值。使用完整查询及其筛选，保留 SQL LIMIT，不受预览页码限制，不进行采样。超过 10,000 个不同非 NULL 值会报错，可先筛选查询。

透视可选一个分组维度和 COUNT/SUM/AVG/MIN/MAX 指标，完整结果最多 1,000 组、4 MiB 值文本；超限报错，不静默截断。COUNT 计入 NULL 行，其他聚合遵循 DuckDB 语义；AVG 可返回浮点值。文本数字先 CAST。点击「导出透视结果」保存独立快照，不替换原查询预览或导出目标。

完整导出与分析会重新读取数据源，外部修改可能影响结果，不是预览时源字节的事务快照。内存、临时磁盘、超时和只读路径范围继续生效；可点击取消或按 Escape 中止分析。

字号与缩放

在「设置 → 通用」调整应用缩放（75%–200%）与数据字号（12–20 px），点击应用或重置。SQL 字号比数据字号大 1 px。偏好会在重启后恢复；高缩放下可在设置和表格内部滚动，使用 Tab 导航。

支持 SELECT、WITH、JOIN、UNION、聚合与窗口函数。写入、建表、COPY、PRAGMA、安装扩展及多语句执行受限制。查询不会修改源文件。内存、临时磁盘和超时可在「设置 → 性能」调整；LIMIT 不保证排序或聚合只读取少量数据。

1970-01-01 00:00:00.123456789
→ 1970-01-01 00:00:00.123456

SELECT *
FROM read_parquet('/path/to/file.parquet', int96_as='struct');

SELECT stamp.date AS day, stamp.time AS exact_time
FROM read_parquet('/path/to/file.parquet', int96_as='struct')
ORDER BY stamp.date, stamp.time;