Class SubmitJobParams
- Namespace
- DatabentoDotNet.Historical
- Assembly
- DatabentoDotNet.Historical.dll
The parameter set batch.submit_job takes.
public sealed record SubmitJobParams : IEquatable<SubmitJobParams>- Inheritance
-
SubmitJobParams
- Implements
- Inherited Members
Remarks
Port of upstream's SubmitJobParams (batch.rs:436-498). Every default here is
upstream's builder default, so a job submitted with only the four
required properties set is the same job upstream's
SubmitJobParams::builder() would submit.
Submitting a job costs money, which is what separates this parameter set from every other one in this library. ToQuery() narrows it to the billing endpoints' parameters so the price can be asked for first; see GetCostAsync(MetadataQueryParams, CancellationToken).
Where the validation lives is decided by how many properties a rule reads.
SplitSize and Limit are checked in their own initializers, because
each rule reads one value. The other three rules — SplitSymbols against
Symbols, and the two pretty_* flags against Encoding —
each read two, and an init accessor cannot: object-initializer order is the
caller's to choose, so whichever property is assigned first would be validated against the
other's default rather than against the value the caller went on to set. Those three are
checked in ToFormParameters(), which is the first moment the object is complete.
Fields
MaximumSplitSize
The largest SplitSize the API accepts: 10 GB.
public const ulong MaximumSplitSize = 10000000000Field Value
MinimumSplitSize
The smallest SplitSize the API accepts: 1 GB.
public const ulong MinimumSplitSize = 1000000000Field Value
Properties
Compression
The compression to write the files with. Defaults to Zstd.
public Compression Compression { get; init; }Property Value
Dataset
The dataset code, for example GLBX.MDP3.
public required string Dataset { get; init; }Property Value
DateTimeRange
The request range: inclusive start, exclusive end.
public required DateTimeRange DateTimeRange { get; init; }Property Value
Remarks
The same convention timeseries.get_range uses, which #38 probed against the live API
— see DateTimeRange. Upstream documents the batch endpoint's
range identically (batch.rs:450-452), including that the filter is on ts_recv
where the schema has one and on ts_event otherwise.
Delivery
How to deliver the files. Defaults to Download.
public Delivery Delivery { get; init; }Property Value
Encoding
The encoding to write the files in. Defaults to Dbn.
public Encoding Encoding { get; init; }Property Value
Remarks
Unlike GetRangeParams, this is a real choice: a batch job's output is files on disk rather than a stream this library decodes, so CSV and JSON are as usable as DBN. That is also why PrettyPx, PrettyTs and MapSymbols exist at all — none of them means anything for a binary encoding.
Limit
The maximum number of records, or null for no limit, in which case the field is omitted rather than sent empty.
public ulong? Limit { get; init; }Property Value
Remarks
Zero is refused for the reason Limit gives at length: #38
probed it, and the API's answer to limit=0 contradicts itself — the body holds the
data and the header warns that none was found.
Exceptions
- ArgumentOutOfRangeException
The value is zero.
MapSymbols
Whether to write a symbol field with each text-encoded record, or null to let the encoding decide.
public bool? MapSymbols { get; init; }Property Value
- bool?
Remarks
null is the default and is not the same as false: it
renders as true for a text encoding and false for
Dbn, which is upstream's unwrap_or(encoding != Encoding::Dbn)
(batch.rs:76-82). The field is always sent, so the choice is made here rather than
left to the API's own default.
PrettyPx
Whether to write prices at their true scale rather than as fixed-precision integers. Defaults to false.
public bool PrettyPx { get; init; }Property Value
Remarks
Meaningful only for Csv and Json; ToFormParameters() refuses it with Dbn.
PrettyTs
Whether to write timestamps as ISO 8601 strings rather than as nanoseconds. Defaults to false.
public bool PrettyTs { get; init; }Property Value
Remarks
Meaningful only for Csv and Json; ToFormParameters() refuses it with Dbn.
Schema
The record schema to produce.
public required Schema Schema { get; init; }Property Value
SplitDuration
The interval to split the output at. Defaults to Day, as upstream's builder does.
public SplitDuration SplitDuration { get; init; }Property Value
SplitSize
The size in bytes to split each file at, or null for no size-based split.
public ulong? SplitSize { get; init; }Property Value
Remarks
Upstream's type is Option<NonZeroU64> and its doc comment gives the range —
"an integer between 1e9 and 10e9 inclusive (1GB - 10GB)" (batch.rs:476-478) — but
nothing in upstream enforces it, so a value outside the range becomes a round trip and a
rejection. The bound is checked here instead, which is also what makes the non-zero
constraint C# has no type for redundant: zero is below
MinimumSplitSize anyway.
Exceptions
- ArgumentOutOfRangeException
The value is outside MinimumSplitSize–MaximumSplitSize.
SplitSymbols
Whether to split the output into one file per raw symbol. Defaults to false.
public bool SplitSymbols { get; init; }Property Value
Remarks
Cannot be combined with All — there is no list of raw symbols to split by. ToFormParameters() refuses the combination.
StypeIn
public SType StypeIn { get; init; }Property Value
StypeOut
The symbology the output names instruments in. Defaults to InstrumentId.
public SType StypeOut { get; init; }Property Value
Symbols
The symbols to include.
public required Symbols Symbols { get; init; }Property Value
Methods
ToFormParameters()
Renders this parameter set as the form body batch.submit_job 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 (batch.rs:68-89), which is neither the declaration
order here nor upstream's own field order: the three optional fields are appended last
because upstream adds them through separate add_to_form calls, and
split_duration follows split_size for the same reason. 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.
Exceptions
- InvalidOperationException
A combination the API rejects was requested — see this type's remarks for why these three rules are checked here rather than in an initializer — or Symbols or DateTimeRange was left at its type's default value.
ToQuery()
Narrows this to the parameters the three metadata.* billing endpoints take, so a
caller can price exactly the job they are about to submit.
public MetadataQueryParams ToQuery()Returns
- MetadataQueryParams
The same request, priced rather than submitted.
Remarks
The same conversion ToQuery() makes, and for a stronger reason:
timeseries.get_range bills for what it streams, while a batch job bills for the whole
range at once and cannot be interrupted part-way. Upstream has no equivalent and leaves its
callers to build the billing object by hand.
Drops StypeOut and every formatting and splitting option, none of which the billing endpoints take or could use — a price depends on how much data is in the range, not on how it is written out.