5.2.17. xgt.JobProgress

class xgt.JobProgress(phase: str, substep: str | None, rows_processed: int, rows_total: int | None, percent: float | None, percent_is_estimate: bool, phase_elapsed: timedelta, traversed_edges: int, job_id: int | None = None)

Live execution progress for a running job, from Job.progress.

Note

Progress is a liveness indicator of work in flight, not a guarantee of committed data. A job is transactional – all-or-nothing – so if it errors or is rolled back, none of the reported progress is persisted (there is no partial commit). The values are therefore meaningful only while the job runs and on successful completion: a job can report substantial progress and then fail, discarding all of it. Use the job’s final Job.status for the authoritative outcome.

Added in version 2.7.0.

Parameters:

• job_id (int | None) – Id of the job this progress belongs to; None if the server did not report it.

• phase (str) – Current execution phase: one of "reading", "building", "executing", "writing" (save/egest), "committing", "done", or "unspecified" (queued / not yet running).

• substep (str | None) – Finer step within the phase, or None when the phase reports none.

• rows_processed (int) – Rows seen so far. Live and approximate – not the authoritative final row count. 0 before the reading phase begins.

• rows_total (int | None) – Total rows expected, when known up front (e.g. Parquet). None for sources whose size isn’t known until fully read.

• percent (float | None) – Progress within the current phase, 0-100. None when no trustworthy denominator exists; fall back to substep and phase_elapsed.

• percent_is_estimate (bool) – True when percent is a byte-based estimate rather than an exact row fraction.

• phase_elapsed (timedelta) – Wall-clock time spent in the current phase so far.

• traversed_edges (int) – Edges traversed so far by a running query (live, exact). 0 for non-query jobs.

Attributes

job_id	Id of the job this progress belongs to, or None if unreported.
phase	Current execution phase (e.g. "reading", "executing", "writing").
substep	Finer step within the phase, or None when the phase reports none.
rows_processed	Rows seen so far (live, approximate); 0 before the reading phase begins.
rows_total	Total rows expected when known up front (e.g. Parquet), else None.
percent	Progress within the current phase (0-100), or None when no denominator.
percent_is_estimate	True when percent is a byte-based estimate, not an exact row fraction.
phase_elapsed	Wall-clock time spent in the current phase so far.
traversed_edges	Edges traversed so far by a running query (0 for non-query jobs).

job_id: int | None = None

Id of the job this progress belongs to, or None if unreported.

percent: float | None

Progress within the current phase (0-100), or None when no denominator.

percent_is_estimate: bool

True when percent is a byte-based estimate, not an exact row fraction.

phase: str

Current execution phase (e.g. “reading”, “executing”, “writing”).

phase_elapsed: timedelta

Wall-clock time spent in the current phase so far.

rows_processed: int

Rows seen so far (live, approximate); 0 before the reading phase begins.

rows_total: int | None

Total rows expected when known up front (e.g. Parquet), else None.

substep: str | None

Finer step within the phase, or None when the phase reports none.

traversed_edges: int

Edges traversed so far by a running query (0 for non-query jobs).