Dataset codebook

A published dataset release ships as a set of Parquet files. This page documents every column in them: what it holds, what its absence means, and how far to trust it.

The tables come from the release schemas in backend/scripts/build_dataset_release.py and describe the archive, not the platform’s internal database (see Data model).

Every release also carries croissant.json, which repeats these descriptions in MLCommons Croissant form for tools that read dataset metadata directly.

How to read the tables

• Required means the column is never null. Everything else can be null, and null means “not recorded” rather than zero or empty. A missing weight_g is a product nobody weighed, not a weightless product.
• Identifiers are unique within one release, and reference tables are joined by them.
• records.parquet holds both whole products and their components in one table. A row with a null parent_id is a whole product; anything else is a part taken out of the row named by parent_id. Depth is not bounded, so treat it as a tree, not two levels.
• Reference tables under reference/ are frozen copies taken at build time. They are the vocabulary the records were annotated against, not a live taxonomy.

Contributor identity

owner_pseudonym is the only trace of who recorded a row. It is a salted hash, and the salt stays unpublished. Each release credits its contributors collectively in its README.md rather than naming them against their rows.

A contributor keeps the same pseudonym across releases built with the same salt. Each release publishes a pseudonym salt fingerprint in its README.md; pseudonyms are comparable only between releases whose fingerprints match. Check the fingerprint before you join on owner_pseudonym across releases.

Re-identifying contributors falls outside the licence, and outside the GDPR basis the release was published under.

Files

records.parquet

One row per documented product or component.

Column	Type	Required	Description
id	integer	yes	Record identifier, unique within the release.
parent_id	integer	no	Record this one was taken out of; null for a whole product.
amount_in_parent	integer	no	How many of this component the parent holds; null if not counted.
owner_pseudonym	text	yes	Stable pseudonymous code for the contributing account. Salted hash, not reversible. Equal codes mean the same contributor across releases that share a salt fingerprint.
name	text	yes	Contributor-given name of the product or component.
description	text	no	Free-text notes the contributor added.
brand	text	no	Brand as read off the product or its label; null if absent or unreadable.
model	text	no	Model or type number as read off the product; null if absent or unreadable.
product_type_id	integer	no	Row in reference/product_types.parquet; null if untyped.
weight_g	float	no	Measured mass in grams.
height_cm	float	no	Measured height in centimetres.
width_cm	float	no	Measured width in centimetres.
depth_cm	float	no	Measured depth in centimetres.
volume_cm3	float	no	Bounding-box volume in cubic centimetres, height x width x depth. Null unless all three are present. It is the box the product fits in, not the volume of material in it.
circularity_properties	text	no	Circularity notes as a JSON object string, with optional recyclability, disassemblability and remanufacturability keys. Contributor judgement, not measurement.
created_at	timestamp (UTC)	no	When the record was first saved (UTC).
updated_at	timestamp (UTC)	no	When the record was last changed (UTC).

record_materials.parquet

Material composition lines, one per record and material pair.

Column	Type	Required	Description
product_id	integer	yes	Record this material line belongs to (records.parquet id).
material_id	integer	yes	Row in reference/materials.parquet.
quantity	float	yes	Amount of the material in the record, in unit.
unit	text	yes	Unit name for quantity; see reference/units.parquet.

reference/taxonomies.parquet

Classification systems the categories belong to.

Column	Type	Required	Description
id	integer	yes	Taxonomy identifier.
name	text	yes	Name of the classification system.
version	text	no	Version of the source taxonomy, where it declares one.
description	text	no	What the taxonomy covers.
domains	list of text	yes	What the taxonomy classifies: materials, products, or other.
source	text	no	Citation or URL for the taxonomy.

reference/categories.parquet

Categories, nested through supercategory_id.

Column	Type	Required	Description
id	integer	yes	Category identifier.
name	text	yes	Category name as used by its taxonomy.
description	text	no	What the category covers.
external_id	text	no	Identifier the source taxonomy uses, where it has one.
supercategory_id	integer	no	Parent category; null at the top of the tree.
taxonomy_id	integer	yes	Taxonomy this category belongs to.

reference/materials.parquet

Materials referenced by record_materials.

Column	Type	Required	Description
id	integer	yes	Material identifier.
name	text	yes	Material name.
description	text	no	What the material entry covers.
source	text	no	Citation or URL for the material entry.
density_kg_m3	float	no	Reference density in kg/m3, where known.
is_crm	boolean	no	Whether the material is an EU Critical Raw Material (CRM).

reference/product_types.parquet

Product types referenced by records.product_type_id.

Column	Type	Required	Description
id	integer	yes	Product type identifier.
name	text	yes	Product type name.
description	text	no	What the product type covers.

reference/category_material_links.parquet

Which categories each material falls under.

Column	Type	Required	Description
category_id	integer	yes	Row in reference/categories.parquet.
material_id	integer	yes	Row in reference/materials.parquet.

reference/category_product_type_links.parquet

Which categories each product type falls under.

Column	Type	Required	Description
category_id	integer	yes	Row in reference/categories.parquet.
product_type_id	integer	yes	Row in reference/product_types.parquet.

reference/units.parquet

Units used by record_materials.unit.

Column	Type	Required	Description
name	text	yes	Unit name, as it appears in record_materials.unit.
symbol	text	yes	Symbol for the unit.