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.createData()`

Learn: Documents

Create a collection document from an object that may contain metadata fields.

Signature

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

Description

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

If the following metadata fields are included, they populate the document data Object field:

id
ts
ttl
data.

Otherwise, the data field isn’t instantiated.

Parameters

Parameter Type Required Description

Parameter	Type	Required	Description
data	Object	true	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. Fields with keys that match metadata fields are moved to the `data` field. See Document fields that populate the `data` field.

data

Object

true

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.

Fields with keys that match metadata fields are moved to the data field. See Document fields that populate the data field.

Document fields that populate the `data` field

Name Type Required Description

Name	Type	Description
`ttl`	Time	Time-to-live (TTL) for the document. Only present if set. If not present or set to `null`, the document persists indefinitely.
`id`	ID	ID for the document. The ID is a string-encoded, 64-bit unsigned integer in the 2^53-1 range. The ID is unique within the collection. IDs are assigned at document creation. To create a document with a user-provided `id` using `collection.createData()`, you must use a secret with the `create_with_id` privilege. If not provided, Fauna generates the `id`.
`<USER_DEFINED_FIELD>`	Any supported data type	User-defined document field.

ttl

Time

Time-to-live (TTL) for the document. Only present if set. If not present or set to null, the document persists indefinitely.

id

ID for the document. The ID is a string-encoded, 64-bit unsigned integer in the 2^53-1 range. The ID is unique within the collection.

IDs are assigned at document creation. To create a document with a user-provided id using collection.createData(), you must use a secret with the create_with_id privilege. If not provided, Fauna generates the id.

<USER_DEFINED_FIELD>

Any supported data type

User-defined document field.

Return value

Type Description

Type	Description
<Document>	New collection document. A document’s data type is taken from its collection’s name. For example, `Product` for a document in the `Product` collection. See Document type.

New collection document.

A document’s data type is taken from its collection’s name. For example, Product for a document in the Product collection. See Document type.

Examples

Create a document with the id and coll metadata fields:

Customer.createData({
  id: 12345,
  coll: "Person",
  name: "John Doe",
  email: "john.doe@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "12345",
    country: "United States"
  }
})

{
  id: "412999820218728960",
  coll: Customer,
  ts: Time("2099-07-30T22:04:39.400Z"),
  cart: null,
  orders: "hdW...",
  name: "John Doe",
  email: "john.doe@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postalCode: "12345",
    country: "United States"
  },
  data: {
    coll: "Person",
    id: 12345
  }
}

createData() treats any metadata field as a document field and nests it in the document’s data property.

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!

collection.createData()