How to Import data into Directus using JSON

When setting up new tables in Directus, it is very likely that you have a purpose in mind and some existing data to include. Rather than having to ask someone to import the data directly to the database, you can import from the Directus UI. This article will cover how you can import JSON into your table.

The essential key for importing a JSON is to format the data correctly. Each field name must match exactly how they appear in the data model (generally all lowercase). Using the Import/Export section in the right side menu, click the import field and select your JSON file. Then click Start Import. Directus will validate your file then import the data.

Step 1: Format your JSON file

It's very important to ensure your the JSON is valid and formatted correctly. Each field is matched to the field names in Directus. To check, open the data model for you table and make note of the field names.

Using your data source, format the output into JSON whether it's natively through an API or export function, or if you need to write a script to convert it for you. The aim is to have a list of objects like the example below.

[
    {
    	"title": "Article 1",
        "slug": "article-1",
        "summary": "An interesting article about web",
        "description": "<p>Lots of interest facts about websites</p>",
        "icon": "globe"
    },
    {
    	"title": "Article 2",
        "slug": "article-2",
        "summary": "An interesting article about print",
        "description": "<p>Lots of interest facts about graphic design</p>",
        "icon": "pencil"
    },
]

If the field names require changing, open the JSON file in a text editor and use Find & Replace to change all the occurances of the previous field name to the new one making sure to be a strict as possible with the selection. For example: replace "article_title": with "title":.

You can use an online validation website to validate your JSON afterwards and make sure nothing has broken.

Step 2: Import the JSON into Directus

Open the collection where you intend to add the data. Expand the right menu and click on the Import/Export section.

Click on the import field, choose your JSON file and click Start Import.

And that's it, Directus will validate the file and import the data.

Limitations

I tried importing 1,000, 10,000, 50,000 records in one hit. I started having difficulties after 10,000 records but this also depends on your server settings such as request timeouts and resource limits. But either way, with records beyond 10,000, it's worth importing directly into the Database.

Also, your database may prevent primary key inserts. If you intend to include the primary key in the import, you'll need to make sure this is allowed on your database end. Otherwise, remove the ID from the JSON file and a new one will be assigned when the item is created.

Conclusion

Importing Data is a fantastic feature to empower users to move their data into Directus easily without needing access to the Databases. The trick is ensuring the JSON is formatted correctly first. If you want an example of how to format the file, you can export some existing records from your table and see how it's done.