Data Model: UZSE Backtest MongoDB Collections Overview

The UZSE Backtest App uses two MongoDB collections inside a single backtest database. The first collection — trade-results — holds every raw executed trade scraped from the Uzbekistan Stock Exchange. The second — candle-items — holds pre-computed OHLCV candles in 11 timeframes derived from those trades. Data always flows in one direction: from UZSE’s HTML pages, through the trade-results store, into candle-items, and finally into the backtest-kit editor for Pine Script analysis.

Database

Setting	Value
Database name	`backtest`
Connection string env var	`MONGO_URI`
Collections	`trade-results`, `candle-items`

See MongoDB Infrastructure for connection setup and recommended Atlas / local configuration.

Collection Summary

Collection	Model	Purpose	Key Index
`trade-results`	`TradeModel`	Raw executed trades scraped from UZSE	`{ hash }` unique, `{ symbol, time }` compound
`candle-items`	`CandleModel`	OHLCV candles across 11 timeframes	`{ symbol, interval, timestamp }` unique

Data Flow

Scrape UZSE HTML trade pages → trade-results

The download-trades.ts script fetches paginated HTML from the UZSE trade history endpoint for a given ISIN and date range. Each executed trade row is parsed, normalised (including the Russian-language date string), and written to disk as a JSON file.

npx tsx scripts/download-trades.ts UZ7011340005 01.03.2026 31.03.2026

The import-trades.ts script then reads those files and performs a bulk upsert into trade-results. Each document is fingerprinted with a SHA1 hash (over symbol|time|tradePrice|quantity|volume|pageIndex|rowIndex|urlKey). The { hash } unique index silently skips any trade that already exists in the database.

npx tsx scripts/import-trades.ts

Aggregate + gap-fill → candle-items (11 timeframes)

The build-candles.ts script reads trade-results day by day for a given ISIN, builds a gapless 1-minute series (filling intraday gaps and non-trading days with synthetic flat candles), then aggregates all 11 timeframes in a single forward pass per day.

npx tsx scripts/build-candles.ts HMKB UZ7011340005

The script accepts both the display symbol (HMKB) and the ISIN (UZ7011340005) because the two collections use different symbol namespaces: trade-results stores the ISIN, while candle-items stores the human-readable ticker. All 11 timeframes for all days are written in bulk with insertMany({ ordered: false }) — the { symbol, interval, timestamp } unique index ensures duplicates are skipped rather than errored.

Query candle-items → backtest-kit editor

The editor.module.ts registers a mongo-exchange adapter with backtest-kit using addExchangeSchema. When a Pine Script strategy requests candle data, the adapter queries candle-items by (symbol, interval, timestamp >= since), sorted ascending with a limit:

const candles = await CandleModel.find(
  { symbol, interval, timestamp: { $gte: since.getTime() } },
  { timestamp: 1, open: 1, high: 1, low: 1, close: 1, volume: 1, _id: 0 }
)
  .sort({ timestamp: 1 })
  .limit(limit)
  .lean();

The result is a continuous OHLCV array with no gaps, ready for Pine Script indicator evaluation.

Symbol Namespace Mapping

The two collections use different identifiers for the same security:

Collection	Symbol field	Example value	Meaning
`trade-results`	`symbol` (ISIN)	`UZ7011340005`	International Securities Identification Number
`candle-items`	`symbol` (display name)	`HMKB`	Human-readable ticker used by the editor

The build-candles.ts script is the bridge between these namespaces. It queries trade-results using the ISIN and writes to candle-items using the display symbol. Both arguments must be supplied on the command line:

# npx tsx scripts/build-candles.ts [displaySymbol] [isin]
npx tsx scripts/build-candles.ts HMKB UZ7011340005

Idempotency Guarantees

Both collections are designed for safe re-ingestion at any stage of the pipeline:

trade-results: SHA1 hash deduplication

Every trade document carries a hash field (SHA1 over trade content + scraping context). The { hash: 1 } unique index means re-importing the same UZSE export file never creates duplicates — already-seen rows are silently skipped.

candle-items: Composite unique index

