Version: 1.x

`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 [ IF NOT EXISTS ] @name ON [ TABLE ] @table [ WHEN @expression ] THEN @expression [ COMMENT @string ]

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,
        happened_at = time::now()
);

Using `IF NOT EXISTS` clause Since 1.3.0

The IF NOT EXISTS clause can be used to define an event only if it does not already exist. If the event already exists, the DEFINE EVENT statement will return an error.

-- Create a EVENT if it does not already exist
DEFINE EVENT IF NOT EXISTS example ON example THEN {};

DEFINE EVENT statement

Requirements​

Statement syntax​

Example usage​

Specific events​

Using IF NOT EXISTS clause Since 1.3.0​