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.

Insert

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

 
Insert( ref, ts, action, param_object )
insert( ref, ts, action, param_object )
Insert( ref, ts, action, param_object )
Insert( ref, ts, action, param_object )
Insert( ref, ts, action, param_object )
Insert( ref, ts, action, param_object )

Description

The Insert function adds an event to a document’s history at a specified timestamp.

The ref parameter must be a reference to a document within a user-defined collection.

We do not recommend using the update action. Currently, it operates like a create action. For example, if you create a document, and then use Insert to create an update, the document then looks identical to the update; any fields not specified are removed.
Since documents are stored immutably within Fauna, events are stored as snapshots of the associated document. Directly manipulating document history, using the Insert and Remove functions, does not currently affect subsequent event snapshots.

Parameters

Parameter Type Definition and Requirements

ref

Reference

A reference must refer to a user-defined collection or a key to be modified. A reference to any other collection results in an "invalid argument" error.

ts

Long or Timestamp

The timestamp within the document’s history that should be modified. Can be expressed as either a number of UNIX microseconds or as a Timestamp.

For large values of ts (positive or negative), you may need to express the value in a String to maintain numeric precision (Fauna uses 64-bit signed integers, whereas JavaScript uses 53-bit signed integers).

action

String

The type of action (create, delete, update) to be inserted.

param_object

Object

The param_object is an object which can contain many items.

param_object

Field Name Field Type Definition and Requirements

data

Object

The document’s user data to be modified.

credentials

Object

The document’s credentials to be modified.

delegates

Object

The document’s delegates to be modified.

Returns

An object containing the metadata about the insert operation.

Field Name Field Type Definition and Requirements

ts

Long

The timestamp when the document’s history was modified.

action

String

The action for the event.

document

Reference

The reference to document where the event was inserted.

data

Object

A copy of the document data that was created, updated, or deleted.

Examples

The following query modifies the history of the "spells" collection for the document ID 181388642581742080, adding a document create operation at timestamp 1 with the associated user data:

client.query(
  q.Insert(
    q.Ref(q.Collection('spells'), '181388642581742080'),
    1,
    'create',
    {
      data: {
        name: 'Mountain\'s Thunder',
        cost: 10,
        element: ['air', 'earth'],
      },
    },
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ts: 1,
  action: 'create',
  document: Ref(Collection("spells"), "181388642581742080"),
  data: { name: "Mountain's Thunder", cost: 10, element: [ 'air', 'earth' ] }
}
result = client.query(
  q.insert(
    q.ref(q.collection("spells"), "181388642581742080"),
    ts=1,
    action="create",
    params={
      "data": {
        "name": "Mountain's Thunder",
        "cost": 10,
        "element": ["air", "earth"]
      }
    }
  )
)
print(result)
{'ts': 1, 'action': 'create', 'document': Ref(id=181388642581742080, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': {'name': "Mountain's Thunder", 'cost': 10, 'element': ['air', 'earth']}}
result, err := client.Query(
	f.Insert(
		f.Ref(f.Collection("spells"), "181388642581742080"),
		1,
		f.ActionCreate,
		f.Obj{
			"data": f.Obj{
				"name": "Mountain's Thunder",
				"cost": 10,
				"element": f.Arr{"air", "earth"}}}))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[action:create data:map[cost:10 element:[air earth] name:Mountain's Thunder] document:{181388642581742080 0xc000168180 0xc000168180 <nil>} ts:1]
try
{
    Value result = await client.Query(
        Insert(
            Ref(Collection("spells"), "181388642581742080"),
            ts: 1,
            action: "create",
            @params: Obj(
                "data", Obj(
                    "name", "Mountain's Thunder",
                    "cost", 10,
                    "element", Arr("air", "earth")
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ts: LongV(1),action: StringV(create),document: RefV(id = "181388642581742080", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: ObjectV(name: StringV(Mountain's Thunder),cost: LongV(10),element: Arr(StringV(air), StringV(earth))))
System.out.println(
    client.query(
        Insert(
            Ref(Collection("spells"), Value("181388642581742080")),
            Value(1),
            Action.CREATE,
            Obj(
                "data", Obj(
                    "name", Value("Mountain's Thunder"),
                    "cost", Value(10),
                    "element", Arr(Value("air"), Value("earth"))
                )
            )
        )
    ).get());
{ts: 1, action: "create", document: ref(id = "181388642581742080", collection = ref(id = "spells", collection = ref(id = "collections"))), data: {name: "Mountain's Thunder", cost: 10, element: ["air", "earth"]}}
Insert(
  Ref(Collection('spells'), '181388642581742080'),
  1,
  'create',
  {
    data: {
      name: 'Mountain\'s Thunder',
      cost: 10,
      element: ['air', 'earth'],
    },
  },
)
{
  ts: 1,
  action: 'create',
  document: Ref(Collection("spells"), "181388642581742080"),
  data: { name: "Mountain's Thunder", cost: 10, element: [ 'air', 'earth' ] }
}
Query metrics:

  •    bytesIn:   199

  •   bytesOut:   241

  • computeOps:     1

  •    readOps:     0

  •   writeOps:     3

  •  readBytes:   242

  • writeBytes: 2,184

  •  queryTime: 111ms

  •    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!