ores.refdata.calendar

Table of Contents

Validated enumeration of named date collections consumed by ORE and QuantLib: business-day/holiday calendars (TARGET, UnitedStates, UnitedStates.GovernmentBond, …), central-bank meeting calendars, and other calendar-shaped reference data. Each row is one concrete QuantLib/ORE calendar token — sub-market variants (e.g. UnitedStates.NYSE vs UnitedStates.GovernmentBond) are separate rows, not a joined variant field, so the code column always matches ORE's XML <Calendar> vocabulary verbatim. Classified by calendar_type and associated with the country whose calendar it is — supranational calendars (TARGET) use the ZZ sentinel (ISO 3166-1's own reserved user-assigned code) rather than a nullable country reference, since no single country owns them.

Flags

:seed_country_sentinel:: the eventing integration test writes a synthetic calendar (always country_code ZZ), and the calendars insert trigger validates country_code against the countries table for the write tenant — the test must seed the ZZ sentinel country first (see refdata_calendars_create.sql's country_code_validation paste block).

Columns

code

QuantLib/ORE calendar token, verbatim (e.g. "TARGET", "UnitedStates", "UnitedStates.GovernmentBond", "UnitedKingdom", "Japan").

std::string("X")

name

Human-readable, unique display name (e.g. "TARGET (Euro area)", "United States (Government Bond)").

"Test Calendar " + std::to_string(faker::number::integer(1000, 9999))

calendar_type

Classification of the calendar's purpose; soft FK to ores_refdata_calendar_types_tbl (e.g. "public_holiday", "central_bank_meeting", "financial_centre", "data_release", "other").

std::string("public_holiday")

country_code

ISO 3166-1 alpha-2 country code of the calendar's owning country; soft FK to ores_refdata_countries_tbl. Supranational or non-country- specific calendars (e.g. "TARGET") use the reserved ZZ user-assigned code rather than a nullable reference.

std::string("ZZ")
-- Paste block: doesn't fit soft_fk_validations (joins on id, not
-- an alpha-2 code column) or the Validations table
-- (ores_refdata_validate_country_fn only checks non-null/empty,
-- not existence).
if not exists (
    select 1 from ores_refdata_countries_tbl
    where tenant_id = NEW.tenant_id
      and alpha2_code = NEW.country_code
      and valid_to = ores_utility_infinity_timestamp_fn()
) then
    raise exception 'Invalid country_code: %. Must be a valid ISO 3166-1 alpha-2 code (or the ZZ sentinel).',
        NEW.country_code;
end if;

image_id

Optional reference to a flag or logo image in the images table — overrides the country-flag icon derived from country_code (e.g. for a central bank's own logo, or a currency-union flag for a supranational calendar).

std::nullopt

source

Soft-enum: quantlib | user | federalreserve.gov. quantlib means this template's rule set was transcribed from QuantLib's published rules and matches one of ORE's recognised built-in calendar names – a taxonomic fact driving read-only enforcement and the ORE-export skip logic, not an instruction to call the QuantLib library (QuantLib is not linked at runtime; see this task's * Revision section). user means a calendar template authored in ORE Studio, fully editable. federalreserve.gov marks the ORE-native US.FOMC calendar, whose meeting dates are transcribed from the Fed's published calendar into calendar_event rows (story: FOMC-dated OIS short end); it is editable like user rows but is not a general user-authored template.

std::string("quantlib")

is_editable

Whether users can edit this template's own row (name, calendar_type, country_code, …) directly. Independent column from source – every quantlib row is inserted with false and every user row with true, but that pairing is enforced by the insert trigger's validation, not hardcoded from source in application code, per this task's instruction that read-only/editable be tracked per-template rather than assumed from source.

false

base_calendar_code

Soft FK to this same table's own code column (self-referential). Only meaningful for source = 'user' rows: present means this template is a delta on top of another template (QuantLib-sourced or itself user-authored) via that template's own calendar_exception rows; absent means a wholly bespoke calendar with no base. Always null for source = 'quantlib' rows.

