From install to your first SQL query

01 / GET STARTED

Download & install

Choose your computer’s OS and architecture. These links use the same stable-release catalog as the homepage.

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

02 / CONNECT YOUR DATA

Open local or cloud files

Bamboo has no backend that receives your data. Local files, SQL and query processing stay on your computer; your computer reads cloud data directly from the configured S3 or R2 storage as needed.

Local files and folders

1. Choose Open data → This computer → Open file and select a .parquet, .csv or .tsv file, or drag a file into the welcome page’s drop area.
2. After opening a file, use Explore Data for the preview and Schema for column names and types. The active file is called data in SQL.
3. For multiple files, choose Open data → This computer → Open folder. Expand directories in the sidebar, or click the workspace name to enter its own SQL editor.

Open workspaces, independent files and the active selection persist across restarts and upgrades. Explicitly closed items stay closed; temporarily offline or inaccessible entries are retained. Restoration previews data without automatically running historical SQL.

CSV/TSV reading options

Local UTF-8 CSV/TSV supports a BOM, quoted delimiters and multiline fields; cloud input remains Parquet-only. Defaults use the first record as headers and preserve values as text. Reading options let you choose a delimiter, disable headers or enable conservative type inference. Options persist per file and apply to workspace queries. Disable headers for headerless files so the first record is treated as data.

CSV detects its delimiter by default; TSV uses tabs. Empty fields are NULL, while quoted empty text stays an empty string. Inference tries booleans, integers and dates and may remove leading zeros; explicitly CAST precise decimals or time text in SQL. Invalid UTF-8, malformed input or records exceeding the budget fail visibly instead of skipping rows. Excel/JSON input, other encodings and arbitrary-path CSV reader calls are not supported.

Cloud connections

Choose a provider under Open data → Cloud storage. Test & connect opens a workspace. Connections added and saved in Settings → Cloud connections can be opened later.

Credentials are stored in macOS Keychain, Windows Credential Manager or Linux Secret Service. When editing, leave all credential fields blank to keep them; supply the complete new credential set to replace them.

Closing a workspace keeps its connection. Deleting a connection requires confirmation and removes saved local configuration and credentials, not cloud files. Close the workspace before changing the bucket, prefix or endpoint.

03 / EXPLORE YOUR DATA

Use SQL

Bamboo uses DuckDB SQL for read-only queries. The order fields and filenames below are examples; replace them with your own data.

Enter SQL and click Run query, or press ⌘ Enter on macOS / Ctrl Enter on Windows and Linux. You can cancel a running query.

Query the active file

After opening a file, data refers to it. In the workspace editor without an active file, use the workspace references in the next section.

SELECT * FROM data LIMIT 100;

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

Use single quotes for strings and double quotes for identifiers. Test NULL with IS NULL / IS NOT NULL, and empty text with = ''; they are different values.

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

Group and aggregate

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

Query files in one workspace

Use workspace."relative/path.parquet", including the extension and subdirectories. Files do not need to be opened first. Workspace tables inserts discovered table names at your cursor. Each query stays within one workspace and can reference up to 32 distinct files.

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";

The same references work in local folder, S3 and R2 workspaces. A query cannot cross independent workspaces or use ../, arbitrary paths or URLs to access unauthorized files.

Organize a query with a CTE

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

Results, export and limits

Wide previews may reduce rows per page; all columns remain available by horizontal scrolling. Export offers the current page or complete result in CSV, TSV, JSON and JSONL. Complete export reruns the last successful query with its filter, sorting and projection, shows progress and supports cancellation. Existing files are never overwritten; failed exports are not published as complete files.

JSON retains column names/types and string-or-null row values. JSONL begins with column metadata, followed by one row-array record per line. Exact numeric values travel as strings, without JavaScript floating-point conversion. CSV/TSV prefix formula-like text with an apostrophe; NULL and empty text both become empty fields. Choose JSON/JSONL to preserve that distinction.

On-demand column statistics and pivots

After a successful query, choose Analyze, select a column and request total rows, NULL counts, distinct non-NULL values, min/max and the 20 most frequent values. Analysis uses the complete query and filter, retains SQL LIMIT, and ignores preview pagination. It never samples. More than 10,000 distinct non-NULL values produces an error; filter the query first.

Choose one grouping dimension and COUNT/SUM/AVG/MIN/MAX metric for a pivot. Complete results allow up to 1,000 groups and 4 MiB of value text; exceeding either limit fails without silent truncation. COUNT includes NULL rows; other aggregates follow DuckDB semantics and AVG may return floating-point values. CAST text numbers first. Export pivot saves its independent snapshot without replacing the normal query preview or export target.

Complete export and analysis read sources again, so external changes may affect results; they are not transactional copies of the preview's source bytes. Memory, temporary disk, timeout and read-only path scopes still apply. Cancel or Escape interrupts analysis.

Text size and zoom

In Settings → General, set app zoom (75–200%) and data text size (12–20 px), then apply or reset. SQL text is one pixel larger than data text. Preferences restore after restart. At high zoom, scroll inside settings and tables and use Tab to navigate.

SELECT, WITH, JOIN, UNION, aggregates and window functions are supported. Writes, table creation, COPY, PRAGMA, extension installation and multi-statement execution are restricted. Queries do not modify source files. Adjust memory, temporary disk and timeout in Settings → Performance; LIMIT does not guarantee a small scan for sorting or aggregation.

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;