Source: https://databento.com/docs/examples/symbology/parent-symbology


# Parent symbology

In this example we will use the [Historical client](https://databento.com/docs/api-historical/client.md) to retrieve a large number of instrument definitions.
We will do this using the [smart symbology](https://databento.com/docs/conventions/symbology.md) feature to request all active E-mini S&P 500 futures contracts on a specified date.

## Definition Schema

This example uses the [definition schema](https://databento.com/docs/schemas/instrument-definitions.md), which contains instrument definitions and properties such as expiration dates.

## Example

```cpp
#include <algorithm>
#include <databento/datetime.hpp>
#include <databento/historical.hpp>
#include <databento/symbol_map.hpp>
#include <iomanip>
#include <iostream>
#include <string>
#include <string_view>
#include <tuple>
#include <vector>

namespace db = databento;

int main() {
  db::TsSymbolMap symbol_mappings;
  auto extract_symbol_mappings = [&symbol_mappings](db::Metadata&& metadata) {
    symbol_mappings = metadata.CreateSymbolMap();
  };

  std::vector<db::InstrumentDefMsg> definitions;
  auto print_definitions = [&definitions](const db::Record& record) {
    definitions.emplace_back(record.Get<db::InstrumentDefMsg>());
    return db::KeepGoing::Continue;
  };

  auto client = db::Historical::Builder().SetKey("$YOUR_API_KEY").Build();
  client.TimeseriesGetRange(
      "GLBX.MDP3", db::DateTimeRange<std::string>{"2022-08-26"}, {"ES.FUT"},
      db::Schema::Definition, db::SType::Parent, db::SType::InstrumentId, {},
      extract_symbol_mappings, print_definitions);

  std::sort(
      definitions.begin(), definitions.end(),
      [](const auto& lhs, const auto& rhs) {
        return std::tuple{lhs.expiration, std::string_view{lhs.RawSymbol()}} <
               std::tuple{rhs.expiration, std::string_view{rhs.RawSymbol()}};
      });
  for (const auto& definition : definitions) {
    std::cout << definition.hd.instrument_id << '\t' << std::setw(9)
              << symbol_mappings.At(definition) << '\t'
              << db::ToIso8601(definition.expiration) << '\n';
  }
  return 0;
}
```
## Result

```plaintext
97042	     ESU2	2022-09-16T13:30:00.000000000Z
431108	ESU2-ESH3	2022-09-16T13:30:00.000000000Z
26998	ESU2-ESM3	2022-09-16T13:30:00.000000000Z
16445	ESU2-ESU3	2022-09-16T13:30:00.000000000Z
431796	ESU2-ESZ2	2022-09-16T13:30:00.000000000Z
206323	     ESZ2	2022-12-16T14:30:00.000000000Z
344396	ESZ2-ESH3	2022-12-16T14:30:00.000000000Z
19355	ESZ2-ESM3	2022-12-16T14:30:00.000000000Z
36396	ESZ2-ESU3	2022-12-16T14:30:00.000000000Z
4931	ESZ2-ESZ3	2022-12-16T14:30:00.000000000Z
206299	     ESH3	2023-03-17T13:30:00.000000000Z
431569	ESH3-ESM3	2023-03-17T13:30:00.000000000Z
20604	ESH3-ESU3	2023-03-17T13:30:00.000000000Z
16567	ESH3-ESZ3	2023-03-17T13:30:00.000000000Z
95414	     ESM3	2023-06-16T13:30:00.000000000Z
2018	ESM3-ESH4	2023-06-16T13:30:00.000000000Z
28177	ESM3-ESU3	2023-06-16T13:30:00.000000000Z
37976	ESM3-ESZ3	2023-06-16T13:30:00.000000000Z
3445	     ESU3	2023-09-15T13:30:00.000000000Z
18909	ESU3-ESH4	2023-09-15T13:30:00.000000000Z
35947	ESU3-ESZ3	2023-09-15T13:30:00.000000000Z
314863	     ESZ3	2023-12-15T14:30:00.000000000Z
33040	ESZ3-ESH4	2023-12-15T14:30:00.000000000Z
2826	ESZ3-ESM4	2023-12-15T14:30:00.000000000Z
17077	     ESH4	2024-03-15T13:30:00.000000000Z
17684	ESH4-ESM4	2024-03-15T13:30:00.000000000Z
5602	     ESM4	2024-06-21T13:30:00.000000000Z
4155	ESM4-ESU4	2024-06-21T13:30:00.000000000Z
118	     ESU4	2024-09-20T13:30:00.000000000Z
183748	     ESZ4	2024-12-20T14:30:00.000000000Z
294973	     ESZ5	2025-12-19T14:30:00.000000000Z
10252	     ESZ6	2026-12-18T14:30:00.000000000Z
```


# Parent symbology

## Overview

In this example we will use the [Historical client](https://databento.com/docs/api-historical/client.md) to retrieve a large number of instrument definitions using [parent symbology](https://databento.com/docs/conventions/symbology.md#parent).
When requesting data with a parent symbol (`ES.FUT`), all contracts that trade under the parent name will be returned.
This includes outright futures (`ESM5`), as well as calendar spreads (`ESM5-ESU5`).

> **See also**
>
> If you are only interested in the front month contract for a futures product, see our [continuous symbology](https://databento.com/docs/examples/symbology/continuous.md) example.

We'll use the [definition schema](https://databento.com/docs/schemas/instrument-definitions.md), which contains instrument definitions and properties such as `expiration`, `raw_symbol`, and `instrument_class`.
`instrument_class` will indicate the type of instrument, such as future or future spread.
A full list of variants can be found in the [instrument class documentation](https://databento.com/docs/schemas/instrument-definitions.md#instrument-class).

## Example

```python
import databento as db

# Create a historical client
client = db.Historical("$YOUR_API_KEY")

# Request definition data
data = client.timeseries.get_range(
    dataset="GLBX.MDP3",
    start="2025-05-19",
    symbols="ES.FUT",
    stype_in="parent",
    schema="definition",
)

# Convert to DataFrame
df = data.to_df()

# Filter out spreads and sort by expiration
df = df[df["instrument_class"] == db.InstrumentClass.FUTURE]
df = df.set_index("expiration").sort_index()

print(df[["instrument_id", "raw_symbol"]])
```
## Result

```plaintext
                           instrument_id raw_symbol
expiration
2025-06-20 13:30:00+00:00           4916       ESM5
2025-09-19 13:30:00+00:00          14160       ESU5
2025-12-19 14:30:00+00:00         294973       ESZ5
2026-03-20 13:30:00+00:00       42140878       ESH6
2026-06-18 13:30:00+00:00       42140864       ESM6
...
2026-09-18 13:30:00+00:00       42140870       ESU6
2026-12-18 14:30:00+00:00          10252       ESZ6
2027-03-19 13:30:00+00:00       42140860       ESH7
2027-06-17 13:30:00+00:00       42140856       ESM7
2027-09-17 13:30:00+00:00       42140874       ESU7
2027-12-17 14:30:00+00:00          17740       ESZ7
2028-03-17 13:30:00+00:00       42140879       ESH8
```


# Parent symbology

In this example we will use the [Historical client](https://databento.com/docs/api-historical/client.md) to retrieve a large number of instrument definitions.
We will do this using the [smart symbology](https://databento.com/docs/conventions/symbology.md) feature to request all active E-mini S&P 500 futures contracts on a specified date.

## Definition Schema

This example uses the [definition schema](https://databento.com/docs/schemas/whats-a-schema.md), which contains instrument definitions and properties such as expiration dates.

## Example
```rust
use databento::{
    HistoricalClient,
    dbn::{InstrumentDefMsg, SType, Schema, TsSymbolMap, decode::DbnMetadata},
    historical::timeseries::GetRangeParams,
};
use time::macros::date;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut client = HistoricalClient::builder().key_from_env()?.build()?;
    // First, we request the definition data
    let mut decoder = client
        .timeseries()
        .get_range(
            &GetRangeParams::builder()
                .dataset("GLBX.MDP3")
                .date_time_range(date!(2022 - 08 - 26))
                .symbols("ES.FUT")
                .stype_in(SType::Parent)
                .schema(Schema::Definition)
                .build(),
        )
        .await?;
    let symbol_mappings = decoder.metadata().symbol_map()?;
    // Then, we store all the definitions in a Vec
    let definitions = decoder.decode_records::<InstrumentDefMsg>().await?;
    // Finally, we sort by contract expiration and print the results
    print_by_expiration(definitions, &symbol_mappings);
    Ok(())
}

fn print_by_expiration(mut definitions: Vec<InstrumentDefMsg>, symbol_mappings: &TsSymbolMap) {
    definitions.sort_by_key(|def| (def.expiration, def.raw_symbol().unwrap().to_owned()));
    println!("expiration               instrument_id raw_symbol");
    for def in definitions {
        let expiration = def.expiration().unwrap();
        println!(
            "{expiration} {:6} {:9}",
            def.hd.instrument_id,
            symbol_mappings[&(def.ts_recv().unwrap().date(), def.hd.instrument_id)],
        );
    }
}
```
## Result
```plaintext
expiration               instrument_id raw_symbol
2022-09-16 13:30:00.0 +00:00:00  97042 ESU2
2022-09-16 13:30:00.0 +00:00:00 431108 ESU2-ESH3
2022-09-16 13:30:00.0 +00:00:00  26998 ESU2-ESM3
2022-09-16 13:30:00.0 +00:00:00  16445 ESU2-ESU3
2022-09-16 13:30:00.0 +00:00:00 431796 ESU2-ESZ2
2022-12-16 14:30:00.0 +00:00:00 206323 ESZ2
2022-12-16 14:30:00.0 +00:00:00 344396 ESZ2-ESH3
2022-12-16 14:30:00.0 +00:00:00  19355 ESZ2-ESM3
2022-12-16 14:30:00.0 +00:00:00  36396 ESZ2-ESU3
2022-12-16 14:30:00.0 +00:00:00   4931 ESZ2-ESZ3
2023-03-17 13:30:00.0 +00:00:00 206299 ESH3
2023-03-17 13:30:00.0 +00:00:00 431569 ESH3-ESM3
2023-03-17 13:30:00.0 +00:00:00  20604 ESH3-ESU3
2023-03-17 13:30:00.0 +00:00:00  16567 ESH3-ESZ3
2023-06-16 13:30:00.0 +00:00:00  95414 ESM3
2023-06-16 13:30:00.0 +00:00:00   2018 ESM3-ESH4
2023-06-16 13:30:00.0 +00:00:00  28177 ESM3-ESU3
2023-06-16 13:30:00.0 +00:00:00  37976 ESM3-ESZ3
2023-09-15 13:30:00.0 +00:00:00   3445 ESU3
2023-09-15 13:30:00.0 +00:00:00  18909 ESU3-ESH4
2023-09-15 13:30:00.0 +00:00:00  35947 ESU3-ESZ3
2023-12-15 14:30:00.0 +00:00:00 314863 ESZ3
2023-12-15 14:30:00.0 +00:00:00  33040 ESZ3-ESH4
2023-12-15 14:30:00.0 +00:00:00   2826 ESZ3-ESM4
2024-03-15 13:30:00.0 +00:00:00  17077 ESH4
2024-03-15 13:30:00.0 +00:00:00  17684 ESH4-ESM4
2024-06-21 13:30:00.0 +00:00:00   5602 ESM4
2024-06-21 13:30:00.0 +00:00:00   4155 ESM4-ESU4
2024-09-20 13:30:00.0 +00:00:00    118 ESU4
2024-12-20 14:30:00.0 +00:00:00 183748 ESZ4
2025-12-19 14:30:00.0 +00:00:00 294973 ESZ5
2026-12-18 14:30:00.0 +00:00:00  10252 ESZ6
```