> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data retrieval

The Atoti Market Data Library can retrieve the following:

* a single market data corresponding to a key defining the market data
* all the market data corresponding to a curve, a surface, or a cube

## Market data retrieval interfaces

Interfaces for market data retrieval are defined in the packages `com.activeviam.marketdata.lib.retrievers.intf` and `com.activeviam.marketdata.lib.retrievers.contextual.intf`.

| Interface | Description | Methods |
| - | - | - |
| `IMarketDataRetriever<C, V>` | Interface for a market data retriever that retrieves a single market data value based on the coordinates passed in. | `getMarketData(coordinates)` |
| `IDefaultMarketDataRetriever` | Interface for a market data retriever that retrieves a single market data `Double` value based on the coordinates passed in as an `Object[]`. | None, aliasing `IMarketDataRetriever<Object[], Double>` |
| `ISpotMarketDataRetriever` | Interface for a market data retriever for spot data, extending `IDefaultMarketDataRetriever`. | `getMarketData(LocalDate asOfDate, String marketDataSet, String instrumentId)` |
| `ICurveMarketDataRetriever` | Interface for a market data retriever for curve (1-axis) market data, extending `IDefaultMarketDataRetriever`. | `getCurve(asOfDate, marketDataSet, curveId)` |
| `ISurfaceMarketDataRetriever` | Interface for a market data retriever for surface (2-axis) market data, extending `IDefaultMarketDataRetriever`. | `getSurface(asOfDate, marketDataSet, surfaceId)` |
| `ICubeMarketDataRetriever` | Interface for a market data retriever for cube (3-axis) market data, extending `IDefaultMarketDataRetriever`. | `getCube(asOfDate, marketDataSet, cubeId)` |
| `IFxMarketDataRetriever` | Interface for a market data retriever for FX rates, extending `IDefaultMarketDataRetriever`. | `getMarketData(asOfDate, marketDataSet, baseCcy, counterCcy)` |
| `IContextualMarketDataRetriever<C, V>` | Interface for a market data retriever for single market data values based on the coordinates passed in. The retrieval may be modified by a provided `MarketDataRetrieverContext`, and a name can be associated with the retriever. | `getName()`, `getMarketData(coordinates, context)` |
| `IDefaultContextualMarketDataRetriever` | Interface for a market data retriever for single market data `Double` values based on the coordinates passed in as an `Object[]`. The retrieval may be modified by a provided `MarketDataRetrieverContext`, and a name can be associated with the retriever. | None, aliasing `IContextualMarketDataRetriever<Object[], Double>` |

## Market data retrieval implementations

Implementations for market data retrieval are defined in the `com.activeviam.marketdata.lib.retrievers.impl` and `com.activeviam.marketdata.lib.retrievers.contextual.impl` packages. All retrievers provide Lombok builders.

