FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

Create

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
Create( collection, param_object )
create( collection, param_object )
Create( collection, param_object )
Create( collection, param_object )
Create( collection, param_object )
Create( collection, param_object )

Description

The Create function adds a new document to a collection. The collection_ref parameter indicates in what collection the document should be created, while param_object has the document data and optional metadata.

Parameters

Parameter Type Definition and Requirements

collection

String or Reference

The name, or Reference, of the collection that should have the new document. A collection Reference can be acquired using the Collection function.

param_object

Object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

data

Object

An object with the fields and values for this document.

credentials

Object

Optional - The permissions for this document.

delegates

Array

Optional - An array of References that should be used for access control instead of this document. See delegates in the Security reference.

ttl

Timestamp

Optional - A timestamp that indicates the time-to-live for a document, which is when the document is removed from the collection and can’t be queried. The document history can continue to be accessed using the Events function, provided the events are in the history retention interval and the document reference is input to the Events function.

Returns

A document with the data and metadata about the results of the operations.

Field Name Field Type Definition and Requirements

ref

Reference

A reference to the created document.

data

Object

The created document data.

ts

Long

The timestamp, with microsecond resolution, associated with the creation of the document.

Examples

The following query creates a document by providing a reference to the collection "spells" and a param_object with a data field. The data field has the user data to be inserted for this document.

client.query(
  q.Create(
    q.Collection('spells'),
    {
      data: {
        name: 'Mountainous Thunder',
        element: 'air',
        cost: 15,
      },
    },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Collection("spells"), "268159557092508160"),
  ts: 1591995732300000,
  data: { name: 'Mountainous Thunder', element: 'air', cost: 15 }
}
result = client.query(
  q.create(
    q.collection("spells"),
    {
      "data": {
        "name": "Mountainous Thunder",
        "element": "air",
        "cost": 15
      }
    }
  )
)
print(result)
{'ref': Ref(id=269062149575279104, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592856511570000, 'data': {'name': 'Mountainous Thunder', 'element': 'air', 'cost': 15}}
result, err := client.Query(
	f.Create(
		f.Collection("spells"),
		f.Obj{
			"data": f.Obj{
				"name": "Mountainous Thunder",
				"element": "air",
				"cost": 15 }}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:map[cost:15 element:air name:Mountainous Thunder] ref:{280481791726322176 0xc00009a1b0 0xc00009a1b0 <nil>} ts:1603747130990000]
try
{
    Value result = await client.Query(
        Create(
            Collection("spells"),
            Obj(
                "data", Obj(
                    "name", "Mountainous Thunder",
                    "element", "air",
                    "cost", 15
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "280491264236847616", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756164680000),data: ObjectV(name: StringV(Mountainous Thunder),element: StringV(air),cost: LongV(15)))
System.out.println(
    client.query(
        Create(
            Collection("spells"),
            Obj(
                "data", Obj(
                    "name", Value("Mountainous Thunder"),
                    "element", Value("air"),
                    "cost", Value(15)
                )
            )
        )
    ).get());
{ref: ref(id = "269699776491028992", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593464599990000, data: {name: "Mountainous Thunder", element: "air", cost: 15}}
Create(
  Collection('spells'),
  {
    data: {
      name: 'Mountainous Thunder',
      element: 'air',
      cost: 15,
    },
  },
)
{
  ref: Ref(Collection("spells"), "302043888864985600"),
  ts: 1624310349250000,
  data: { name: 'Mountainous Thunder', element: 'air', cost: 15 }
}
Query metrics:

  •    bytesIn:  131

  •   bytesOut:  224

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:    0

  • writeBytes:  650

  •  queryTime: 32ms

  •    retries:    0

The following query creates a document in the posts collection with a defined document ID (using the Ref function):

serverClient.query(
  q.Create(
    q.Ref(q.Collection('Posts'), '1'),
    { data: { title: 'The first post' } },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Ref(Collection("Posts"), "1"),
  ts: 1622574501060000,
  data: { title: 'The first post' }
}
result = serverClient.query(
  q.create(
    q.ref(q.collection("Posts"), 1),
    {"data": {"title": "The first post"}}
  )
)
print(result)
{'ref': Ref(id=1, collection=Ref(id=Posts, collection=Ref(id=collections))), 'ts': 1622574508850000, 'data': {'title': 'The first post'}}
result, err := serverClient.Query(
	f.Create(
		f.Ref(f.Collection("Posts"), "1"),
		f.Obj{"data": f.Obj{"title": "The first post"}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:map[title:The first post] ref:{1 0xc00009dbc0 0xc00009dbc0 <nil>} ts:1622574332010000]
try
{
    Value result = await serverClient.Query(
        Create(
            Ref(Collection("Posts"), 1),
            Obj("data", Obj("title", "The first post"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "1", collection = RefV(id = "Posts", collection = RefV(id = "collections"))),ts: LongV(1622574261840000),data: ObjectV(title: StringV(The first post)))
System.out.println(
    serverClient.query(
        Create(
            Ref(Collection(Value("Posts")), Value(1)),
            Obj(
                "data", Obj(
                    "title", Value("The first post")
                )
            )
        )
    ).get());
{ref: ref(id = "1", collection = ref(id = "Posts", collection = ref(id = "collections"))), ts: 1622574416990000, data: {title: "The first post"}}
Create(
  Ref(Collection('Posts'), '1'),
  { data: { title: 'The first post' } },
)
{
  ref: Ref(Collection("Posts"), "1"),
  ts: 1624310598180000,
  data: { title: 'The first post' }
}
Query metrics:

  •    bytesIn:  117

  •   bytesOut:  176

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:   14

  • writeBytes:  352

  •  queryTime: 23ms

  •    retries:    0

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!