# Detecting Flash Sales Using the is_flash_sale Boolean Field in Bambu Lab Tracker

> Easily detect flash sales using the is_flash_sale boolean field in the BBL Tracker database. Filter and analyze limited-quantity purchase events separately from regular stock data.

- Repository: [Nelson Chen/bbl-tracker-public-db](https://github.com/nelsonjchen/bbl-tracker-public-db)
- Tags: how-to-guide
- Published: 2026-03-08

---

**The `is_flash_sale` boolean field in the Bambu Lab Store Filament Tracker database explicitly marks inventory snapshots captured during flash-sale windows, allowing you to filter and analyze limited-quantity purchase events separately from regular stock data.**

Detecting flash sales using the `is_flash_sale` boolean field is straightforward in the `nelsonjchen/bbl-tracker-public-db` repository. This open-source dataset tracks Bambu Lab store inventory, and the dedicated boolean column provides a reliable mechanism to distinguish between normal restocks and time-limited flash sales where purchase quantities are typically capped.

## Understanding the is_flash_sale Schema

### Schema Definition in README.md

The database schema is documented in the repository's [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md) file (lines 48-49). The `is_flash_sale` column is defined as a **boolean** type that indicates whether the snapshot was taken during an active flash-sale period.

When this field value is **`true`**, the store was actively enforcing purchase quantity limits—often restricting buyers to 10 units or fewer for that specific product variant at the moment of the snapshot. A value of `false` indicates standard inventory tracking without flash-sale restrictions.

## Querying Flash Sale Data with DuckDB

### Basic SQL Filter for Flash Sale Snapshots

To isolate flash-sale events for a specific product, filter on `is_flash_sale = true` when querying the Parquet files. This example retrieves all flash-sale snapshots for Black PETG in the US region:

```sql
SELECT
    timestamp,
    stock,
    max_quantity,
    is_flash_sale
FROM read_parquet('https://db-public.bbltracker.com/2026-02-16-0000.parquet')
WHERE
    region = 'us'
    AND product_name = 'PETG'
    AND variant_name = 'Black'
    AND is_flash_sale = true;

```

This query returns a precise timeline showing exactly when the store enforced flash-sale caps for that variant.

### Python Script for Bottleneck Analysis

For programmatic detection across multiple files, use Python with DuckDB to identify which items suffer the worst availability during flash sales. This script extends the pattern found in the repository's [`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py):

```python
import duckdb
import json, urllib.request

# 1. Discover recent parquet files via the manifest

manifest_url = "https://db-public.bbltracker.com/manifest.json"
with urllib.request.urlopen(manifest_url) as resp:
    manifest = json.loads(resp.read())

# Grab the last 8 files (≈ 2 days of data)

recent_files = sorted(manifest["files"].keys())[-8:]
urls = [f"https://db-public.bbltracker.com/{f}" for f in recent_files]

# 2. Query flash-sale rows and calculate availability

query = f"""
WITH flash AS (
    SELECT
        timestamp,
        product_name || ' - ' || variant_name AS sku,
        stock,
        max_quantity
    FROM read_parquet({urls})
    WHERE is_flash_sale = true
      AND region = 'us'
)
SELECT
    sku,
    COUNT(*) AS total_snapshots,
    SUM(CASE WHEN stock > 0 THEN 1 ELSE 0 END) AS in_stock_snapshots,
    ROUND(100.0 * SUM(CASE WHEN stock > 0 THEN 1 ELSE 0 END) / COUNT(*), 1)
        AS availability_pct
FROM flash
GROUP BY sku
ORDER BY availability_pct ASC
LIMIT 20;
"""

con = duckdb.connect()
df = con.execute(query).df()
print(df.to_string(index=False))

```

This analysis reveals which SKUs had the lowest in-stock percentage during flash-sale periods, indicating potential bottlenecks that could block multi-item purchases.

### Excluding Flash Sales for Baseline Analysis

To calculate baseline availability metrics without flash-sale distortion, explicitly exclude flash-sale rows:

```sql
SELECT
    sku,
    AVG(CASE WHEN stock > 0 THEN 1 ELSE 0 END) * 100 AS normal_availability_pct
FROM (
    SELECT
        product_name || ' - ' || variant_name AS sku,
        stock,
        is_flash_sale
    FROM read_parquet('https://db-public.bbltracker.com/2026-02-01-0000.parquet')
    UNION ALL
    SELECT
        product_name || ' - ' || variant_name,
        stock,
        is_flash_sale
    FROM read_parquet('https://db-public.bbltracker.com/2026-02-01-0600.parquet')
)
WHERE is_flash_sale = false
GROUP BY sku;

```

The `WHERE is_flash_sale = false` clause ensures only standard inventory snapshots contribute to the trend analysis.

## Key Files for Flash Sale Detection

| File | Role | Location |
|------|------|----------|
| [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md) | Defines the database schema, including the `is_flash_sale` column specification. | [README.md](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/master/README.md) |
| [`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py) | Example Python script demonstrating DuckDB queries against recent Parquet files; serves as a template for custom flash-sale filters. | [script.py](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/master/script.py) |
| [`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py) | Utility to build a consolidated DuckDB database file for offline analysis, useful when running repeated flash-sale queries without re-downloading Parquet files. | [reconstruct_db.py](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/master/reconstruct_db.py) |
| [`manifest.json`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/manifest.json) | Remote index of all available Parquet files; required for programmatic discovery of recent snapshots to analyze for flash-sale events. | `https://db-public.bbltracker.com/manifest.json` |

## Summary

- The `is_flash_sale` boolean field in `nelsonjchen/bbl-tracker-public-db` explicitly marks inventory snapshots taken during flash-sale windows.
- Filter on `is_flash_sale = true` to isolate time-limited purchase events where quantity caps (typically 10 units) were enforced.
- Use `is_flash_sale = false` to exclude flash-sale distortion from long-term availability trend analysis.
- Query the field using DuckDB SQL or Python scripts based on the repository's [`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py) and [`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py) utilities.

## Frequently Asked Questions

### What does the is_flash_sale field indicate?

The `is_flash_sale` field is a boolean column that indicates whether an inventory snapshot was captured while the Bambu Lab store was actively running a flash sale. When set to `true`, the store was enforcing purchase quantity limits on that product variant at the exact moment of the snapshot.

### How can I filter out flash sale data to analyze normal inventory trends?

To analyze only standard inventory patterns without flash-sale interference, add `WHERE is_flash_sale = false` to your SQL queries. This exclusion ensures that metrics like average availability or stock levels reflect normal restocking cycles rather than artificial scarcity periods caused by purchase limits.

### Which repository files contain the flash sale detection logic?

The schema definition resides in [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md) (lines 48-49), while example query patterns are provided in [`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py). For offline analysis workflows, [`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py) demonstrates how to consolidate Parquet files into a local DuckDB database where you can run repeated flash-sale detection queries efficiently.

### Can I use Python to programmatically detect flash sale periods?

Yes, you can use Python with DuckDB to programmatically identify flash-sale periods by querying the `is_flash_sale` field across multiple Parquet files. Use the remote [`manifest.json`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/manifest.json) to discover recent data files, then filter for rows where `is_flash_sale` equals `true` to build a timeline of when quantity limits were enforced.