std::nullopt
-- Paste block: self-referential soft FK (joins the same table
-- against itself), doesn't fit soft_fk_validations. Only checked
-- when present -- a null base_calendar_code is always valid (a
-- base-less template, QuantLib or user-authored).
if NEW.base_calendar_code is not null and not exists (
    select 1 from ores_refdata_calendars_tbl
    where tenant_id = NEW.tenant_id
      and code = NEW.base_calendar_code
      and valid_to = ores_utility_infinity_timestamp_fn()
) then
    raise exception 'Invalid base_calendar_code: %. No active calendar found with this code.',
        NEW.base_calendar_code;
end if;

SQL

Flags

Extra drops

drop function if exists ores_refdata_validate_calendar_fn;

Validation function

Insert trigger

Validations

column validation_function
calendar_type ores_refdata_validate_calendar_type_fn
change_reason_code ores_dq_validate_change_reason_fn

C++

Flags

Repository

Domain includes

#include <boost/uuid/uuid.hpp>
#include <chrono>
#include <optional>
#include <string>

Entity includes

#include <optional>
#include <string>

Conventions

Table display

column header
code Code
name Name
calendar_type Type
country_code Country
modified_by Modified By
version Version

Qt

Detail fields

field label widget type is_key is_required placeholder flag_source combo_fetch combo_allow_blank combo_domain_type combo_fetch_include combo_fetch_fn combo_watcher_name combo_code_field combo_tooltip_field combo_sort_field combo_label combo_setter_pascal badge_key view_group immutable combo_blank_label
code Code codeEdit line_edit true true Enter QuantLib calendar code                           General    
name Name nameEdit line_edit   true Enter calendar name                           General    
calendar_type Type calendarTypeCombo dynamic_combo             refdata::domain::calendar_type ores.qt/LookupFetcher.hpp fetch_calendar_types calendarTypeWatcher code description display_order calendar types CalendarTypeCombo calendar_type General    
country_code Country countryCodeCombo flagged_combo       country fetch_country_codes true   ores.qt/LookupFetcher.hpp                 General    
source Source sourceEdit line_edit   true quantlib or user                           General true  
is_editable Editable isEditableCheck check_box                                 General true  
base_calendar_code Base Calendar baseCalendarCodeCombo dynamic_combo             refdata::domain::calendar ores.qt/LookupFetcher.hpp fetch_calendars calendarBaseCalendarWatcher code code version calendars BaseCalendarCodeCombo   General   No Base Calendar

Columns (Qt model)

enum_name field header type width import_preview is_badge badge_key hidden_by_default
Code code Code string auto true      
CalendarName name Name string auto true      
CalendarType calendar_type Type string auto   true calendar_type  
CountryCode country_code Country string 80        
Version version Version int 70        
ModifiedBy modified_by Modified By string auto        

Icon columns (Qt model)

