# How to Interpret Stock Visibility Caps and max_quantity Values in Bambu Lab Filament Data

> Understand Bambu Lab filament stock visibility caps and max_quantity values. Learn how to interpret inventory data accurately for the bbl-tracker-public-db repository. Get the real stock number.

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

---

**The Bambu Lab store caps reported inventory numbers at specific thresholds (10, 200, or 400) for performance and anti-scraping reasons, and when the `stock` column equals the `max_quantity` value, the actual inventory is at least that number but potentially higher.**

The `bbl-tracker-public-db` repository provides a public dataset that mirrors the Bambu Lab storefront's inventory view, capturing filament stock levels across regions and time. Understanding how to interpret **stock visibility caps** and the **`max_quantity` column** is essential for accurate availability analysis, as the raw numbers often represent lower bounds rather than exact counts.

## Understanding Stock Visibility Caps in the Bambu Lab Store

### Why Inventory Numbers Are Capped

According to the repository's documentation in [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md), the Bambu Lab store implements **stock visibility caps** primarily for two reasons: **performance optimization** and **anti-scraping protection**. By limiting the maximum value displayed for any single SKU, the system reduces database query load and discourages automated inventory scraping that could reveal exact supply levels.

### Common Cap Values and Timeline

The cap values have evolved over time and vary by region or product family. As documented in [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md) (lines 76-80), the most common thresholds include:

- **10**: Typically applied during flash-sale periods or for high-demand limited releases
- **200**: The early global cap implemented temporarily across all regions
- **400**: The standard cap for larger regions with higher inventory turnover

The timeline of these constraints shows a clear evolution (lines 84-88 in [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md)):
- **Before February 03, 2026**: Store displayed uncapped, exact stock numbers
- **February 03 – February 09, 2026**: Global 200-cap applied across all products
- **After February 09, 2026**: Family-based caps introduced (10/200/400 depending on product category)

## Interpreting the max_quantity Column

### What max_quantity Represents

The `max_quantity` column in the dataset usually reflects the same **store-imposed limit** described in the visibility caps (line 82, [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md)). This column serves as metadata indicating the ceiling value that the Bambu Lab store allows for that specific product at that specific time.

When analyzing the data, treat `max_quantity` as the **reporting threshold** rather than a physical inventory limit. It tells you when the `stock` value hits an artificial ceiling.

### Identifying Capped vs. Uncapped Rows

The relationship between `stock` and `max_quantity` determines how you should interpret the data:

- **`stock < max_quantity`**: The number is exact and accurate. The item has fewer units than the cap threshold.
- **`stock == max_quantity`**: The number represents a **lower bound**. The actual inventory is "at least" `max_quantity`, but could be significantly higher.

This distinction is critical for availability metrics. A product showing `stock = 400` with `max_quantity = 400` is not necessarily low on stock—it may have thousands of units available, but the display is capped.

## Handling Capped Data in Analysis

### Normalizing Stock Values in Python

When computing availability metrics, you should adjust your logic to account for capped values. The repository includes example scripts demonstrating this pattern.

In [`script.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/script.py), the query logic treats capped rows differently from exact counts. Here is a practical Python example using **DuckDB** to normalize stock values:

```python
import duckdb

# Example URLs for a single day (replace with desired dates)

urls = [
    "https://db-public.bbltracker.com/2026-02-16-0000.parquet",
    "https://db-public.bbltracker.com/2026-02-16-0600.parquet",
]

# Load data

df = duckdb.read_parquet(urls).df()

# Normalize stock values:

def normalize_stock(row):
    # If stock equals the reported max_quantity, treat as at least that value

    if row.stock == row.max_quantity:
        return f"{row.stock}+"
    return str(row.stock)

df["stock_normalized"] = df.apply(normalize_stock, axis=1)

# Example: compute availability percentage per variant (US region only)

availability = (
    df[df.region == "us"]
    .groupby(["product_name", "variant_name"])
    .apply(
        lambda g: {
            "total_snapshots": len(g),
            "in_stock_snapshots": (g.stock > 0).sum(),
            "availability_pct": round((g.stock > 0).mean() * 100, 1),
            "max_stock_seen": g.stock.max(),
            "cap_seen": g.max_quantity.max(),
        }
    )
)

print(availability)

```

This approach uses `max_quantity` to flag capped rows while preserving exact counts for uncapped inventory.

### SQL Queries for Capped Data

For direct SQL analysis using the Parquet files, you can use conditional logic to handle capped values. This is particularly useful when querying the dataset without loading it into a DataFrame:

```sql
SELECT
    product_name,
    variant_name,
    CASE
        WHEN stock = max_quantity THEN max_quantity || '+'  -- capped, treat as lower bound
        ELSE CAST(stock AS VARCHAR)
    END AS stock_display,
    max_quantity,
    region
FROM read_parquet('https://db-public.bbltracker.com/2026-02-16-0000.parquet')
WHERE region = 'us';

```

This SQL pattern, similar to the logic found in [`reconstruct_db.py`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/reconstruct_db.py), ensures that your availability reports distinguish between exact counts and capped lower bounds.

## Summary

- **Stock visibility caps** are artificial limits (10, 200, or 400) imposed by the Bambu Lab store for performance and anti-scraping protection, as documented in [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md).
- When `stock` equals `max_quantity`, the value represents a **lower bound**—the actual inventory is at least that number, but potentially much higher.
- Use `max_quantity` to **identify capped rows** and handle **anomaly values** like `99999` by capping them to the expected maximum.
- For accurate availability metrics, treat `stock < max_quantity` as exact counts and `stock == max_quantity` as "at least" values in your Python or SQL queries.

## Frequently Asked Questions

### What does it mean when the stock value equals the max_quantity value?

When `stock` equals `max_quantity`, the reported number is **capped** and represents a lower bound rather than an exact count. According to the [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md) documentation, the actual inventory is "at least" that value, meaning the store may have significantly more units available than the displayed number indicates.

### Why did Bambu Lab implement stock visibility caps?

The Bambu Lab store implemented these caps for **performance optimization** and **anti-scraping protection**. As noted in the repository's [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md), limiting the maximum displayed stock value reduces database query load and prevents automated systems from scraping exact supply levels, which helps protect business intelligence regarding inventory depth.

### How should I handle anomalous stock values like 99999 in the dataset?

Anomalous values such as `99999` should be **discarded or capped** to the `max_quantity` value for that row. The [`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md) (lines 90-91) indicates these are glitch values that do not represent actual inventory. When processing data, treat any stock value exceeding the expected cap as an error and replace it with the `max_quantity` or exclude the row from availability calculations.

### Where can I find the data schema and cap history documentation?

The complete data schema, cap value history, and usage notes are documented in the **[`README.md`](https://github.com/nelsonjchen/bbl-tracker-public-db/blob/main/README.md)** file at the root of the repository. For implementation examples showing how `max_quantity` is used in queries, refer to **[`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)**, which demonstrate Python and SQL patterns for handling capped stock data when building local databases or computing availability metrics.