Anyone who works with CSVs knows they are, let’s say… finicky. And if you've never worked them, you may be asking yourself "What's a CSV?".
Please don’t hesitate to reach out if you’d like some help downloading, formatting, or uploading a CSV.
General CSV Information
- A CSV is a comma-separated values file. They can be viewed in spreadsheet format, with columns and rows, or as lines of plain text, wherein each data element is separated by a comma (for example: title,artist,date).
- To help you get started, the MOON Object System generates helpful, downloadable CSVs based on the fields in your Blueprints.
- Object data can only be uploaded via CSV for a single Blueprint type. For example, if you’d like to add a group of 20 oil paintings, you’d upload new object information using one Blueprint CSV.
- Our CSV upload is limited to 500 objects at a time.
- If you’re uploading more than 500 objects, you’ll need to upload multiple CSVs.
- The CSV must be encoded in UTF-8 format.
PLEASE NOTE: To preserve special characters like diacritics in a CSV, we recommend viewing, updating, or exporting using Google Sheets, Apple Pages, Airtable, or a plain text editor. Microsoft Excel may not preserve special characters.
Downloading a Blueprint’s CSV Template
The first step to uploading a group of new objects is to download a handy CSV template for your Blueprint. There are two ways to do this.
From your selected Blueprint, click on the arrow at far right (above the Add Row section). Click on Download CSV.
Or, from your Objects page, filter objects by the selected Blueprint. In this example, we’ll choose Paintings.
Icons for uploading and downloading will appear at right. Click the downward pointing arrow.
You’ll see a popup that asks if you need the Blueprint CSV Template. Click on the blue link to download it.
PLEASE NOTE: When adding a group of new objects, it’s best to use the Blueprint’s CSV Template. For editing information for existing objects and adding new objects, use the Blueprint’s Object Data CSV, which will include object information (more on this coming up).
Import New Objects Using a Blueprint’s CSV Template
The first line in the CSV template (the column headings) will correspond to the field ids in your selected Blueprint. DO NOT alter these headings.
Add your object information values to the CSV template.
Remember we mentioned CSVs are finicky? These rules MUST be followed:
- For the Blueprint field, capitalization matters. You must match the capitalization you used for the name of your Blueprint.
- Every object must have a title.
- If a row has data, there cannot be any empty fields in that row. You must add a hyphen in an empty field to preserve order (see the two fields with hyphens highlighted in gray below).
You can view the CSV and add data in spreadsheet format (recommended) or with a plain text editor (see the examples below). Notice the hyphens in the second example.
Save your CSV, go back to the Objects page, and filter your objects by the same Blueprint.
Click on the upload icon (the upward facing arrow) to import.
Upload your CSV.
You’ll receive a message letting you know the objects were added successfully.
PLEASE NOTE: When you upload a CSV with new objects, make sure to upload it only once – otherwise duplicate objects will be created.
Import Updated Information for a Group of Objects
To edit information for a group of objects (with the option of adding new ones), go to the Objects page and filter your objects by the desired Blueprint. Then click on the download option for that Blueprint (see instructions above).
You’ll be given an option to download the Object Data for the Blueprint as JSON or CSV. Choose Download CSV.
The CSV will include your existing object data. In this example, five objects use the Paintings Blueprint. Notice the hyphens where there are no information values.
- The first line in the Object Data CSV (the column headings) will correspond to the field ids in your selected Blueprint. DO NOT alter these headings.
- Objects will have an object id (oid). DO NOT alter the oids.
- The CSV will include a column heading called ostatus (object status), and the fields below will contain hyphens. DO NOT alter these ostatus fields (unless you plan to delete objects – see below).
- You will see hyphens in empty fields with no information values. If you have data to enter in a specific field, you can add it to replace the hyphen. Otherwise, DO NOT alter these.
Edit the object information in the CSV. PLEASE NOTE: Once uploaded, any updated information will overwrite old information.
If you add new objects, you must enter a hyphen in any empty fields (for example, oid and ostatus). Here we're adding a row for an object titled A Vase of Flowers. Because it's a new object, it will not have an oid (object id). Remember, every object must have a title.
ADVANCED OPTION: To duplicate an existing object, replace its object id (oid) with a hyphen. This will create a new, duplicated object once uploaded.
Input and save the information in the CSV. For rows with data, make sure you don’t have any empty fields.
Go back to the Objects page and filter your objects by the same Blueprint. Click on the upload icon (the upward facing arrow) to import. PLEASE NOTE: Once uploaded, any updated information will overwrite old information.
Upload your CSV. You’ll receive a message letting you know the objects were added successfully.
PLEASE NOTE: When you upload a CSV with new objects, make sure to upload it only once – otherwise duplicate objects will be created.
Add a New Column Heading to a CSV
Any column headings you add to a CSV must be lowercase and must not include punctuation, numbers, or special characters. Replace any spaces with hyphens or underscores.
For example, a column heading with the name Frame Information would look like: frame-information (all lowercase, hyphen instead of a space between words).
Input object data for the new column. Remember to use a hyphen if there is no information.
PLEASE NOTE: If a row has data, there must not be any empty fields. You must add a hyphen to preserve order.
Any additional column headings and informational values you add to the CSV will appear in the "All Data" section for the respective object. For more information, see Navigating "All Data".
Delete a Group of Objects
Go to the Objects page and filter your objects by the desired Blueprint. Click the download option for that Blueprint (see instructions above).
You’ll be given an option to download the object data for the Blueprint as JSON or CSV. Choose Download the CSV.
The CSV will include your existing object data.
It will include a column heading called ostatus. You can delete an object by entering the word delete (lowercase) in the field value in the ostatus column.
PLEASE NOTE: For objects you do not wish to delete, make sure there are hyphens in the ostatus fields. In this example, we're only deleting A Bouquet of Flowers.
Once you’ve input and saved the information in the CSV, go back to the Objects page and filter your objects by the same Blueprint.
Click on the upload icon (the upward facing arrow) to import. PLEASE NOTE: Once uploaded, any updated information will overwrite old information.
Upload your CSV. The deleted objects will be removed from your Base.
Questions about CSVs? Reach out