Iteration

get_iteration(id::Integer)::Optional{Iteration}

Get a Iteration by id.

Arguments

• id::Integer: The id of the iteration to query.

Returns

A Iteration object. If the record does not exist, return nothing.

get_iteration(client::Client, id::Integer)::Optional{Iteration}

Fetch an Iteration via GET /iteration/{id}. Returns nothing when the server replies 404 and raises ClientError for other failures. Requires ReadPermission on the iteration's project.

get_iterations(experiment_id::Integer)::Array{Iteration, 1}

Get all Iteration for a given experiment.

Arguments

• experiment_id::Integer: The id of the experiment to query.

Returns

An array of Iteration objects.

get_iterations(experiment_id::Integer, page::Pagination)::PaginatedResponse{Iteration}

Get a page of Iteration records for an experiment, with total count populated.

Arguments

• experiment_id::Integer: The id of the experiment to query.
• page::Pagination: The page bounds (limit + offset).

Returns

A PaginatedResponse of Iteration.

get_iterations(client::Client, experiment_id::Integer)::Array{Iteration,1}

Convenience wrapper around the paged form: returns the first page (default limit) of Iteration records under experiment_id and discards the pagination envelope.

get_iterations(client::Client, experiment_id::Integer, page::Pagination)::PaginatedResponse{Iteration}

Fetch a page of Iteration records under experiment_id via GET /iteration/experiment/{experiment_id}?limit=…&offset=….

get_child_iterations(parent_id::Integer)::Array{Iteration, 1}

Return the direct children of parent_id — the iterations whose parent_iteration_id points at it — ordered by id ascending. Returns an empty array when no children exist.

Arguments

• parent_id::Integer: The id of the parent iteration.

Returns

An array of child Iteration objects.

get_child_iterations(client::Client, parent_id::Integer)::Array{Iteration,1}

Fetch the direct children of parent_id via GET /iteration/{parent_id}/children. Returns an empty array when no children exist. Requires ReadPermission on the iteration's project.

create_iteration(experiment_id::Integer; parent_iteration_id=nothing)::NamedTuple{id::Optional{<:Int64},status::DataType}

Create a Iteration.

When parent_iteration_id is supplied, the new row is a child run — used to model HPO trials, nested-CV folds, or distributed-worker fan-outs. The parent must already exist and must belong to the same experiment_id; cross-experiment lineage is rejected with Unprocessable.

Arguments

• experiment_id::Integer: The id of the experiment to create the iteration for.
• parent_iteration_id::Optional{Integer}: When set, the id of the parent iteration.

Returns

• The created iteration ID, or nothing on failure.
• An UpsertResult.

create_iteration(client::Client, experiment_id::Integer; parent_iteration_id=nothing)::Iteration

Open a fresh Iteration under experiment_id via POST /iteration/experiment/{experiment_id} and fetch the freshly-created row so the caller can immediately use its id and created_date. The parent experiment must be IN_PROGRESS. Requires CreatePermission on the owning project.

When parent_iteration_id is supplied, the new row is registered as a child of the given iteration (HPO trial, distributed worker, nested CV fold). The parent must belong to the same experiment_id.

update_iteration(id::Integer, notes::Optional{AbstractString}, end_date::Optional{DateTime}; status_id=nothing, error_message=nothing)::Type{<:UpsertResult}

Update a Iteration record.

Once an iteration has been finalised (end_date is set), the row is locked: further updates return Unprocessable. The intended terminal-state flow is to pass end_date, status_id, and (when applicable) error_message together in a single call.

Arguments

• id::Integer: The id of the iteration to update.
• notes::Optional{AbstractString}: The new notes for the iteration.
• end_date::Optional{DateTime}: The new end date for the iteration.
• status_id::Optional{Integer}: The new IterationStatus value. Must be one of the four valid integers (1..4) or nothing.
• error_message::Optional{AbstractString}: The captured exception text when the iteration ended in a FAILED state.

Returns

An UpsertResult.

update_iteration(id::Integer, notes::Optional{AbstractString}, end_date::Optional{DateTime}, status::IterationStatus; error_message=nothing)::Type{<:UpsertResult}

IterationStatus-typed overload of update_iteration.

update_iteration(client::Client, id::Integer; notes=nothing, end_date=nothing, status=nothing, error_message=nothing)::Nothing

Patch an Iteration via PATCH /iteration/{id}. Any keyword left as nothing is left untouched server-side. Once an iteration has an end_date set, the server locks it: further updates fail with ClientError "INVALID_PAYLOAD". Requires UpdatePermission on the owning project.

status accepts an IterationStatus enum value; the integer is sent on the wire.

delete_iteration(id::Integer)::Bool

Delete a Iteration record. Children whose parent_iteration_id points at this row have their reference set to NULL by the schema's foreign-key action; they continue to exist as standalone iterations until explicitly deleted.

Arguments

• id::Integer: The id of the iteration to delete. Also deletes all associated Parameter and Metric records.

Returns

true if the record was successfully deleted, false otherwise.

delete_iteration(client::Client, id::Integer)::Nothing

Delete an Iteration (and its Parameters + Metrics) via DELETE /iteration/{id}. Requires DeletePermission on the owning project.

with_iteration(f::Function, experiment_id::Integer; parent_iteration_id=nothing, snapshot=parent_iteration_id |> isnothing)

Open a fresh Iteration under experiment_id via create_iteration, pass it to f, and finalise the iteration's end_date and status_id regardless of whether the body returns normally or throws. On a clean return the iteration is marked SUCCEEDED; on an exception it is marked FAILED with the captured exception text in error_message, and the exception is rethrown so the caller still sees it.

By default the function calls snapshot_environment! on the new iteration right after creation, but only when it has no parent — driver runs capture the env, child runs inherit it. Pass snapshot=true to force a per-child capture (each child gets its own snapshot, useful when workers run in different processes) or snapshot=false to skip entirely.

Arguments

• f::Function: A unary function that receives the freshly-created Iteration.
• experiment_id::Integer: The id of the Experiment that owns the iteration.
• parent_iteration_id::Optional{Integer}: When set, the new iteration is registered as a child of the given parent — useful for HPO sweeps and distributed-worker fan-outs.
• snapshot::Bool: Whether to call snapshot_environment! after creation. Defaults to true for driver iterations and false for children.

Returns

Whatever f returns.

with_iteration(f::Function, client::Client, experiment_id::Integer; parent_iteration_id=nothing, snapshot=parent_iteration_id |> isnothing)

Open a fresh Iteration under experiment_id, invoke f(iteration), and finalise the iteration regardless of whether the body returns normally or throws. On a clean return the iteration is marked SUCCEEDED; on an exception it is marked FAILED with the captured exception text in error_message, and the exception is rethrown so the caller still sees it.

By default the helper attaches an EnvironmentSnapshot to the new iteration immediately after creation, but only when it has no parent — driver runs capture the env, child runs inherit it. Pass snapshot=true to force a per-child capture or snapshot=false to skip entirely.

When parent_iteration_id is supplied, the new iteration is registered as a child of the given parent — useful for HPO sweeps and distributed-worker fan-outs.

Example

client = DearDiary.connect("http://127.0.0.1:9000"; username="default", password="default")
result = with_iteration(client, experiment_id) do iter
    create_parameter(client, iter.id, "lr", 1e-3)
    for epoch in 1:10
        create_metric(client, iter.id, "loss", train_step!(model))
    end
    model
end