collection.create()

Create a document in the collection.

Signature

create(data: { id: ID | Null, ttl: Time | Null, *: Any }) => <Document>

Description

Creates a document in the collection with the provided data.

Parameters

Parameter Type Required Description

data

Object

Yes

Object describing the document properties and values.

data fields

Name Type Required Description

id

ID | Null

Unique, immutable identifier for the document in the collection. If null or not provided, Fauna assigns an id.

To provide an id:

  • Create an ID using ID().

  • Provide a literal Int or literal String that be coerced into a 64-bit unsigned integer in the 253-1 range.

id is returned as a String.

ttl

Time | Null

Expiration timestamp for the document. When the ttl timestamp passes, Fauna deletes the document. Default = null, which persists the document indefinitely.

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!