events

UserService::EventIndex

struct UserService::EventIndex {
    const psibase::AccountNumber service;      
    const uint64_t               serviceFlags; 

    setSchema(...); // Sets the schema associated with a service.
    addIndex(...);  // Requests an index. Indexes can improve the performance of queries involving the column. The indexes are subjective and MAY be adjusted by individual nodes. Indexes increase the CPU cost of transactions that create events. Block producers SHOULD use exactly the indexes requested by services to ensure consistent billing.
    init(...);      // Initializes the service
    sync(...);      // Indexes all new events. This is run automatically at the end of every transaction.
    onBlock(...);   // Runs in subjective mode at the end of each block
};

The events service maintains indexes for all events..

Queries for events use SQL and are sent to the /sql endpoint with Content-Type: application/sql

There is one table for each type of event, for example, "history.tokens.transferred". Note that double quotes are required because a . is not otherwise allowed in SQL table names.

Each field of the event is a column in the table. Types that are represented in json as a number, string, true, false, or null are represented by an appropriate SQL value and can be compared. Types that do not have a simple representation in SQL are represented by an opaque SQL value. The result of applying any operation to an opaque value other that returning it as a query result is unspecified.

The query result is returned as a JSON array of objects.

Example:

Given an event

void add(uint32_t x, uint32_t y, uint32_t sum);

the query

SELECT * FROM "history.example.add" WHERE sum > 10 ORDER BY x

might return a result that looks like

[{"x":5,"y":7,"sum":12},{"x":6,"y":5,"sum":11}]

UserService::EventIndex::setSchema

void UserService::EventIndex::setSchema(
    const psibase::ServiceSchema & schema
);

Sets the schema associated with a service..

UserService::EventIndex::addIndex

void UserService::EventIndex::addIndex(
    psibase::DbId          db,
    psibase::AccountNumber service,
    psibase::MethodNumber  event,
    std::uint8_t           column
);

Requests an index. Indexes can improve the performance of queries involving the column. The indexes are subjective and MAY be adjusted by individual nodes. Indexes increase the CPU cost of transactions that create events. Block producers SHOULD use exactly the indexes requested by services to ensure consistent billing..

UserService::EventIndex::init

void UserService::EventIndex::init();

Initializes the service.

UserService::EventIndex::sync

void UserService::EventIndex::sync();

Indexes all new events. This is run automatically at the end of every transaction..

UserService::EventIndex::onBlock

void UserService::EventIndex::onBlock();

Runs in subjective mode at the end of each block.