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

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 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:

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:

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:

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	Defines the database schema, including the is_flash_sale column specification.	README.md
script.py	Example Python script demonstrating DuckDB queries against recent Parquet files; serves as a template for custom flash-sale filters.	script.py
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
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 and 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 (lines 48-49), while example query patterns are provided in script.py. For offline analysis workflows, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}