The { symbol: 1, interval: 1, timestamp: 1 } unique index means re-running build-candles.ts for any symbol and date range already in the database will skip all existing candles rather than failing or creating duplicates.

Example MongoDB Queries

The following queries can be run directly in mongosh or MongoDB Compass against the backtest database.

Show Query candle-items

// Get the 100 most recent 1h candles for HMKB
db['candle-items'].find({
  symbol: 'HMKB',
  interval: '1h',
  timestamp: { $gte: 1704067200000 }
}).sort({ timestamp: 1 }).limit(100)

// Count total candles stored per timeframe for HMKB
db['candle-items'].aggregate([
  { $match: { symbol: 'HMKB' } },
  { $group: { _id: '$interval', count: { $sum: 1 } } },
  { $sort: { _id: 1 } }
])

// Find the earliest and latest candle timestamps for a symbol
db['candle-items'].find(
  { symbol: 'HMKB', interval: '1d' },
  { timestamp: 1, open: 1, close: 1, _id: 0 }
).sort({ timestamp: 1 }).limit(1)

Show Query trade-results

// Find all trades for a specific ISIN on a single date
db['trade-results'].find({
  symbol: 'UZ7011340005',
  time: {
    $gte: new Date('2024-01-01'),
    $lt:  new Date('2024-01-02')
  }
}).sort({ time: 1 })

// List all distinct ISINs stored in trade-results
db['trade-results'].distinct('symbol')

// Count trades per day for a given ISIN (useful for gap checking)
db['trade-results'].aggregate([
  { $match: { symbol: 'UZ7011340005' } },
  {
    $group: {
      _id: {
        $dateToString: { format: '%Y-%m-%d', date: '$time' }
      },
      tradeCount: { $sum: 1 }
    }
  },
  { $sort: { _id: 1 } }
])

Bulk Import via mongoimport

If you have a pre-existing JSON dump (e.g. from a colleague or a previous mongoexport), you can seed both collections directly without running the full scraping pipeline:

mongoimport \
  --db backtest \
  --collection trade-results \
  --file backtest.trade-results.json \
  --jsonArray

mongoimport \
  --db backtest \
  --collection candle-items \
  --file backtest.candle-items.json \
  --jsonArray

mongoimport does not enforce unique indexes during import unless you use --mode upsert. Without it, importing into a non-empty collection may produce duplicate-key errors on the hash (for trade-results) or { symbol, interval, timestamp } (for candle-items) indexes. Add --mode upsert or clear the collection first if you are merging into existing data.

Candle Schema

Full field-level reference for the candle-items collection.

Trade Schema

Full field-level reference for the trade-results collection.

Timeframes

All 11 OHLCV timeframes and the gap-fill aggregation algorithm.

MongoDB Infrastructure

Connection configuration, Atlas setup, and recommended index management.

Build Candles

Step-by-step guide to running build-candles.ts.

Exchange Module

How getCandles() in editor.module.ts bridges MongoDB and backtest-kit.

Get Started

Data Pipeline

Backtesting & Analysis

Infrastructure

Reference

Data Model: UZSE Backtest MongoDB Collections Overview

Database

Collection Summary

Data Flow

Symbol Namespace Mapping

Idempotency Guarantees

trade-results: SHA1 hash deduplication

candle-items: Composite unique index

Example MongoDB Queries

Bulk Import via mongoimport

Candle Schema

Trade Schema

Timeframes

MongoDB Infrastructure

Build Candles

Exchange Module

Build docs developers (and LLMs) love

Get Started

Data Pipeline

Backtesting & Analysis

Infrastructure

Reference

Documentation Index

​Database

​Collection Summary

​Data Flow

​Symbol Namespace Mapping

​Idempotency Guarantees

trade-results: SHA1 hash deduplication

candle-items: Composite unique index

​Example MongoDB Queries

​Bulk Import via mongoimport

​Related Pages

Candle Schema

Trade Schema

Timeframes

MongoDB Infrastructure

Build Candles

Exchange Module

Build docs developers (and LLMs) love

Database

Collection Summary

Data Flow

Symbol Namespace Mapping

Idempotency Guarantees

Example MongoDB Queries

Bulk Import via mongoimport

Related Pages