Skip to main content

36. Tournament Entity as Source of Truth

Status: Accepted Date: 2025-07-06

Context​

To effectively run and analyze experiments in the Mercury framework, we need a reliable way to associate every trading tournament with the specific experiment and variant it belongs to. Storing this metadata in separate tables, log files, or relying on configuration files at analysis time would be complex, error-prone, and would make querying for experiment results difficult.

Decision​

The Tournament database entity will be the single source of truth for all experiment-related metadata. We will add experimentId and variant fields directly to the Tournament table. When a new tournament is created as part of an experiment, these fields will be populated and persisted. All downstream processes, including data analysis, monitoring, and reporting, must rely on these fields as the authoritative source for experiment context.

Consequences​

Positive:

  • Single Source of Truth: Provides a clear, unambiguous, and permanent record of which experiment and variant each tournament belongs to.
  • Data Integrity: Co-locating the experiment metadata with the core tournament data ensures they can never go out of sync.
  • Simplified Analysis: Greatly simplifies data analysis, as we can easily group, filter, and aggregate tournament results by experimentId and variant with simple SQL queries.
  • Transactional Consistency: The experiment context is saved within the same transaction as the tournament itself, guaranteeing consistency.

Negative:

  • Schema Modification: Requires modifying the Tournament entity's database schema, which is a core table in the system.
  • Data Coupling: Tightly couples the Tournament entity to the concept of "experiments." This is an acceptable trade-off as running tournaments is the primary method of experimentation in this framework.

Mitigation:

  • Database Migrations: Use the existing MikroORM migration process to apply these schema changes in a safe, controlled, and reversible manner.
  • Clear Naming: Use clear and unambiguous field names (experimentId, variant) and data types in the database schema.
  • Non-nullable Fields: Make these fields non-nullable (with appropriate defaults for non-experimental tournaments) to ensure the data is always present.