lib-event 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793357862/FIN+5.3.1+lib-event 中文整理基于 FIN 5.3.1

导读： 事件数据库引擎

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• Overview
• Axon APIs
• Storage
• Observable
  • def
  • supertypes
• eventCreate(target, event)
• eventDelete(target, span, filter: null)
• eventRead(targets, span: null, filter: null, opts: null)
  • tags

---

概述（中译）

事件数据库引擎

---

API 正文（英文）

docs

Overview • Axon APIs • Storage • Observable

---

tags

event	Event dict - see docs
obsEvents	Subscribe to event creation - see docs

---

funcs

eventCreate	Asynchronously create a new event for the given target and return a future
eventDelete	Asynchronously delete a batch of events and return a future
eventRead	Read all the events for the given list of targets and span

---

lib event

Overview

The event extension provides a simple, open ended eventing engine. Events are timestamped dicts that are "attached" to any record in the Folio database. All events have the following tags:

• targetRef: reference to record the event is associated with
• ts: DateTime timestamp for the event
• event: marker tag

You can add any additional arbitrary tags based on your application.

Note: events are optimized to append new immutable dicts into storage. Although you can modify events with the eventDelete() function, it is very expensive and should be avoided in designs that use this API.

Axon APIs

You can create new events via the eventCreate() function. You must associated an event with a target record and a UTC timestamp. Here is a simple example to create an event under a site record:

read(site).eventCreate({ts:nowUtc(), dis:"My first event!"})

You can read events using the eventRead() function:

read(site).eventRead(null)

Events may be deleted using the eventDelete() function:

read(site).eventDelete(null)

There is no function to update an existing event. Instead using eventDelete to delete the old version, and then recreate it via eventCreate:

eventDelete(target, event->ts)
eventCreate(target, newEvent)

See caution above about using eventDelete to modify event storage.

Storage

Events are stored in a Folio blob by UTC date using a compact binary encoding. There is a max of 1MB available to store a single date (based on UTC time). If this limit is exceeded for a given date, then a StoreErr will be raised with the message "Data size exceeds limit". Deleting the target record will automatically delete all associated events.

Observable

You can subscribe to event creation via the obsEvents observable. See the observable docs for more information.

---

---

def

event

Event dict - see docs

---

meta

def	event
is	marker
lib	lib:event

---

supertypes

marker	Marker labels a dict with typing information

---

---

def

func:eventCreate

eventCreate(target, event)

Asynchronously create a new event for the given target and return a future. The target may be any value accepted by toRecId(). The event must be a dict the defines a ts DateTime with a UTC timezone. The event dict may not contain the event nor the targetRef tag.

Example:

read(equip).eventCreate({ts:nowUtc(), dis:"Interesting event"})

---

meta

def	func:eventCreate
is	func
lib	lib:event
name	eventCreate

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:eventDelete

eventDelete(target, span, filter: null)

Asynchronously delete a batch of events and return a future. The target may be any value accepted by toRecId(). If the span argument is a DateTime then we delete the event (or events) with the exact timestamp (any timezone may be used). Or span may be anything accepted by toSpan() to delete a range of whole dates. An optional filter may be specified to only delete events that match the filter. If both a span and filter are passed then we only delete if both match (using AND logic). Passing null for both span and filter deletes all events for the target.

Example:

// delete the event(s) for a specific timestamp
eventDelete(rec, ts)

// delete the event(s) for a specific timestamp and filter
eventDelete(rec, ts, myEvent)

// delete the events for a span
eventDelete(rec, lastMonth)

// delete the events for a span and filter
eventDelete(rec, lastMonth, level=="debug")

// delete all the events
eventDelete(rec, null, null)

---

meta

def	func:eventDelete
is	func
lib	lib:event
name	eventDelete

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:eventRead

eventRead(targets, span: null, filter: null, opts: null)

Read all the events for the given list of targets and span. Return the result as a grid. The targets may be any value accepted by toRecIdList(). The span may be any value accepted by toSpan() or null to read all stored events.

If the tz option is specified it is used for the timezone for all timestamps, otherwise results are returned using the timezone of the span (or if null the current timezone).

Examples:

// read all events for given rec
read(equip).eventRead(null)

// read events for a given date
eventRead(@xyz-123, today)

// read events for a list of targets
readAll(equip).eventRead(thisWeek)

// read events for a list of targets with a filter
readAll(equip).eventRead(thisWeek, severity=="warn")

// read results using a specific timezone
readAll(equip).eventRead(thisWeek, null, {tz:"Chicago"})

---

meta

def	func:eventRead
is	func
lib	lib:event
name	eventRead

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

obsEvents

Subscribe to event creation - see docs

---

meta

def	obsEvents
is	observable
lib	lib:event

---

supertypes

marker	Marker labels a dict with typing information
observable	Observable subscription - see docs

---

tags

obsFilter	Filter string to define the record data set observed