| Class | Description | Details |
| - | - | - |
| `SingleTableMarketDataRetriever` | Implements `IDefaultMarketDataRetriever`. | Returns a single market data `Double` value. |
| `SpotTableMarketDataRetriever` | Extends `SingleTableMarketDataRetriever`, implements `ISpotMarketDataRetriever`. | Returns spot market data. |
| `FxRateTableMarketDataRetriever` | Extends `SingleTableMarketDataRetriever`, implements `IFxMarketDataRetriever`. | Returns FX rates and available currencies. |
| `CurveTableMarketDataRetriever` | Extends `SingleTableMarketDataRetriever`, implements `ICurveMarketDataRetriever`. | Returns single market data values from a curve, or whole curves. |
| `SurfaceTableMarketDataRetriever` | Extends `SingleTableMarketDataRetriever`, implements `ISurfaceMarketDataRetriever`. | Returns single market data values from a surface, or whole surfaces. A whole surface is returned only if it has a value for every pair of its tenors and moneyness values. Otherwise, no surface is returned and a warning lists the missing points. |
| `CubeTableMarketDataRetriever` | Extends `SingleTableMarketDataRetriever`, implements `ICubeMarketDataRetriever`. | Returns single market data values from a cube. |
| `AContextualMarketDataRetriever<C, V>` | Implements `IContextualMarketDataRetriever<C, V>`. | Returns market data with caching, after translating the requested coordinates using a coordinates translator. Provides abstract methods for creating a cache key and a non-contextual retrieval of market data, to be overridden by any extension. |
| `ADefaultContextualMarketDataRetriever` | Extends `AContextualMarketDataRetriever<Object[], Double>`, implements `IDefaultContextualMarketDataRetriever`. | Creates a cache key based on the translated coordinates, the retriever name and the retrieval operation id. |
| `SingleContextualMarketDataRetriever<T extends IDefaultMarketDataRetriever>` | Extends `ADefaultContextualMarketDataRetriever`. | Returns market data values using the underlying table retriever. |
| `FxContextualMarketDataRetriever` | Extends `SingleContextualMarketDataRetriever<IFxMarketDataRetriever>`. | Returns FX rates with support for inverse rates and pivot currencies. Logs a warning when it finds no rate, directly or through the pivot currency. |
| `InterpolatingCurveContextualMarketDataRetriever` | Extends `SingleContextualMarketDataRetriever<ICurveMarketDataRetriever<String>>`. | Returns single market data values from a curve, interpolating values from the whole curve when necessary. |
| `InterpolatingSurfaceContextualMarketDataRetriever` | Extends `SingleContextualMarketDataRetriever<ISurfaceMarketDataRetriever<String, String>>`. | Returns single market data values from a surface, interpolating values from the whole surface when necessary. |

## Market data retrieval containers

All contextual market data retrievers are built using a name, table retriever, and coordinate translator. To facilitate their instantiation, we provide containers for the components and a service for their collection.

| Class | Description |
| - | - |
| `IMarketDataRetrievalContainer<T>` | An interface for a container for a retriever of type `T`, with an associated `IMarketDataCoordinateTranslator<Object[]>` and a name. |
| `MarketDataRetrievalContainer<T>` | An implementation of `IMarketDataRetrievalContainer<T>` as a `record`. |
| `IMarketDataRetrievalContainerService<T>` | An interface for a service allowing the selection of `IMarketDataRetrievalContainer<T>` by name. |
| `MarketDataRetrievalContainerService<T>` | An implementation of `IMarketDataRetrievalContainerService<T>` collecting `IMarketDataRetrievalContainer<T>` objects. |
| `MarketDataRetrievalContainerServiceConfig` | Spring `@Configuration` class publishing a `MarketDataRetrievalContainerService<T>` as an `IMarketDataRetrievalContainerService<T>` bean. |

## MarketDataDateShift

The `MarketDataDateShift` defined in the package `com.activeviam.marketdata.lib.dates.impl` is an enum with the following values:

| Value | Details |
| - | - |
| `CURRENT_DAY` | Retrieves the current day with regard to a base date. |
| `NEXT_DAY` | Retrieves the next day with regard to a base date. |
| `PREVIOUS_DAY` | Retrieves the previous day with regard to a base date. |

## Retrieval context

The market data retrieval context is defined in the class `MarketDataRetrieverContext` in the package `com.activeviam.marketdata.lib.retrievers.intf`.
It is used to define:

* the name of the retrieval
* the query cache that is used
* the `MarketDataDateShift` (see above).

## Date retrieval interfaces

Interfaces for date retrieval are defined in the package `com.activeviam.marketdata.lib.dates.intf`.

| Interface | Description | Details |
| - | - | - |
| `IDateRetriever` | Interface to retrieve all the asOfDates present in market data inputs. | Used for the retrieval of the previous or the next day with regards to a given asOfDate. |
| `IContextualDateRetriever` | Interface for the retrieval of the current, previous or the next day with regard to a given asOfDate. | Takes an asOfDate and a `MarketDataRetrieverContext` object as inputs. |

## Date retrieval implementations

Implementations for date retrieval are defined in the package `com.activeviam.marketdata.lib.dates.impl`.

