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

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, 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 (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):

• 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). 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, the query logic treats capped rows differently from exact counts. Here is a practical Python example using DuckDB to normalize stock values:

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:

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, 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.
• 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 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, 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 (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 file at the root of the repository. For implementation examples showing how max_quantity is used in queries, refer to script.py and reconstruct_db.py, which demonstrate Python and SQL patterns for handling capped stock data when building local databases or computing availability metrics.

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