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.
You must define your properties first before importing. CSV columns are matched against existing property names, and unknown columns cause the import to fail.
File requirements
| Requirement | Value |
|---|
| Format | .csv only |
| Encoding | UTF-8 |
| Maximum rows | 1,000 per file |
| Header row | Required |
Required columns
| Column | Notes |
|---|
name | The unique sample name. Required on every row. |
Optional columns
| Column | Notes |
|---|
description | Free-text description. Replaces existing description if the sample is being updated. |
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”):
name,description,Brix,pH,Variety
Sample-001,Harvest A batch,18.5,3.42,Arabica
Sample-002,Harvest B batch,19.2,3.51,Arabica
Sample-003,Test batch,21.0,3.38,Robusta
Sample-004,,17.8,,Arabica
- 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.
| CSV content | Result |
|---|
name,Brix\nSample-001,19.0 | Brix updated to 19.0. pH and Variety left as-is. |
name,Brix,pH\nSample-001,19.0, | Brix updated to 19.0. pH target removed (empty cell). Variety untouched. |
name,Brix,pH,Variety\nSample-001,19.0,3.5, | Brix updated, pH updated, Variety target removed. |
name,description\nSample-001,New notes | Description replaced. All property targets untouched. |
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
Line 5: Name is required.
Unknown column
Unknown columns: weight, color. Define them as sample properties first.
name and description must match an existing property name. Define missing properties first, then re-import.
Invalid continuous value
Line 12 (Sample-042): Value '18,5' is not a valid number for property 'Brix'.
- 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
Line 7 (Sample-007): Value 'arabica' is not in categories for 'Variety': [Arabica, Robusta].
Other errors
| Error | Cause |
|---|
Only .csv files are accepted. | The file extension is not .csv |
File must be UTF-8 encoded. | The file has non-UTF-8 characters (e.g., Latin-1 encoding from Excel) |
CSV exceeds the maximum of 1000 rows. | Split your file into chunks of 1,000 rows or fewer |
CSV must have a 'name' column. | The header row does not include name |
Import flow
Click Import CSV
Opens the import dialog.
Choose your file
Drag and drop, or click to browse. Only .csv files are accepted.
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.
Success
On success, you see counts: New samples (created), Updated (existing), Errors (always 0 on 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. 
