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

For more details, review the migration guide. Contact support@fauna.com with any questions.

Events

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

 
Events( input )
events( input )
Events( input )
Events( input )
Events( input )

Description

The Events function returns a Set of events for the provided Reference. These events represent the history of the reference, and demonstrate when the reference was created, modified, or removed.

The kinds of events vary based on the kind of reference provided:

Singular references

  • create

  • delete

  • update

Set references

  • add

  • remove

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.

Parameter

Parameter Type Definition and Requirements

input

Set or Reference

A Set of References, or a singular Reference.

Returns

A Set containing the creation, modification, or deletion events related to the provided input. Each event in the set contains the following fields:

Field Name Field Type Definition and Requirements

action

String

The action applied to the instance during the event.

data

Object

Optional: only provided for documents containing user-supplied data. The data involved in the event.

instance

Reference

The Reference identifies the document associated with the event.

ts

Long

The timestamp, with microsecond resolution, associated with the event.

Examples

The following query fetches the events for a regular document:

client.query(
  q.Events(q.Ref(q.Collection('posts'), '233555580689580553'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
Events(Ref(Collection("posts"), "233555580689580553"))
result = client.query(
  q.events(q.ref(q.collection("posts"), "233555580689580553"))
)
print(result)
SetRef({'events': Ref(id=233555580689580553, collection=Ref(id=posts, collection=Ref(id=collections)))})
result, err := client.Query(
	f.Events(f.Ref(f.Collection("posts"), "233555580689580553")))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
{map[events:{233555580689580553 0xc000192180 0xc000192180 <nil>}]}
try
{
    Value result = await client.Query(
        Events(Ref(Collection("posts"), "233555580689580553"))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
SetRefV(System.Collections.Generic.Dictionary`2[System.String,FaunaDB.Types.Value])
Events(Ref(Collection('posts'), '233555580689580553'))
Events(Ref(Collection("posts"), "233555580689580553"))
Query metrics:

  •    bytesIn:  67

  •   bytesOut: 149

  • computeOps:   1

  •    readOps:   0

  •   writeOps:   0

  •  readBytes:   0

  • writeBytes:   0

  •  queryTime: 6ms

  •    retries:   0

And again, using Paginate to see the details of each event:

client.query(
  q.Paginate(q.Events(q.Ref(q.Collection('posts'), '233555580689580553')))
)
.then((ret) => console.log(util.inspect(ret, { depth: null })))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  data: [
    {
      ts: 1592269279120000,
      action: 'create',
      document: Ref(Collection("posts"), "233555580689580553"),
      data: { title: 'What I had for breakfast ..' }
    },
    {
      ts: 1592269279150000,
      action: 'update',
      document: Ref(Collection("posts"), "233555580689580553"),
      data: { tags: [ 'eggs', 'toast' ] }
    },
    {
      ts: 1592269279170000,
      action: 'delete',
      document: Ref(Collection("posts"), "233555580689580553"),
      data: null
    }
  ]
}
result = client.query(
  q.paginate(q.events(q.ref(q.collection("posts"), "233555580689580553")))
)
print(result)
{'data': [{'ts': 1592939385260000, 'action': 'create', 'document': Ref(id=233555580689580553, collection=Ref(id=posts, collection=Ref(id=collections))), 'data': {'title': 'What I had for breakfast ..'}}, {'ts': 1592939385290000, 'action': 'update', 'document': Ref(id=233555580689580553, collection=Ref(id=posts, collection=Ref(id=collections))), 'data': {'tags': ['eggs', 'toast']}}, {'ts': 1592939385310000, 'action': 'delete', 'document': Ref(id=233555580689580553, collection=Ref(id=posts, collection=Ref(id=collections))), 'data': None}]}
result, err := client.Query(
	f.Paginate(f.Events(f.Ref(f.Collection("posts"), "233555580689580553"))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:[map[action:create data:map[title:What I had for breakfast ..] document:{233555580689580553 0xc00009a240 0xc00009a240 <nil>} ts:1603747163140000] map[action:update data:map[tags:[eggs toast]] document:{233555580689580553 0xc00009a450 0xc00009a450 <nil>} ts:1603747163170000] map[action:delete data:{} document:{233555580689580553 0xc00019a0f0 0xc00019a0f0 <nil>} ts:1603747163190000]]]
try
{
    Value result = await client.Query(
        Paginate(Events(Ref(Collection("posts"), "233555580689580553")))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(data: Arr(ObjectV(ts: LongV(1603756294080000),action: StringV(create),document: RefV(id = "233555580689580553", collection = RefV(id = "posts", collection = RefV(id = "collections"))),data: ObjectV(title: StringV(What I had for breakfast ..))), ObjectV(ts: LongV(1603756294110000),action: StringV(update),document: RefV(id = "233555580689580553", collection = RefV(id = "posts", collection = RefV(id = "collections"))),data: ObjectV(tags: Arr(StringV(eggs), StringV(toast)))), ObjectV(ts: LongV(1603756294140000),action: StringV(delete),document: RefV(id = "233555580689580553", collection = RefV(id = "posts", collection = RefV(id = "collections"))),data: NullV)))
Paginate(Events(Ref(Collection('posts'), '233555580689580553')))
{
  data: [
    {
      ts: 1624310406540000,
      action: 'create',
      document: Ref(Collection("posts"), "233555580689580553"),
      data: { title: 'What I had for breakfast ..' }
    },
    {
      ts: 1624310406640000,
      action: 'update',
      document: Ref(Collection("posts"), "233555580689580553"),
      data: { tags: [ 'eggs', 'toast' ] }
    },
    {
      ts: 1624310406660000,
      action: 'delete',
      document: Ref(Collection("posts"), "233555580689580553"),
      data: null
    }
  ]
}
Query metrics:

  •    bytesIn:  80

  •   bytesOut: 625

  • computeOps:   1

  •    readOps:   1

  •   writeOps:   0

  •  readBytes: 302

  • writeBytes:   0

  •  queryTime: 6ms

  •    retries:   0

The following query fetches the events while using Singleton:

client.query(
  q.Paginate(
    q.Events(
      q.Singleton(q.Ref(q.Collection('posts'), '233555580689580553'))
    )
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  data: [
    {
      ts: 1592269043990000,
      action: 'add',
      document: Ref(Collection("posts"), "233555580689580553")
    },
    {
      ts: 1592269044060000,
      action: 'remove',
      document: Ref(Collection("posts"), "233555580689580553")
    }
  ]
}
result = client.query(
  q.paginate(
    q.events(
      q.singleton(q.ref(q.collection("posts"), "233555580689580553"))
    )
  )
)
print(result)
{'data': [{'ts': 1592939385260000, 'action': 'add', 'document': Ref(id=233555580689580553, collection=Ref(id=posts, collection=Ref(id=collections)))}, {'ts': 1592939385310000, 'action': 'remove', 'document': Ref(id=233555580689580553, collection=Ref(id=posts, collection=Ref(id=collections)))}]}
result, err := client.Query(
	f.Paginate(
		f.Events(
			f.Singleton(
				f.Ref(f.Collection("posts"), "233555580689580553")))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:[map[action:add document:{233555580689580553 0xc0000915c0 0xc0000915c0 <nil>} ts:1603747163140000] map[action:remove document:{233555580689580553 0xc0000917a0 0xc0000917a0 <nil>} ts:1603747163190000]]]
try
{
    Value result = await client.Query(
        Paginate(
            Events(Singleton(Ref(Collection("posts"), "233555580689580553")))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(data: Arr(ObjectV(ts: LongV(1603756294080000),action: StringV(add),document: RefV(id = "233555580689580553", collection = RefV(id = "posts", collection = RefV(id = "collections")))), ObjectV(ts: LongV(1603756294140000),action: StringV(remove),document: RefV(id = "233555580689580553", collection = RefV(id = "posts", collection = RefV(id = "collections"))))))
Paginate(
  Events(
    Singleton(Ref(Collection('posts'), '233555580689580553'))
  )
)
{
  data: [
    {
      ts: 1624310406540000,
      action: 'add',
      document: Ref(Collection("posts"), "233555580689580553")
    },
    {
      ts: 1624310406660000,
      action: 'remove',
      document: Ref(Collection("posts"), "233555580689580553")
    }
  ]
}
Query metrics:

  •    bytesIn:  94

  •   bytesOut: 360

  • computeOps:   1

  •    readOps:   1

  •   writeOps:   0

  •  readBytes: 302

  • writeBytes:   0

  •  queryTime: 6ms

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