Country gets its own flag icon in the list, keyed by country_code via the generic country-code accessor (same mechanism as business_centre's country_alpha2_code) – this is independent of the row's own getCalendarFlagIcon chain (own image_id -> else country_code) used for the primary Code column's icon.

column accessor field1 field2
CountryCode country_flag_icon country_code  

Custom generator declarations

/**
 * @brief Generates the full QuantLib calendar set as real reference data.
 *
 * Transcribed from QuantLib's calendar headers (ql/time/calendars/):
 * one row per concrete calendar token, including sub-market variants
 * (e.g. UnitedStates.NYSE, UnitedStates.GovernmentBond) as distinct
 * rows rather than a joined variant field. This is real reference
 * data, not fictional test data — every code matches ORE's XML
 * <Calendar> vocabulary verbatim.
 */
ORES_REFDATA_API_EXPORT std::vector<domain::calendar>
generate_quantlib_calendars(utility::generation::generation_context& ctx);

Custom generator implementations

std::vector<domain::calendar>
generate_quantlib_calendars(utility::generation::generation_context& ctx) {
    const auto modified_by = ctx.env().get_or(generation_keys::modified_by, "system");
    const auto tid = ctx.env().get_or(generation_keys::tenant_id, "system");
    const auto parsed_tid = utility::uuid::tenant_id::from_string(tid);
    const auto tenant_id =
        parsed_tid.has_value() ? parsed_tid.value() : utility::uuid::tenant_id::system();
    const auto now = ctx.past_timepoint();

    struct row { const char* code; const char* name; const char* type; const char* country; };
    static constexpr row rows[] = {
        // Supranational
        {"TARGET", "TARGET (Euro area)", "public_holiday", "ZZ"},
        {"WeekendsOnly", "Weekends Only", "public_holiday", "ZZ"},
        // Single-market national calendars
        {"Argentina", "Argentina", "public_holiday", "AR"},
        {"Australia", "Australia", "public_holiday", "AU"},
        {"Austria", "Austria", "public_holiday", "AT"},
        {"Botswana", "Botswana", "public_holiday", "BW"},
        {"Brazil", "Brazil", "public_holiday", "BR"},
        {"Chile", "Chile", "public_holiday", "CL"},
        {"CzechRepublic", "Czech Republic", "public_holiday", "CZ"},
        {"Denmark", "Denmark", "public_holiday", "DK"},
        {"Finland", "Finland", "public_holiday", "FI"},
        {"France", "France", "public_holiday", "FR"},
        {"HongKong", "Hong Kong", "public_holiday", "HK"},
        {"Hungary", "Hungary", "public_holiday", "HU"},
        {"Iceland", "Iceland", "public_holiday", "IS"},
        {"India", "India (National Stock Exchange)", "financial_centre", "IN"},
        {"Italy", "Italy", "public_holiday", "IT"},
        {"Japan", "Japan", "public_holiday", "JP"},
        {"Mexico", "Mexico", "public_holiday", "MX"},
        {"NewZealand", "New Zealand", "public_holiday", "NZ"},
        {"Norway", "Norway", "public_holiday", "NO"},
        {"Poland", "Poland", "public_holiday", "PL"},
        {"Romania", "Romania", "public_holiday", "RO"},
        {"Russia", "Russia", "public_holiday", "RU"},
        {"SaudiArabia", "Saudi Arabia", "public_holiday", "SA"},
        {"Singapore", "Singapore", "public_holiday", "SG"},
        {"Slovakia", "Slovakia", "public_holiday", "SK"},
        {"SouthAfrica", "South Africa", "public_holiday", "ZA"},
        {"Sweden", "Sweden", "public_holiday", "SE"},
        {"Switzerland", "Switzerland", "public_holiday", "CH"},
        {"Taiwan", "Taiwan", "public_holiday", "TW"},
        {"Thailand", "Thailand", "public_holiday", "TH"},
        {"Turkey", "Turkey", "public_holiday", "TR"},
        {"Ukraine", "Ukraine", "public_holiday", "UA"},
        // United States (Market enum)
        {"UnitedStates.Settlement", "United States (Settlement)", "public_holiday", "US"},
        {"UnitedStates.NYSE", "United States (NYSE)", "financial_centre", "US"},
        {"UnitedStates.GovernmentBond", "United States (Government Bond)", "financial_centre", "US"},
        {"UnitedStates.NERC", "United States (NERC)", "financial_centre", "US"},
        {"UnitedStates.LiborImpact", "United States (Libor Impact)", "financial_centre", "US"},
        {"UnitedStates.FederalReserve", "United States (Federal Reserve)", "financial_centre", "US"},
        {"UnitedStates.SOFR", "United States (SOFR)", "financial_centre", "US"},
        // United Kingdom (Market enum)
        {"UnitedKingdom.Settlement", "United Kingdom (Settlement)", "public_holiday", "GB"},
        {"UnitedKingdom.Exchange", "United Kingdom (Exchange)", "financial_centre", "GB"},
        {"UnitedKingdom.Metals", "United Kingdom (Metals)", "financial_centre", "GB"},
        // China (Market enum)
        {"China.SSE", "China (Shanghai Stock Exchange)", "financial_centre", "CN"},
        {"China.IB", "China (Interbank)", "financial_centre", "CN"},
        // Germany (Market enum)
        {"Germany.Settlement", "Germany (Settlement)", "public_holiday", "DE"},
        {"Germany.FrankfurtStockExchange", "Germany (Frankfurt Stock Exchange)", "financial_centre", "DE"},
        {"Germany.Xetra", "Germany (Xetra)", "financial_centre", "DE"},
        {"Germany.Eurex", "Germany (Eurex)", "financial_centre", "DE"},
        {"Germany.Euwax", "Germany (Euwax)", "financial_centre", "DE"},
        // Canada (Market enum)
        {"Canada.Settlement", "Canada (Settlement)", "public_holiday", "CA"},
        {"Canada.TSX", "Canada (Toronto Stock Exchange)", "financial_centre", "CA"},
        // South Korea (Market enum)
        {"SouthKorea.Settlement", "South Korea (Settlement)", "public_holiday", "KR"},
        {"SouthKorea.KRX", "South Korea (Korea Exchange)", "financial_centre", "KR"},
        // Indonesia (Market enum)
        {"Indonesia.BEJ", "Indonesia (Jakarta SE, legacy BEJ)", "financial_centre", "ID"},
        {"Indonesia.JSX", "Indonesia (Jakarta SE, legacy JSX)", "financial_centre", "ID"},
        {"Indonesia.IDX", "Indonesia (Indonesia Stock Exchange)", "financial_centre", "ID"},
        // Israel (Market enum)
        {"Israel.Settlement", "Israel (Settlement)", "public_holiday", "IL"},
        {"Israel.TASE", "Israel (Tel-Aviv Stock Exchange)", "financial_centre", "IL"},
    };

    std::vector<domain::calendar> result;
    result.reserve(std::size(rows));
    for (const auto& r : rows) {
        result.push_back({.tenant_id = tenant_id,
                          .code = r.code,
                          .name = r.name,
                          .calendar_type = r.type,
                          .country_code = r.country,
                          .modified_by = modified_by,
                          .change_reason_code = "system.initial_load",
                          .change_commentary = "QuantLib calendar reference data",
                          .recorded_at = now});
    }
    return result;
}

Custom repository methods

Qt: lock the whole form for a non-editable template

is_editable=false (every source'quantlib'= row, and any source'user'= row an admin has otherwise marked non-editable) must lock every field in the detail dialog, not just the fields already locked-after-create ( code, source, is_editable ) – a user must not be able to change a QuantLib-transcribed template's own name=/=calendar_type=/=country_code=/=base_calendar_code via the UI, full stop. setReadOnly(true) already does exactly this (it drives every non-locked-after-create field's enabled state, not only the locked-after-create ones), so this seam just calls it based on the row just loaded – create mode never reaches this seam (set{{Entity}} is only called when opening an existing row), so a brand-new is_editable=false-by-default calendar stays fully editable until saved.

