Versioned Write [C#]

An easy step by step tutorial about how to write a Versioned Time Series in C# SDK.

Artesian gives you straightforward access to the data history to perform an analysis and produce a plan in the most compatible way.

Let’s see step-by-step how to proceed.

The goal

Write our data in a Versioned Time Series Market Data.

The reference data is fictitious, created exclusively for this case. With Artesian, it is possible to write any data attributable to a Time Series, making it suitable for saving your data production.

Let’s see how to proceed step by step.

Import of Artesian libraries and configuration

The first thing to do in order to use all the features of Artesian is to download the Artesian SDK from NuGet.

Once installed, and imported the necessary libraries (lines 1-4), we can configure Artesian by entering the essential link and API key (line 6).

To extract these two essential data, refer to the reference tutorial  “How to install Artesian C# SDK”.

After configuring Artesian and an eventual Policy, we can configure the Query Service (line 15) and proceed with the writing of data.

					using Artesian.SDK.Dto;
using Artesian.SDK.Service;
using Artesian.SDK.Factory;
using NodaTime;

ArtesianServiceConfig cfg = new ArtesianServiceConfig(new Uri("{tenantName}/", "{api-key}");

var qs = new MarketDataService(cfg);

Il MarketData Identifier e i dati necessari per la scrittura della Versioned TimeSeries

Once Artesian and the Market Data Service have been configured, we can define the Market Data Identifier; that is, we can give a name to our MarketData.

In this case, the Provider’s name will be “C#SDK”, while the name of the MarkeData will be “VersionedWrite”. The definition of these two fields is necessary for two reasons:

  1. The Provider and MarketData’s names represent the unique identifier of our curve on Artesian. The value combination is then translated into the MarketDataID.
  2. The Provider and MarketData’s names are necessary to find the data within the portal through the free text or category filter.

Once the market data and provider names are defined, we can decide on the essential characteristics of our Time Series, such as the type of granularity, the type of the Time Series, the Time Zone and any Aggregation Rule.

Artesian can support different granularities such as 10min, 15min, 30min, Hour, Day, Week, Month, Quarter, Season and Year.

When we decide the type of granularity of our market data: we must write it accordingly, indicating the values. For example, in the case of Granularity Day, the data will correspond to a specific day of a certain month in a particular year. In the case of Granularity Hour, the data will correspond to a specific hour (minute and second) of a certain day in a particular month and year.

The TimeZones: must be enhanced with the one corresponding to the data we are saving; this will help the system to apply the necessary conversions to the data in the case of extractions in a TimeZone different from the original.

The Aggregation Rule: in Artesian, the Aggregation Rule is the operation when data is extracted in a different granularity from the original one. You can choose whether to set it to “Undefined”, “SumAndDivide”, or “AverageAndReplicate”. In the example code, we report the Aggregation Rule SumAndDivide.

The Type of the Time Series: in this case is Versioned, but it could also be Actual, MarketAssessment, BidAsk or Auction. See the other tutorials.

					 var marketDataEntity = new MarketDataEntity.Input()
    ProviderName = "C#SDK",
    MarketDataName = "VersionedWrite",
    OriginalGranularity = Granularity.Day,
    OriginalTimezone = "CET",
    AggregationRule = AggregationRule.AverageAndReplicate,
    Type = MarketDataType.VersionedTimeSerie

var marketDataService = new MarketDataService(cfg);

var marketData = marketDataService.GetMarketDataReference(new MarketDataIdentifier(

Control and registration of the Market Data

First, set the MarketData base; you must check if this Time Series already exists. To do this, we need to insert the Provider’s name, the market data, and unique identifiers to see if there is a match in Artesian. The data already exists if there is a match and can not be overwritten. On the other hand, if there is no response, the data is saved on Artesian through the command “marketData.Register(marketDataEntity)“.

					var isRegistered = await marketData.IsRegistered();
await marketData.Register(marketDataEntity);

Writing the MarketData values

The last part of our code consists of the configuration of our write to Artesian.

The required parameters for this step are:

The MarketData identifier: that we defined at the beginning of our code

The reference TimeZone of the data we are writing: this must be “UTC” in the case of data with hourly or lower granularity (with adequate data conversion if necessary). It must correspond to the Original Timezone in the case of daily granularity data or higher. This data conversion in the case of hourly or lower granularity is necessary for Artesian to correctly manage the data sent (e.g. change of Winter/Summer time)

The Versioned rows: are an array of data dictionaries in which the “key” “value” pair is structured as follows:

  • “key the reference DateTime of the data
  • “value” the number we want to enter for that instant of time

Below there are examples of a code for writing daily or hourly data:

  • Daily data has values for June 18th and 19th
  • Hourly data has values for June 18th, at 9AM and 10AM

Artesian does not support writing values in two different granularities; these were done only as an example!

To conclude and proceed with writing our Versioned TimeSeries, we must define the Version, which typically corresponds to the timestamp at which the series was generated and the “downloadedAt“. Represented metadata type of information data when written in Artesian. The definition of the Version is essential as it will become a valuable parameter for the extraction and calculation of the MUV (Most Updated version).

Once the previous steps are complete, we can load the Versioned Time Series into the system using the command “Save“.

					var writeMarketData = marketData.EditVersioned(new LocalDateTime(2022, 6, 19, 00, 00));

OriginalGranularity = Granularity.Day
OriginalTimezone = "CET"
    writeMarketData.AddData(new LocalDate(2022, 6, 18), 40);
    writeMarketData.AddData(new LocalDate(2022, 6, 19), 45);
OriginalGranularity = Granularity.Hour
OriginalTimezone = "UTC"
    writeMarketData.AddData(new LocalDate(2022, 6, 18, 9, 0, 0), 42);
    writeMarketData.AddData(new LocalDate(2022, 6, 18, 10, 0, 0), 46);

await writeMarketData.Save(downloadedAt: SystemClock.Instance.getCurrentInstant);


Visualization of the new MarketData on the Artesian portal

Unless there are errors to report, nothing will appear in the terminal. However, returning to the Artesian portal, we can verify that our TimeSeries appears under the ProviderName category with the previously given name “C#SDK”.

It is sufficient to employ just once and then have it entirely reproducible and automated in our workflow.

Not only does it save you time, but it allows you to minimize human errors caused by repeated operations on substantial amounts of data or different Excel files.

An undeniable advantage that allows us to focus on data analysis instead of its management and optimization.