Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

collection.create()

Create a collection document.

Signature

create(data: { *: Any }) => <Document>

Description

Creates a document in the collection with user-provided document fields.

Reserved fields

You can’t use this method to write to the following metadata fields:

  • coll

  • ts

  • data

Parameters

Parameter Type Required Description

data

Object

Yes

Object containing the document’s fields.

For supported fields in user-defined collections, see Document fields.

To create a document with a user-provided id, you must use an authentication secret with the create_with_id privilege.

The object can’t include the following metadata fields:

  • coll

  • ts

  • data

Return value

Type Description

Document

New document.

Examples

Basic example

Customer.create({
  name: "John Doe",
  email: "john.doe@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "12345",
    country: "United States"
  }
})
{
  id: "12345",
  coll: Customer,
  ts: Time("2099-02-19T14:53:53.940Z"),
  cart: null,
  orders: "hdWCxmVPcmRlcoHKhGpieUN1c3RvbWVygcZidjD09oHNSgW6Vc/c8AIABAD2wYIaZxvNCBoz2yWAEA==",
  name: "John Doe",
  email: "john.doe@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "12345",
    country: "United States"
  }
}

Create with ID

You can specify a custom id when creating a document. The id must be unique within the collection:

Customer.create({
  id: "999",
  name: "Jane Doe",
  email: "jane.doe@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "12345",
    country: "United States"
  }
})

If you don’t specify an id`, Fauna auto-generates one.

To create documents with a custom id, you must have the create_with_id privilege on the collection.

Default values

A field definition can set a default field value for documents in a collection:

collection Customer {
  // `name` accepts `String` and `Null` values.
  // If missing, defaults to `unknown`.
  name: String? = "unknown"
  email: String
}

If you don’t provide a value during document creation, the document uses the default:

Customer.create({
  // The `name` field is missing.
  email: "john.doe@example.com"
})
{
  id: "12345",
  coll: Customer,
  ts: Time("2099-02-19T14:53:53.940Z"),
  email: "john.doe@example.com",
  // `name` defaulted to `unknown`.
  name: "unknown"
}

If you provide an explicit null value, the field is null. Fields with null values aren’t stored or returned.

Customer.create({
  // `name` is an explicit `null`.
  name: null,
  email: "jane.doe@example.com"
})
{
  id: "12345",
  coll: Customer,
  ts: Time("2099-02-19T14:53:53.940Z"),
  // `name` is not stored or returned.
  email: "jane.doe@example.com"
}

See also

ID()
newId()

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!