Class SecurityMasterGetRangeParams
- Namespace
- DatabentoDotNet.Reference
- Assembly
- DatabentoDotNet.Reference.dll
The parameter set security_master.get_range takes: which symbols, over what range of
which timestamp, optionally narrowed to a set of countries or security types.
public sealed record SecurityMasterGetRangeParams : IEquatable<SecurityMasterGetRangeParams>- Inheritance
-
SecurityMasterGetRangeParams
- Implements
- Inherited Members
Remarks
Port of upstream's security::GetRangeParams (security.rs:95-130). Named for its
endpoint rather than as a bare GetRangeParams, for the reason
AdjustmentFactorsGetRangeParams records: upstream can reuse that name in three
modules of one crate and C# cannot reuse it in one namespace.
This differs from SecurityMasterGetLastParams by exactly three form fields —
index, start and end — and the two types are deliberately unrelated.
Making one inherit the other would let a caller hand this to
GetLastAsync(SecurityMasterGetLastParams, CancellationToken), where the range it names would be silently
dropped rather than refused. Upstream keeps them as two independent structs for its own reasons;
the reason to keep them so here is that the compiler then does the refusing.
compression is not a property, because it is not a choice. Upstream hard-codes
compression=zstd on both of these endpoints (security.rs:40, :70) and so
does ToFormParameters(). The response handler requires the frame — an uncompressed
body would not parse — so a caller who could set it could only break the request.
Properties
AllocateIsins
Whether the request may allocate new ISINs on an ISIN-limited plan. Defaults to true, as upstream's builder does.
public bool AllocateIsins { get; init; }Property Value
Remarks
A billing consequence hiding in a default, and it bites harder here than anywhere else in
this library. This is the endpoint whose whole purpose is to return identifiers, so a
request for symbols the plan has not seen before is exactly the request that can create new
allocations against an ISIN-limited entitlement (security.rs:126-130). Set it
false and the API drops the rows that would have done so rather than
returning them — fewer rows, no allocation. The default is upstream's and is kept, because a
client that silently returned fewer rows than upstream for the same parameters would be the
worse surprise.
No test that reaches the real API may leave this true without going through #57's gate. That is a rule about spending someone's entitlement, not a style preference, and it is the one thing about this property that is not merely documentation.
Countries
The countries to filter for, or null to include every country.
public IReadOnlyList<Country>? Countries { get; init; }Property Value
Remarks
An empty sequence means the same thing as null: the parameter is left out. A default Country in the list is a caller mistake and is refused — see Render<T>(IEnumerable<T>?).
DateTimeRange
The request range: inclusive start, optional exclusive end.
public required ReferenceDateTimeRange DateTimeRange { get; init; }Property Value
Remarks
Filters on Index — which is what makes that property a request parameter here rather than a presentation choice. Omit the end and the response runs to the end of the data; see ReferenceDateTimeRange, which also records that the exclusive end is documented rather than probed.
Index
Which timestamp DateTimeRange applies to. Defaults to TsEffective, as upstream's builder does.
public SecurityMasterIndex Index { get; init; }Property Value
Remarks
The field this endpoint has and get_last does not. It changes which rows come
back, not their order: upstream also sorts its buffered response by it
(security.rs:50-53) and GetRangeAsync(SecurityMasterGetRangeParams, CancellationToken) streams, so
the sort is not performed here. See SecurityMasterIndex.
SecurityTypes
The security types to filter for, or null to include every type.
public IReadOnlyList<SecurityType>? SecurityTypes { get; init; }Property Value
Remarks
StypeIn
public SType StypeIn { get; init; }Property Value
Symbols
The symbols to filter for.
public required Symbols Symbols { get; init; }Property Value
Methods
ToFormParameters()
Renders this parameter set as the form body security_master.get_range 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 (security.rs:36-46), which is not the order the
properties are declared in: index leads, stype_in precedes symbols,
allocate_isins and compression sit before the range, and the two optional
filters come last. It makes no difference to the API and it makes the rendered body
byte-comparable with upstream's, which is the cheapest way to tell this rendering apart from
a plausible one.
The four fields shared with ToFormParameters()
are written out in both places rather than shared. They are also written out a third
time in ToFormParameters(), which is upstream's
arrangement (security.rs:36-40, :66-70, adjustment.rs:32-36) and is
kept: a shared renderer used by two of the three endpoints would be worse than one
used by none or by all, and #55 — which arrived with the fourth body — answered the question
by writing it out again. ToFormParameters()
carries the reasoning.
For a request with no country or security-type filter and an open range, the key set is
exactly {index, stype_in, symbols, allocate_isins, compression, start} — six fields,
with nothing sent empty.
Exceptions
- InvalidOperationException
Symbols or DateTimeRange is left at its type's default value. required forces a caller to assign each property but does not stop them assigning default, and the accessors this reads refuse to render one.
- ArgumentException
A default Country or SecurityType appears in a filter list.
- ArgumentOutOfRangeException
Index is not a defined SecurityMasterIndex.