CSV imports

Appwrite's CSV Import feature allows you to create multiple rows in a table by uploading a single CSV file. This is especially useful for importing existing data, seeding test environments, or migrating from other systems.

This feature is available in both Appwrite Cloud and the self-hosted version.

Prepare your table

To get started, create a table in your database and define its columns. Your CSV file must match the structure of this table. All required columns must be present in the CSV. Each row is validated before being imported.

Each column in the CSV should map to a column key in your table, and each row should represent a new row.

An example of a valid CSV file for a table with the following columns:

• title (string)
• author (string)
• year (integer)
• available (boolean)

$id,title,author,year,available
f3k91x8b2q,Harry Potter and the Sorcerer's Stone,J.K. Rowling,1997,true
mz7lq3dp5c,The Fellowship of the Ring,J.R.R. Tolkien,1954,true
x0v4p8ncq2,To Kill a Mockingbird,Harper Lee,1960,false

Empty values

Different column types handle empty values differently:

• String columns: Empty values are interpreted as empty strings. To add null values to a string column, use the value null without quotes.
• Integer columns: Empty values are interpreted as null.
• Boolean columns: Empty values are interpreted as null.
• Array of any type: Empty values are interpreted as empty arrays.

Create and update timestamps

You can also optionally include $createdAt and $updatedAt columns to set custom timestamps for imported rows. If omitted, Appwrite sets these automatically during import.

An example of a valid CSV file with $createdAt and $updatedAt timestamps:

$id,$createdAt,$updatedAt,title,author,year,available
f3k91x8b2q,2025-08-10T12:34:56.000Z,2025-08-10T12:34:56.000Z,Harry Potter and the Sorcerer's Stone,J.K. Rowling,1997,true
mz7lq3dp5c,2025-08-11T09:15:00.000Z,2025-08-11T10:00:00.000Z,The Fellowship of the Ring,J.R.R. Tolkien,1954,true
x0v4p8ncq2,2025-08-12T08:00:00.000Z,2025-08-12T08:30:00.000Z,To Kill a Mockingbird,Harper Lee,1960,false

Arrays

You can also include data for array columns in your CSV file. For any column configured as an array, you can include a comma-separated list of values within double quotes ("one,two").

An example of a valid CSV file with an array column:

$id,title,author,year,available,categories
f3k91x8b2q,Harry Potter and the Sorcerer's Stone,J.K. Rowling,1997,true,"fiction,fantasy"
mz7lq3dp5c,The Fellowship of the Ring,J.R.R. Tolkien,1954,true,"fiction,fantasy"
x0v4p8ncq2,To Kill a Mockingbird,Harper Lee,1960,false,"fiction,nonfiction"

Relationships

If you want to create relationships between rows in different tables, you can provide the $id of the related row in the related table.

An example of a valid CSV file with relationships between tables where related_id is the $id of the related row in the related table:

$id,title,author,year,related_id
f3k91x8b2q,Harry Potter and the Sorcerer's Stone,J.K. Rowling,1997,id_1
mz7lq3dp5c,The Fellowship of the Ring,J.R.R. Tolkien,1954,id_2
x0v4p8ncq2,To Kill a Mockingbird,Harper Lee,1960,id_3

Permissions

You can set permissions for rows in your CSV file by adding data for the $permissions column. Make sure row-level security is enabled for your table.

An example of a valid permissions string:

"read(""any""),update(""users""),delete(""user:user_id"")"

The roles used are API strings that can be found in the permissions documentation.

A full example of a valid CSV file with row permissions:

name,$id,$permissions
blog-post-1,post-1,"read(""any""),update(""user:user_id""),delete(""user:user_id"")"
blog-post-2,post-2,"read(""guests""),update(""user:user_id"")"
blog-post-3,post-3,"read(""users""),update(""user:user_id""),delete(""user:user_id"")"
blog-post-4,post-4,"read(""any""),update(""team:team_id""),delete(""team:team_id"")"

Special characters

If your CSV file contains characters like double quotes (") or commas (,), you need to escape them.

Comma

There are different ways to escape commas based on different scenarios.

• If your column type is a string, you can enclose the value in double quotes ("comma,used,here").
• If your column type is a string array, you need to escape double quotes within the array to use a comma ("one,two,""comma,allowed,here""").

Double quotes

If you want to add double quotes to a string column, you need to escape them by doubling them (""), otherwise it will be treated as an array.

Import rows from the Console

To import rows using the Appwrite Console:

1. Go to your project -> Databases
2. Navigate to your target Table
3. Click on the Import CSV button in the action area
4. Upload a new CSV file or choose an existing file from your Storage bucket

CSV imports run as background tasks. The Console displays a floating progress bar while the import is active.

Additional resources

• Appwrite CLI
• Database Permissions
• Database API Reference