Skip to main content
If you have many samples to add or many property values to update, importing from CSV is much faster than the manual dialog. Click Import CSV on the Samples page.
CSV import dialog showing drag-and-drop upload zone and file picker
You must define your properties first before importing. CSV columns are matched against existing property names, and unknown columns cause the import to fail.

​
CSV format

​
File requirements

​
Required columns

​
Optional columns

​
Property columns

Every other column header must match the exact name of a property defined in your project (case-sensitive). The values in those columns become the sample targets.

​
Example

For a project with properties Brix (continuous), pH (continuous), and Variety (categorical with categories “Arabica”, “Robusta”):
Notes on this example:
  • Sample-004 has no description (empty cell)
  • Sample-004 has no pH value (empty cell removes any existing pH target)
  • All three samples have all required columns

​
Upsert behavior

CSV import is an upsert, meaning it creates new samples and updates existing ones in the same operation.

​
When the sample name does not exist

A new sample is created using the row’s name, description, and property values.

​
When the sample name already exists

The existing sample is updated:
  • Description is replaced with the new value (even if blank)
  • For each property column present in the CSV:
    • If the cell has a value, the property target is created or updated
    • If the cell is empty, the existing property target is deleted
  • Property targets for properties not in the CSV are left untouched
This is the most important rule to understand. The CSV scopes which properties are managed by which columns are present.

​
Examples

Scenario: Project has properties Brix, pH, Variety. Sample-001 already exists with Brix=18.5, pH=3.42, Variety=Arabica.
To fully reset a sample’s properties, include all property columns in the CSV with empty cells for the ones you want to clear.

​
Validation

The whole CSV is validated before any change is saved. If any row has any error, nothing is imported.

​
Empty name

Every row must have a name.

​
Unknown column

Every column other than name and description must match an existing property name. Define missing properties first, then re-import.

​
Invalid continuous value

Continuous values must be parseable as a number. Common causes:
  • Comma instead of dot for decimals (use 18.5, not 18,5)
  • Units mixed with the value (use 18.5, not 18.5 °Bx)
  • Stray spaces or non-numeric characters

​
Invalid categorical value

Categorical values must match one of the property’s categories exactly. Categories are case-sensitive.

​
Other errors

​
Import flow

1

Click Import CSV

Opens the import dialog.
2

Choose your file

Drag and drop, or click to browse. Only .csv files are accepted.
3

Review

Chemolytic validates the file before saving anything. If errors are found, you see a list of them by line number with the exact error message. Fix the file and re-import.
4

Success

On success, you see counts: New samples (created), Updated (existing), Errors (always 0 on a successful import).
CSV import result showing created and updated counts after a successful import

​
Tips

Re-importing the same file is safe. Existing samples are matched by name and updated in place. Use this to iterate on your data.
Use Excel carefully. Excel can silently change number formats, encodings, and date columns. Always export as CSV UTF-8 (not “CSV” which may be Latin-1 on Windows).
Keep a master CSV file. Treat it as the source of truth for your samples. Make changes there, re-import to update Chemolytic.

​
Plan limits

The plan limit on samples per project is checked when importing. If your CSV would exceed the limit, the import is rejected before any change is made.