Class ResolveParams
- Namespace
- DatabentoDotNet.Historical
- Assembly
- DatabentoDotNet.Historical.dll
The parameters for symbology.resolve: which symbols to resolve, from which symbology to
which, over which UTC dates.
public sealed record ResolveParams : IEquatable<ResolveParams>- Inheritance
-
ResolveParams
- Implements
- Inherited Members
Remarks
Port of upstream's ResolveParams (symbology.rs:60-81). Its bon::Builder
with two #[builder(default = ...)] attributes becomes required init
properties for the two fields with no sensible default and plain initialisers for the two with
one — PORTING.md's "type-state builders → required init properties".
The two conversions are the reason this type is worth more than its five properties.
FromMetadata(Metadata) exists because a historical ALL_SYMBOLS request comes back
with no mappings of its own: the stream names every instrument by id and nothing in it
says what those ids were called. Resolving afterwards from the metadata the stream itself
carries is the only way to name what arrived, and it is a real workflow rather than a
convenience. FromQuery(MetadataQueryParams, SType) does the same for a request you are about to send.
Properties
Dataset
The dataset code, for example GLBX.MDP3.
public required string Dataset { get; init; }Property Value
DateRange
The UTC date range to resolve over: inclusive Start, exclusive End, exactly as this type's usual contract reads — and exactly as the endpoint reads it.
public required DateRange DateRange { get; init; }Property Value
Remarks
That the two agree is a probed fact, not an assumption inherited from the type. #45
found metadata.get_dataset_condition reading end_date as inclusive
while its neighbour metadata.list_datasets read it as exclusive, and closed with the
rule that each new endpoint gets asked rather than assumed. So this one was asked, before
ToFormParameters() was written: 2024-01-02 .. 2024-01-03 for ESH4
on GLBX.MDP3 returns a single interval covering that one day, and
2024-01-02 .. 2024-01-05 returns the end sent, verbatim.
The decisive answer came from the third probe, where the server states the contract itself:
start_date == end_date is rejected with HTTP 422
data_date_range_start_on_or_after_end — "start_date 2024-01-02 cannot be on or
after end_date 2024-01-02". An endpoint reading end_date as inclusive has to
accept that, because it is how such an endpoint spells a single day;
get_dataset_condition does accept it. This one refuses it. Hence
ToExclusiveEndDateParameters(DateRange), and hence
DateRange.OnDay(d) resolving d alone rather than d and the day after.
A DateRange and not a DateTimeRange, because symbology resolves per whole UTC day and there is nothing below a day for an intraday bound to mean. FromQuery(MetadataQueryParams, SType) and FromMetadata(Metadata), whose sources both carry nanosecond bounds, narrow through ToDateRange(), which rounds a partial end day up so the resolution never covers less than the query did.
StypeIn
The symbology Symbols is expressed in. Defaults to
RawSymbol (symbology.rs:69), and is pushed onto the form
unconditionally rather than omitted when unchanged, as upstream pushes it
(symbology.rs:32).
public SType StypeIn { get; init; }Property Value
StypeOut
The symbology to resolve to. Defaults to InstrumentId, which
with the StypeIn default makes the unconfigured request the common one:
ESM2 → 3403.
public SType StypeOut { get; init; }Property Value
Remarks
Not every pairing with StypeIn is valid, and the invalid ones are rejected by the API rather than here — the supported set is documented per dataset and moves without a release of this library, so a client-side table would go stale silently. See the symbology reference.
Symbols
The symbols to resolve, in StypeIn's symbology.
public required Symbols Symbols { get; init; }Property Value
Methods
FromMetadata(Metadata)
Builds the parameters that resolve the symbols a decoded stream was requested with — the
ALL_SYMBOLS workflow this type's remarks describe.
public static ResolveParams FromMetadata(Metadata metadata)Parameters
metadataMetadataThe decoded stream metadata.
Returns
- ResolveParams
Parameters resolving
metadata's symbols over its own range.
Remarks
Port of upstream's TryFrom<Metadata> (symbology.rs:85-107). Paired with
TryFromMetadata(Metadata, out ResolveParams?) exactly as ToInstant(ulong) is paired with
TryToInstant(ulong, out Instant): this one names the missing field in its message, which
is what a caller who expected the conversion to work needs; the other reports the same
three absences as false, which is what a caller holding metadata that may
legitimately lack them needs.
Exceptions
- ArgumentNullException
metadatais null.- ArgumentException
metadatahas no StypeIn, no End, or no Symbols — the three absences described on TryFromMetadata(Metadata, out ResolveParams?). The message names which. A symbol carrying a character the API uses as a separator throws from From(IEnumerable<string>) with its own message.- ArgumentOutOfRangeException
Start is UndefTimestamp, which is not a time. Unlike the three absences this is not a state a real stream reaches — End decodes the same sentinel to null, but Start is not nullable and a stream with no start is not a stream.
FromQuery(GetRangeParams)
The parameters resolving a get_range request's symbols, over its own range and into
its own output symbology.
public static ResolveParams FromQuery(GetRangeParams request)Parameters
requestGetRangeParamsThe download whose symbols to resolve.
Returns
- ResolveParams
Parameters resolving
request's symbols over its own range.
Remarks
The overload that needs no stype_out argument, because
GetRangeParams carries one. This is the shape upstream's
From<GetRangeParams> actually has (symbology.rs:109-119); the
two-argument form above is the compromise that existed while this library had only the
billing type to convert from.
Prefer this one. Passing StypeOut by hand to the other overload is the drift this exists to remove — a resolution named in a symbology the download did not use fails nowhere, as that overload's remarks explain at length.
Exceptions
- ArgumentNullException
requestis null.- InvalidOperationException
request's DateTimeRange is a default value, which names no range.
FromQuery(MetadataQueryParams, SType)
Builds the parameters that resolve the symbols of a request you are about to send, or have just priced.
public static ResolveParams FromQuery(MetadataQueryParams query, SType stypeOut)Parameters
queryMetadataQueryParamsThe query whose symbols to resolve.
stypeOutSTypeThe symbology to resolve to — the same value the eventual
get_rangewill ask for.
Returns
- ResolveParams
Parameters resolving
query's symbols over its own range.
Remarks
Port of upstream's From<GetRangeParams> (symbology.rs:109-119), which
reads five fields off its source. This reads four, and takes the fifth as an argument.
stypeOut is a parameter rather than a field of
query, because MetadataQueryParams does not have one — and
that is a genuine gap rather than a porting choice. Upstream keeps two distinct types
here: GetQueryParams, for the three billing endpoints, carries no stype_out
(metadata.rs:328-346), while GetRangeParams, for
timeseries.get_range, does (timeseries.rs:189) and posts it
alongside encoding and compression (timeseries.rs:131-134), which the
billing endpoints also do not send. MetadataQueryParams is a port of the
first, so it cannot describe a get_range request. #38 settled it by introducing
GetRangeParams as a second type, which is what the
FromQuery(GetRangeParams) overload below reads its stype_out from.
This form stays for the caller who only ever holds a billing query.
Requiring it is what stops the failure this gap would otherwise cause. Defaulting to
InstrumentId — the value upstream's builder defaults to, and the
obvious thing to write — would silently resolve to instrument ids for the caller who is
about to request raw_symbol output, which is the one caller for whom the answer
matters. A resolution named in the wrong symbology is not an error anywhere: every symbol
resolves, nothing lands in NotFound, and the names are simply
wrong. There is no default that is right, so there is no default.
Upstream's second conversion, From<GetRangeToFileParams>, has no counterpart
because it delegates to this one after discarding a file path
(symbology.rs:121-125).
Exceptions
- ArgumentNullException
queryis null.- InvalidOperationException
query's DateTimeRange is a default value, which names no range.
ToFormParameters()
Renders this parameter set as the form body symbology.resolve posts.
public IReadOnlyList<KeyValuePair<string, string>> ToFormParameters()Returns
- IReadOnlyList<KeyValuePair<string, string>>
The form fields, in upstream's push order.
Remarks
The order is upstream's push order (symbology.rs:30-36), which puts both symbology
types before the symbols they describe, and appends the date pair last through the same
add_to_form the billing endpoints use.
Exceptions
- InvalidOperationException
Symbols or DateRange is left at its type's default value. required forces a caller to assign each but does not stop them assigning default, so both renderers refuse one, as their own accessors document.
TryFromMetadata(Metadata, out ResolveParams?)
FromMetadata(Metadata) for metadata that may legitimately not support a resolution.
public static bool TryFromMetadata(Metadata metadata, out ResolveParams? parameters)Parameters
metadataMetadataThe decoded stream metadata.
parametersResolveParamsThe parameters, or null when
metadatalacks one of the three.
Returns
Remarks
Three absences, each a normal state for a real stream rather than a corruption.
StypeIn is null when a stream mixed several input
symbologies, the ordinary case for live data. End is
null for an open-ended query — every live session. Either one alone makes
a resolution request unformulable, and upstream's TryFrom reports exactly these two
(symbology.rs:89-97).
The third is this port's, and it is not upstream's oversight so much as a difference in
what the two Symbols types permit. Upstream builds
Symbols::Symbols(metadata.symbols) unconditionally, so an empty list renders as
symbols= and asks the API to resolve nothing;
From(IEnumerable<string>) refuses to construct an
empty set at all, for the reasons that type documents. Reporting it here rather than
letting the factory throw is what keeps this method's contract — a
false for every expected absence.
What still throws, deliberately. Two things, and both describe a corrupt file rather than an ordinary stream: a symbol carrying a character the wire uses as a separator, which From(IEnumerable<string>) refuses, and a Start holding UndefTimestamp. Swallowing either into a false would report "this metadata does not support resolution" for what is actually a broken stream, which is the wrong thing to tell a caller who would then go looking at their symbology arguments.
Exceptions
- ArgumentNullException
metadatais null.