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!