| Interface | Description | Details |
| - | - | - |
| `TableDateRetriever` | Implementation of `IDateRetriever`. | Returns all the dates present in a given table in an `IDatabase` object. |
| `DateShiftingDateRetriever` | Implementation of `IContextualDateRetriever`. | Returns a shifted date (i.e. the current, next or previous date) with an asOfDate and a `MarketDataRetrieverContext` object as inputs. |

## Coordinate Translator Interface

The interface for translating market data coordinates used to retrieve market data is defined in the package
`com.activeviam.marketdata.lib.translators.intf`. This interface modifies the coordinates based on a given `MarketDataRetrieverContext` (see [Retrieval context](#retrieval-context)).

The translation is meant to modify the asOfDate passed in the coordinates in order to return a key containing the previous or next day with regard to the original asOfDate.

| Interface | Description | Details |
| - | - | - |
| `IMarketDataCoordinateTranslator` | Interface for market data coordinates translators | Uses `IContextualDateRetriever` to translate a key based on a `MarketDataRetrieverContext`. |

## Key Translator Implementation

The implementation used to translate a coordinates used to retrieve market data is defined in the package `com.activeviam.marketdata.lib.translators.impl`.

| Interface | Description | Details |
| - | - | - |
| `DateShiftTranslator` | Implementation of `IMarketDataCoordinateTranslator`. | Shifts the provided date by using an underlying `IContextualDateRetriever`. |

## Spring configuration classes

To configure the retrieval from a market data store, we now create:

* The store, as a @Bean extending `AMarketDataStore<T>`, used by the `IDatastoreConfigurator`
* A `TableDateRetriever` on the configured store
* A `DateShiftingDateRetriever` wrapping the `TableDateRetriever` with caching and date shifting
* An `IMarketDataCoordinateTranslator<List<Object>>`, usually an implementation of `DateShiftingTranslator`, using the `DateShiftingDateRetriever`, to shift the market data retrieval coordinates to the correct date
* A retriever of the appropriate type (e.g. a `CubeTableMarketDataRetriever` as an `ICubeMarketDataRetriever<String, String, String>`)
* A container wrapping the retriever and translator, with a name.

In cases where the components held in a container are sufficient for instantiating a contextual retriever, the `IMarketDataRetrievalContainerService` should be used (e.g. for retrieving a point on a curve without interpolation, the `SingleMarketDataPostProcessor` can be instantiated with the `CURVE_MARKET_DATA_RETRIEVER` property).

Several Spring configuration classes are provided in the `com.activeviam.marketdata.config.retrievers` package of the `market-data-config` module, providing Datastore Helper (DaSH) stores and retrievers as Spring beans. When you add the `market-data-spring-boot-starter` as a dependency in your project, the `CubeMarketDataRetrievalConfig`, `CurveMarketDataRetrievalConfig`, `FxRateMarketDataRetrievalConfig`, `SpotMarketDataRetrievalConfig`, and `SurfaceMarketDataRetrievalConfig` classes will be auto-configured.

| Class | Details |
| - | - |
| `SpotMarketDataRetrievalConfig` | Publishes a spot store bean along with associated date retrievers and translators. |
| `FxRateMarketDataRetrievalConfig` | Publishes an FX rate store bean along with associated date retrievers and translators. |
| `CurveMarketDataRetrievalConfig` | Publishes a curve store bean along with associated date retrievers and translators. |
| `SurfaceMarketDataRetrievalConfig` | Publishes a surface store bean along with associated date retrievers and translators. |
| `CubeMarketDataRetrievalConfig` | Publishes a cube store bean along with associated date retrievers and translators. |
| `MarketDataRetrievalContainerServiceConfig` | Publishes an `IMarketDataRetrievalContainerService<T>` collecting all implementations of `IMarketDataRetrievalContainer<T>` published by the individual configuration classes. |
| `AllMarketDataRetrievalConfig` | Imports all other `*MarketDataRetrievalConfig` and `MarketDataRetrievalContainerServiceConfig` classes. |
