Table of Contents
Overview
We also make it easy for you to obtain a snapshot of Current cohort data. On the “User Data” section of your Cohort’s page (the same page where you can manage Participations), you will find a list of files. The most recent file is at the top of the list. If the list is empty or outdated, you may enqueue the creation of a new file with the “Refresh CSVs” button. You may generate as many snapshots as you like, but we enforce a 2-hour wait between consecutive dumps.
File Structure
A CSV data dump contains multiple files that work together to represent the complete dataset:
annotation_items.csv: Individual food items within annotationsannotations.csv: Collections of annotation items linked to dishescohorts.csv: Groups of userscomments.csv: User, collaborator, chatbot and system comments on dishesdish_images.csv: Links to download the dish imagesdishes.csv: User meal recordsfood_lists.csv: Collections of foodsfood_nutrients.csv: Nutrient information for foodsfoods.csv: Individual food itemsinfo.txt: Database metadataintakes.csv: User meal consumption recordsnutrients.csv: Nutrient definitionsorganizations.csv: Organization owning the cohortparticipations.csv: User-cohort associationsproduct_nutrients.csv: Nutrient information for productsproducts.csv: Product informationusers.csv: User information
Data Relationships
The data is organized in a relational structure where:
- Users belong to cohorts through participations
- Users create dishes
- Dishes can have images
- Dishes are linked to annotations
- Each annotation belongs to the participation it was logged during
- Annotations contain annotation items
- Annotation items reference either foods or products
- Foods belong to food lists
- Both foods and products have associated nutrients
The dump only holds what was logged during this cohort’s participations.
If a user also took part in another cohort, the dishes, dish images, annotations, intakes, comments and annotation items from that other cohort are not in this dump.
Neither are the foods and products that only those annotation items use, nor their nutrient values.
nutrients.csv still lists every nutrient.
For a more detailed description of each object and their role see the Glossary.
File Descriptions
Columns marked as legacy are deprecated and will be removed in future version of data exports.
Columns marked as internal use are not intended to be used by collaborators and might be removed in future version of data exports.
annotation_items.csv
An annotation item is a single item in an annotation. It can be a food, a product, and it has a consumed quantity and unit of measure (either grams or ml).
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| consumed_quantity | float | Quantity in grams or ml | |
| consumed_unit_id | string | ID of the unit of measure | Foreign key (e.g., g) |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| annotation_id | uuid | Associated annotation ID | Foreign key |
| food_id | uuid | Associated food ID | Foreign key, optional |
| product_id | uuid | Associated product ID | Foreign key, optional |
| consumed_kcal | float | Calculated kcal | |
| packaged | boolean | Looked like a packaged product to the photo analysis | Set when the photo analysis creates the item, cleared whenever the item gets another food (from the chatbot, a collaborator or a product swapped for a food), copied to duplicated meals, not updated otherwise. False for items logged before this column existed |
| name_from_ai_* | text | AI-detected name | Available in en, fr, de, nl, es |
| name_from_user_* | text | User-provided name | Available in en, fr, de, nl, es |
| properties_* | text | AI-detected properties | Available in en, fr, de, nl, es |
annotations.csv
An annotation is a collection of annotation items. It also links a dish to a participation.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| dish_id | uuid | Associated dish ID | Foreign key |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| status | text | Annotation status | See status values below |
| participation_id | uuid | Associated participation ID | Foreign key |
| favorited_at | datetime | When the annotation was favorited | Null if not favorited |
| parent_annotation_id | uuid | Parent annotation in a “Quick pick” | Foreign key, optional |
Status Values
initial: Initial state when annotation is createdawaiting_segmentation_service: Awaiting segmentation serviceawaiting_llm_service: Awaiting LLM serviceannotatable: Annotatableinfo_asked: Info asked by collaborator to the userrequires_human_intervention: Requires collaborator intervention for annotationannotated: Manually annotated by collaborator
cohorts.csv
A cohort is a group of users.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| name | text | Cohort name | Not enforced unique |
| info | text | Cohort description | |
| public | boolean | Whether anyone can join the cohort with a key | |
| trial | boolean | Whether the cohort is a trial cohort | |
| expires_at | datetime | When the cohort expires | Null if it never expires |
| participation_limit | integer | Maximum number of participations | Null if unlimited |
| annotation_limit | integer | Maximum number of annotations | Null if unlimited |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| organization_id | uuid | Associated organization ID | Foreign key, internal use |
comments.csv
A comment is associated with a dish and can be posted either by a user, a collaborator, or the chatbot.
Besides its replies, the chatbot posts automatic notices, such as the welcome message.
The kind column tells these notices apart from ordinary messages:
| Kind | Message |
|---|---|
conversational |
An ordinary message: every comment by a user or a collaborator, and the chatbot’s replies |
welcome |
The welcome message, sent once per participation |
kcal_verification |
A kcal verification request, sent when dish analysis reported a kcal sum higher than a threshold |
acknowledgment |
Tells the user that a human annotator will answer their comment |
handoff |
Tells the user that a human annotator is taking over |
reformulation_request |
Asks the user to reformulate a comment the chatbot could not process |
barcode_request |
Asks the user to scan the barcode of items that look like packaged products, at most once per dish |
Handoff and reformulation messages posted before 2026-08-24 were not told apart from the chatbot’s replies, so their kind is conversational.
Older exports have true/false columns instead of kind: welcome and kcal_verification, plus acknowledgment and housekeeping from 2026-08-24 on.
housekeeping is true for both handoff and reformulation messages.
Exports made between 2026-10-20 and 2026-10-21 have both these columns and kind.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| message | text | Comment content | |
| user_id | uuid | Associated user ID | Foreign key, optional |
| collaborator_id | uuid | Associated collaborator ID | Foreign key, optional |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| silent | boolean | Whether comment is silent | No notification sent to the user |
| annotation_id | uuid | Associated annotation ID | Foreign key |
| bot | boolean | Whether from chatbot | |
| kind | string | What kind of message this is | One of the kinds listed above |
| llm_content_policy_violation_at | datetime | Set when comment violated LLM policy | Null otherwise; internal use |
dish_images.csv
A dish image is a picture of a dish. The image files are not in the ZIP file: each row has a link to download its image instead (see Downloading the dish images).
A dish can have several images: photos taken by the participant, an image generated by AI when the meal was described in text, or photos of a scanned product’s packaging.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| dish_id | uuid | Associated dish ID | Foreign key |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| ai_generated | boolean | Whether the image was made by AI | false for photos |
| filename | text | Name of the uploaded file | |
| content_type | text | File type | e.g., image/jpeg |
| url | text | Link to download the image | Works for 7 days after the export |
Anyone who has a link can open the image without signing in to MyFoodRepo. Keep this file as private as the rest of the data. The links stop working 7 days after the CSV file was made (see
Generatedin info.txt). To download the images later, generate a new CSV file with the “Refresh CSVs” button.
dishes.csv
A dish is a meal consumed by a user, it can be associated with images (see dish_images.csv) or described by text.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| user_id | uuid | Associated user ID | Foreign key |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| description | text | Text description | Used when no image for dish captured as text |
| llm_content_policy_violation_at | datetime | Set when content violated policy | Null otherwise; internal use |
food_lists.csv
A food list is a collection of foods.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| country_id | string | Associated country code | Foreign key (e.g., ch, fr) |
| name | text | Food list name | |
| source | text | Data source | |
| version | text | Version number | |
| metadata | jsonb | Additional metadata | |
| editable | boolean | Whether list is editable | Official lists are not editable |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| cname | text | Canonical name | Internal use |
| retired_at | datetime | Retirement date | Null if active |
food_nutrients.csv
A food nutrient is a nutrient associated with a food.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| food_id | uuid | Associated food ID | Foreign key |
| nutrient_id | string | Associated nutrient ID | Foreign key (e.g., energy_kcal) |
| per_hundred | float | Quantity per 100 grams or ml | |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp |
foods.csv
A food is a single item in a food list.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| unit_id | string | Associated unit ID | Foreign key (e.g., g, ml) |
| fa_ps_ratio | float | FA/PS ratio | |
| id_v1 | integer | Previous version ID | Legacy |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| portion_quantity | float | Standard portion size | |
| food_list_id | uuid | Associated food list ID | Foreign key |
| metadata | jsonb | Additional metadata | |
| properties | jsonb | AI-generated properties | |
| name_* | text | Food name | Available in en, fr, de, nl, es |
info.txt
A text file containing information about the database.
Content
- Cohort: name of the cohort
- Source: name of the source of the data
- Author: name of the author of the data
- Generated: date and time of the export
- A reminder that the links in
dish_images.csvstop working 7 days after that date
intakes.csv
An intake is a single intake of a dish by a user. It records the date and time of consumption, the timezone, and the associated annotation.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| consumed_at | datetime | Consumption timestamp | |
| timezone | text | Timezone | |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| annotation_id | uuid | Associated annotation ID | Foreign key |
nutrients.csv
A nutrient is a component of food that can be measured.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | string | Unique identifier | Primary key (e.g., energy_kcal) |
| unit_id | string | Associated unit ID | Foreign key (e.g., g, mg, kcal) |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| name_* | text | Nutrient name | Available in en, fr, de, nl, es |
organizations.csv
An organization owns one or more cohorts.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| name | text | Organization name | |
| address | text | Postal address | |
| main_collaborator_id | uuid | Main collaborator | Foreign key, internal use |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp |
participations.csv
A participation associates a user to a cohort.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| user_id | uuid | Associated user ID | Foreign key, null until joined |
| cohort_id | uuid | Associated cohort ID | Foreign key |
| key | text | Mobile app access key | |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| associated_at | datetime | User association date | |
| started_at | datetime | Validity start date | |
| ended_at | datetime | Validity end date |
product_nutrients.csv
A product nutrient is a nutrient associated with a product.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| product_id | uuid | Associated product ID | Foreign key |
| nutrient_id | string | Associated nutrient ID | Foreign key (e.g., energy_kcal) |
| per_hundred | float | Quantity per 100 grams or ml | |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp |
products.csv
A product is a packaged food item with a barcode.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| barcode | text | Product barcode | |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| fetched_at | datetime | Last source update timestamp | |
| image_url | text | Product image URL | |
| unit_id | string | Associated unit ID | Foreign key (e.g., g, ml) |
| portion_quantity | float | Standard portion size | |
| source | text | Data source | |
| status | text | Product status | See status values below |
| name_* | text | Product name | Available in en, fr, de, nl, es |
Status Values
initial: Initial state when product is createdcomplete: All data is availableincomplete: Some data is missing
users.csv
A user is a user of the app.
Authentication-related columns (email, encrypted password, reset and unlock tokens, auth tokens, provider, etc.) are deliberately excluded from the dump.
Columns
| Column | Type | Description | Notes |
|---|---|---|---|
| id | uuid | Unique identifier | Primary key |
| created_at | datetime | Creation timestamp | |
| updated_at | datetime | Last update timestamp | |
| anonymous | boolean | Anonymous user | Legacy |
| note | text | Collaborator notes | |
| locale | text | User’s language | e.g., en, fr, de |
Downloading the dish images
The following Python script downloads every image listed in dish_images.csv. It only needs Python 3, with no extra package.
Save it as download_dish_images.py, then run it with the path of dish_images.csv (taken out of the ZIP file):
python3 download_dish_images.py path/to/dish_images.csv
The images are saved in a dish_images folder next to the CSV file, named after the id column (for example 8f14e45f-ceea-467f-a0e6-3f8c5d1e2b7a.jpg).
Images already downloaded are skipped, so you can run the script again if it was interrupted.
Each ZIP file unpacks into a new folder, so after a refresh, copy the new dish_images.csv over the old one before running the script: only the new images are downloaded, and the old ones are kept.
On macOS, if every download fails with CERTIFICATE_VERIFY_FAILED, your Python (from python.org) doesn’t have its certificates installed yet: run Install Certificates.command from its folder in Applications, then run the script again.
"""Download the images listed in the dish_images.csv file of a MyFoodRepo cohort export.
Usage: python3 download_dish_images.py path/to/dish_images.csv
"""
import csv
import http.client
import mimetypes
import sys
import urllib.request
from pathlib import Path
if len(sys.argv) != 2:
sys.exit(__doc__)
csv_path = Path(sys.argv[1])
output_folder = csv_path.parent / "dish_images"
output_folder.mkdir(parents=True, exist_ok=True)
downloaded = skipped = failed = 0
with csv_path.open(newline="", encoding="utf-8") as csv_file:
for row in csv.DictReader(csv_file):
extension = mimetypes.guess_extension(row["content_type"]) or ""
image_path = output_folder / f"{row['id']}{extension}"
if image_path.exists():
skipped += 1
continue
try:
# The link redirects to the file storage; urllib follows the redirect.
with urllib.request.urlopen(row["url"], timeout=60) as response:
image = response.read()
# OSError covers HTTP errors, timeouts and dropped connections; HTTPException covers a
# response cut off halfway.
except (OSError, http.client.HTTPException) as error:
failed += 1
print(f"Could not download image {row['id']}: {error}", file=sys.stderr)
continue
# Write to a temporary file first, so an interrupted run leaves no half-written image.
partial_path = image_path.with_name(image_path.name + ".part")
partial_path.write_bytes(image)
partial_path.replace(image_path)
downloaded += 1
print(f"{downloaded} downloaded, {skipped} already there, {failed} failed.")
if failed:
print("If the links have expired (HTTP Error 404), generate a new export and run the script on its dish_images.csv.")
sys.exit(1)