DEFINE EVENT

DEFINE EVENT statement

Events can be triggered after any change or modification to the data in a record. Each trigger is able to see the $before and $after value of the record, enabling advanced custom logic with each trigger.

Requirements

• You must be authenticated as a root or namespace user before you can use the DEFINE EVENT statement.
• You must select your namespace and database before you can use the DEFINE EVENT statement.

Statement syntax

SurrealQL Syntax

DEFINE EVENT @name ON [ TABLE ] @table [ WHEN @expression ] THEN @expression

Example usage

Below is an example showing how to create an event which upon updating a user's email address will create an entry recording the change on an event table.

-- Create a new event whenever a user changes their email address
-- One-statement event
DEFINE EVENT email ON TABLE user WHEN $before.email != $after.email THEN (
    CREATE event SET user = $value.id, time = time::now(), value = $after.email, action = 'email_changed'
);

-- Create a relation between a customer and a product whenever a purchase is made
-- Notice the subtle difference when we use multiple statements inside an event: 
-- we have to use {curly brackets} instead of (parenthesis)
DEFINE EVENT purchase ON TABLE purchase WHEN $before == NONE THEN {
    LET $from = (SELECT * FROM customer WHERE id == $after.customer);
    LET $to = (SELECT * FROM product WHERE id == $after.product);

    RELATE $from->purchases->$to CONTENT {
        quantity: $after.quantity,
        total: $after.total,
        status: 'Pending',
    };
};

Specific events

You can trigger events based on specific events. You can use the variable $event to detect what type of event is triggered on the table.

-- CREATE event is triggered when a new record is inserted into the table.
-- Here we are updating the status of the post to PUBLISHED
-- when a new record is inserted into the publish_post table.
DEFINE EVENT publish_post ON TABLE publish_post WHEN $event = "CREATE" THEN (
    UPDATE post SET status = "PUBLISHED" WHERE id = $after.post_id
);

-- UPDATE event
-- Here we are creating a notification when a user is updated.
DEFINE EVENT user_updated ON TABLE user WHEN $event = "UPDATE" THEN (
    CREATE notification SET message = "User updated", user_id = $after.id, created_at = time::now()
);

-- DELETE event is triggered when a record is deleted from the table.
-- Here we are creating a notification when a user is deleted.
DEFINE EVENT user_deleted ON TABLE user WHEN $event = "DELETE" THEN (
    CREATE notification SET message = "User deleted", user_id = $before.id, created_at = time::now()
); 

-- You can combine multiple events based on your use cases.
-- Here we are creating a log when a user is created, updated or deleted.
DEFINE EVENT user_event ON TABLE user WHEN $event = "CREATE" OR $event = "UPDATE" OR $event = "DELETE" THEN (
    CREATE log SET table = "user", event = $event, created_at = time::now()
);