setReadOnly(!calendar_.is_editable);

Qt: "Regenerate up to <year>" action

A toolbar action (:has_toolbar: true, above) that calls the refdata.v1.calendar_dates.regenerate NATS command (regenerate_calendar_dates_request, in ores.refdata.api/messaging/calendar_materialisation_protocol.hpp) for the calendar currently open in this dialog, extending its materialised calendar_dates up to a user-prompted end year. Available regardless of is_editable – regenerating derived calendar_dates rows is not the same as editing the template's own fields, so it isn't gated by the whole-form lock above. Disabled in create mode (nothing to regenerate for a row that doesn't exist on the server yet) – its initial state is set once in setupConnections() (below) while createMode_ still holds its constructor default, but the real caller-driven state only lands later via setCreateMode(), so that seam must also re-sync the action's enabled state, or it stays permanently disabled for every existing calendar opened through the normal view/edit flow (the one path this feature exists for).

if (regenerateAction_)
    regenerateAction_->setEnabled(!createMode);
#include "ores.refdata.api/messaging/calendar_materialisation_protocol.hpp"
#include <QDate>
#include <QInputDialog>
QAction* regenerateAction_{nullptr};
void onRegenerateClicked();
regenerateAction_ = toolBar_->addAction(
    IconUtils::createRecoloredIcon(Icon::ArrowSync, IconUtils::DefaultIconColor),
    tr("Regenerate"));
regenerateAction_->setToolTip(
    tr("Regenerate this calendar's holidays up to a chosen year"));
regenerateAction_->setEnabled(!createMode_);
connect(regenerateAction_, &QAction::triggered,
        this, &CalendarDetailDialog::onRegenerateClicked);

Qt: "Browse Holidays" action

A second toolbar action, alongside "Regenerate up to <year>" above, that opens a browser onto the calendar's materialised calendar_dates rows. The dialog itself doesn't know how to open that browser window (that's the plugin composition root's job, same as any other cross-entity navigation) – it only emits browseHolidaysRequested(code), which CalendarController relays upward as its own signal of the same name. Disabled in create mode for the same reason "Regenerate" is (nothing materialised yet for a row that doesn't exist on the server).

void browseHolidaysRequested(const QString& code);
QAction* browseHolidaysAction_{nullptr};
void onBrowseHolidaysClicked();
browseHolidaysAction_ = toolBar_->addAction(
    IconUtils::createRecoloredIcon(Icon::Table, IconUtils::DefaultIconColor),
    tr("Browse Holidays"));
browseHolidaysAction_->setToolTip(tr("Browse this calendar's materialised holiday dates"));
browseHolidaysAction_->setEnabled(!createMode_);
connect(browseHolidaysAction_, &QAction::triggered,
        this, &CalendarDetailDialog::onBrowseHolidaysClicked);
if (browseHolidaysAction_)
    browseHolidaysAction_->setEnabled(!createMode);
void CalendarDetailDialog::onBrowseHolidaysClicked() {
    emit browseHolidaysRequested(code());
}

CalendarController relays the dialog's signal as its own, of the same name – the plugin composition root connects CalendarController::browseHolidaysRequested to whatever opens the materialised-dates browser.

/**
 * @brief Relayed from CalendarDetailDialog's "Browse Holidays" toolbar
 * action; RefdataPlugin connects this to
 * CalendarDateController::openForParent(calendarCode).
 */
void browseHolidaysRequested(const QString& calendarCode);
connect(detailDialog, &CalendarDetailDialog::browseHolidaysRequested,
        this, &CalendarController::browseHolidaysRequested);
void CalendarDetailDialog::onRegenerateClicked() {
    if (!clientManager_ || !clientManager_->isConnected()) {
        MessageBoxHelper::warning(this, "Disconnected",
            "Cannot regenerate while disconnected from server.");
        return;
    }

    bool ok = false;
    const int currentYear = QDate::currentDate().year();
    const int endYear = QInputDialog::getInt(this, tr("Regenerate Holidays"),
        tr("Regenerate up to year:"), currentYear + 10,
        currentYear, currentYear + 100, 1, &ok);
    if (!ok) return;

    const std::string calendarCode = calendar_.code;
    QPointer<CalendarDetailDialog> self = this;

    struct RegenerateResult {
        bool success;
        std::string message;
        std::uint64_t rows_written;
    };

    auto task = [self, calendarCode, endYear]() -> RegenerateResult {
        if (!self || !self->clientManager_) {
            return {false, "Dialog closed", 0};
        }

        refdata::messaging::regenerate_calendar_dates_request request;
        request.calendar_code = calendarCode;
        request.end_year = endYear;
        auto response_result = self->clientManager_->
            process_authenticated_request(std::move(request));

        if (!response_result) {
            return {false, "Failed to communicate with server", 0};
        }

        return {response_result->success, response_result->message,
                response_result->rows_written};
    };

    auto* watcher = new QFutureWatcher<RegenerateResult>(self);
    connect(watcher, &QFutureWatcher<RegenerateResult>::finished, self, [self, watcher]() {
        auto result = watcher->result();
        watcher->deleteLater();
        if (!self) return;

        if (result.success) {
            BOOST_LOG_SEV(lg(), info) << "Regenerated " << result.rows_written
                                      << " calendar_dates rows";
            emit self->statusMessage(
                tr("Regenerated %1 holiday row(s)").arg(result.rows_written));
        } else {
            QString errorMsg = QString::fromStdString(result.message);
            emit self->errorMessage(errorMsg);
            MessageBoxHelper::critical(self, "Regenerate Failed", errorMsg);
        }
    });

    QFuture<RegenerateResult> future = QtConcurrent::run(task);
    watcher->setFuture(future);
}

See also

Emacs 29.3 (Org mode 9.6.15)