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 annotations
  • annotations.csv: Collections of annotation items linked to dishes
  • cohorts.csv: Groups of users
  • comments.csv: User, collaborator, chatbot and system comments on dishes
  • dish_images.csv: Links to download the dish images
  • dishes.csv: User meal records
  • food_lists.csv: Collections of foods
  • food_nutrients.csv: Nutrient information for foods
  • foods.csv: Individual food items
  • info.txt: Database metadata
  • intakes.csv: User meal consumption records
  • nutrients.csv: Nutrient definitions
  • organizations.csv: Organization owning the cohort
  • participations.csv: User-cohort associations
  • product_nutrients.csv: Nutrient information for products
  • products.csv: Product information
  • users.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 created
  • awaiting_segmentation_service: Awaiting segmentation service
  • awaiting_llm_service: Awaiting LLM service
  • annotatable: Annotatable
  • info_asked: Info asked by collaborator to the user
  • requires_human_intervention: Requires collaborator intervention for annotation
  • annotated: 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 Generated in 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.csv stop 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 created
  • complete: All data is available
  • incomplete: 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)