Insert

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.

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.

Parameters

Argument Type Definition and Requirements

ref

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

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 (FaunaDB uses 64-bit signed integers, whereas JavaScript uses 53-bit signed integers).

action

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

param_object

The param_object is an object which can contain many items.

param_object

Field Name Field Type Definition and Requirements

data

The document’s user data to be modified.

credentials

The document’s credentials to be modified.

delegates

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

The timestamp when the document’s history was modified.

action

The action for the event.

document

The reference to document where the event was inserted.

data

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 at id 181388642581742080, adding a document create operation at timestamp 1 with the associated user data:

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")
      )
    )
  )
);
{
  "ts": 1,
  "action": "create",
  "resource": { "@ref": "classes/spells/181388642581742080" }
}
curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "insert": { "@ref": "classes/spells/181388642581742080" },
          "ts": 1,
          "action": "create",
          "params": {
            "object": {
              "data": {
                "object": {
                  "name": "Mountain's Thunder",
                  "cost": 10,
                  "element": [ "air", "earth" ]
                }
              }
            }
          }
        }'
HTTP/1.1 200 OK
{
  "resource": {
    "ts": 1,
    "action": "create",
    "resource": { "@ref": "classes/spells/181388642581742080" }
  }
}
result, _ := client.Query(
    f.Insert(
        f.RefCollection(f.Collection("spells"), "181388642581742080"),
        1,
        f.ActionCreate,
        f.Obj{
            "data": f.Obj{
                "name": "Mountain's Thunder",
                "cost": 10,
                "element": f.Arr{"air", "earth"},
            },
        },
    ),
)

fmt.Println(result)
map[ts:1 action:create document:{181388642581742080 0xc420254480 <nil>} data:map[name:Mountain's Thunder cost:10 element:[air earth]]]
System.out.println(
    client.query(
       Insert(
           Ref(Collection("spells"), Value(181388642581742080L)),
           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"]
  }
}
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))
{ 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' ] } }
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"]
      }
    }
  )
)
{
  "ts": 1,
  "action": "create",
  "resource": { "@ref": "classes/spells/181388642581742080" }
}
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")
      )
    )
  )
)
{
  "ts": 1,
  "action": "create",
  "resource": { "@ref": "classes/spells/181388642581742080" }
}

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!