ores.refdata.calendar
Table of Contents
- Flags
- Columns
- SQL
- Validation function
- Insert trigger
- C++
- See also
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
- ores.refdata — component group overview.
- ores.refdata.calendar_type — the aux-type table classifying
calendar_type. - Model calendars as proper ORE Studio reference data — parent story.
- Calendars, Holidays and Events — the knowledge cluster grounding this entity's design.