import

Imports JSON or CSV files into Fauna collections.

fauna import [OPTIONS]

Description

The import command imports the contents of a JSON or CSV file, or a directory of JSON or CSV files, into a Fauna collection. If you import a directory of source files, each file is imported into a separate collection.

JSON source files must contain valid JSON, and each JSON object in the file becomes a document in the target collection.

CSV source files must be comma-delimited, and each line in the CSV file becomes a document in the target collection. A CSV file must have a header line containing the field names to be used in the target collection.

If your CSV file has rows which contain fewer fields than the number of fields in the header line, you can use the --allow-short-rows option to permit the import to proceed. Otherwise the import fails with an error. If you use the --allow-short-rows option, the documents imported from short rows do not contain the missing fields.

The target collection can be either an existing Fauna collection or a new one. If the target collection exists and is not empty, you must use the --append option, and the new documents are added to the existing collection. If you don’t specify a target collection, Fauna Shell uses the filename of the source file as the name of the target collection.

The --path option specifies the path to the source file or directory of source files, and it is required. If you don’t specify any other options, Fauna Shell uses the parameters specified in your fauna-shell configuration file.

To ensure the integrity of your data import, it is recommended that each record of your source file should include a unique identifying field. You can create a unique index on that field to ensure that no records are imported more than once, and you can query against the unique field to verify the completeness of your import.

Options

Option Description

--allow-short-rows

Optional - Allow CSV files in which some rows have fewer fields than the number of fields in the header row. Note that if import finds a row which has more fields than the number of fields in the header row, the import fails with an error.

--append

Optional - Append documents to an existing collection.

--collection=<collection>

Optional - Specifies the target collection to be created. Defaults to the filename of the source file.

--db=<db>

Optional - Specifies a child database in which to create a new target collection or append to an existing target collection. The parent database is always the database associated with the secret you specify for the command.

--path=<path>

Required - Specifies the path to a source file or directory of source files. Note that directories may only contain files, not additional directories. import does not recurse into sub-directories.

--domain=<domain>

Optional - The Fauna server domain, that is, the hostname where Fauna is running. Defaults to db.fauna.com.
Since the introduction of Region Groups, three cloud domains are available. Use the correct domain for your database’s Region Group.
Classic (US and EU): db.fauna.com
United States (US): db.us.fauna.com
Europe (EU): db.eu.fauna.com

--endpoint=<endpoint>

Optional - The name of the endpoint to use for the command.

--port=<port>

Optional - The connection port. Defaults to 8443.

--scheme=<scheme>

Optional - The connection scheme. Must be one of https or http. Defaults to https.

--secret=<secret>

Optional - The secret to use. A secret authenticates your connection to Fauna, and connects you to a specific database.

--timeout=<timeout>

Optional - The connection timeout, an integer number of milliseconds. When the specified period has elapsed, fauna-shell stops waiting for a response and displays an error.

The default is zero, which means that fauna-shell waits until a response is received.

--type=<column>::<type>

Optional - Specify a data type for a column. You can specify a column in your source file to be imported as one of the following data types:

  • number

  • date

  • bool

You can cast fields to type date which contain either a string date (such as "March 14, 1994") or seconds since epoch (such as 1494805725).

Examples

Import a JSON file

A file named zipcodes.json contains the following:

{ "zipcode" : "01001", "city" : "AGAWAM", "pop" : 15338, "state" : "MA" }
{ "zipcode" : "01002", "city" : "CUSHMAN", "pop" : 36963, "state" : "MA" }
{ "zipcode" : "01005", "city" : "BARRE", "pop" : 4546, "state" : "MA" }
{ "zipcode" : "01007", "city" : "BELCHERTOWN", "pop" : 10579, "state" : "MA" }
{ "zipcode" : "01008", "city" : "BLANDFORD", "pop" : 1240, "state" : "MA" }

The following terminal command imports zipcodes.json:

fauna import --path=./zipcodes.json
Start importing from zipcodes.json
5 documents imported from zipcodes.json to zipcodes
 ›   Success: Import from zipcodes.json to zipcodes completed

In the above command, no --collection option is specified, so Fauna Shell creates a new collection called zipcodes.

Import a JSON file and append to an existing collection

A file named zipcodes2.json contains the following:

{ "zipcode" : "01010", "city" : "BRIMFIELD", "pop" : 3706, "state" : "MA" }
{ "zipcode" : "01011", "city" : "CHESTER", "pop" : 1688, "state" : "MA" }
{ "zipcode" : "01012", "city" : "CHESTERFIELD", "pop" : 177, "state" : "MA" }

The following terminal command imports zipcodes2.json and appends the documents to the existing collection zipcodes:

fauna import --path=./zipcodes2.json --collection=zipcodes --append
Start importing from zipcodes2.json
3 documents imported from zipcodes2.json to zipcodes
 ›   Success: Import from zipcodes2.json to zipcodes completed

Import a JSON file with configuration options

The following terminal command overrides any configuration options in the fauna-shell configuration file:

fauna import --path=./zipcodes.json --scheme=https --domain=db.us.fauna.com --port=443 --secret=secret
Start importing from zipcodes.json
5 documents imported from zipcodes.json to zipcodes
 ›   Success: Import from zipcodes.json to zipcodes completed

Import a JSON file with type conversions

The following JSON object contains three string values:

{ "myDate" : "May 3, 2021", "myBool": "true", "myNumber" : "15338" }

To convert those string values to other types, you can use the --type option.

fauna import --path=./myFile.json --type=myDate::date --type=myBool::bool --type=myNumber::number
1 documents imported from myFile.json to myFile
 ›   Success: Import from myFile.json to myFile completed

The above JSON object becomes the following Fauna document:

{
  "ref": Ref(Collection("types"), "313718366743298625"),
  "ts": 1635443998950000,
  "data": {
    "myDate": Time("2021-05-03T07:00:00Z"),
    "myBool": true,
    "myNumber": 15338
  }
}

Import a directory of source files

A directory named source_files contains the following files:

myJSONfile1.json
myJSONfile2.json
myCSVfile1.csv
myCSVfile2.csv

The following command imports four files and creates four new collections:

fauna import --path=./source_files
Database connection established
Start importing from source_files/myJSONfile1.json
10 documents imported from myJSONfile1.json to myJSONfile1
 ›   Success: Import from myJSONfile1.json to myJSONfile1 completed
Start importing from source_files/myJSONfile2.json
10 documents imported from myJSONfile2.json to myJSONfile2
 ›   Success: Import from myJSONfile2.json to myJSONfile2 completed
Start importing from source_files/myCSVfile1.csv
10 documents imported from myCSVfile1.csv to myCSVfile1
 ›   Success: Import from myCSVfile1.csv to myCSVfile1 completed
Start importing from source_files/myCSVfile2.csv
10 documents imported from myCSVfile2.csv to myCSVfile2
 ›   Success: Import from myCSVfile2.csv to myCSVfile2 completed

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!