Manage import jobs
The Import Tasks page in EMR StarRocks Manager gives you a visual view of all import jobs in your StarRocks instance — without running SQL commands. Use it to monitor job progress, diagnose failures, and control jobs that are stuck or running unexpectedly.
Data on the Import Tasks page comes from StarRocks kernel query commands such as SHOW LOAD. Its lifecycle matches the data stored in the StarRocks kernel.
Broker Load is an asynchronous import method. A job that submits without errors may still fail. After submitting a Broker Load job, check the Import Tasks page to confirm the final status.
Prerequisites
Before you begin, ensure that you have:
A connected StarRocks instance. For more information, see SQL editor.
Limitations
Import task management requires a StarRocks instance with minor version 2.5.8-1.7-1.1.3 or later.
View import jobs
To view Stream Load jobs, run SET GLOBAL enable_load_profile = true first.
On the Import Tasks page, you can:
View jobs in Broker Load, Routine Load, Stream Load, or Insert mode.
Sort jobs by job ID or creation time, in ascending or descending order.
Filter jobs by warehouse name, database name, table name, job ID, status, or tag.
Job states by mode
Each import mode has its own set of states. Understanding what each state means helps you decide whether to wait or intervene.
States fall into two categories:
Terminal states — the job has ended. No further action is needed or possible.
In-progress states — the job is still running or waiting. Monitor these to decide whether to wait or intervene.
The following tables map each state to its category and what the system is doing.
Broker Load
| State | Category | What it means |
|---|---|---|
| FINISHED | Terminal | The job succeeded. |
| CANCELLED | Terminal | The job failed. |
| QUEUEING | In progress | The job is waiting in the queue to be scheduled. |
| PENDING | In progress | The job has been created but not yet started. |
| LOADING | In progress | The job is actively importing data. |
| PREPARED | In progress | The import job is submitted. |
Routine Load
| State | Category | What it means |
|---|---|---|
| STOPPED | Terminal | The job has ended and cannot be restarted. |
| CANCELLED | Terminal | The job failed. |
| NEED_SCHEDULE | In progress | The job is waiting to be rescheduled. |
| RUNNING | In progress | The job is actively consuming messages from Kafka. |
| PAUSED | In progress | The job is suspended. Resume it when ready. |
Stream Load
| State | Category | What it means |
|---|---|---|
| FINISHED | Terminal | The job succeeded. |
| CANCELLED | Terminal | The job failed. |
| BEGIN | In progress | The job has started. |
| BEFORE_LOAD | In progress | The data is queued and waiting to be imported. |
| LOADING | In progress | The data is being imported. |
| PREPARING | In progress | The job is preparing to commit. |
| PREPARED | In progress | The job is presubmitted. |
| COMMITED | In progress | The import job is submitted. |
Insert
Insert mode supports internal tables only.
| State | Category | What it means |
|---|---|---|
| FINISHED | Terminal | The job succeeded. |
| CANCELLED | Terminal | The job failed. |
| QUEUEING | In progress | The job is waiting in the queue to be scheduled. |
| PENDING | In progress | The job has been created but not yet started. |
| LOADING | In progress | The job is actively running. |
| PREPARED | In progress | The import job is submitted. |
View job details
On the Import Tasks page, click the tab for the import mode you want to inspect.
Find the job and click its job ID.
On the Task Details page, review the job details and error logs if the job failed.
When a job shows CANCELLED status on the list page, hover over the status to see a quick error summary. For the full error log, go to the Task Details tab.
Detail fields by mode
Broker Load
| Field | Description |
|---|---|
etlInfo | Extract, transform, and load (ETL) information. |
taskInfo | Parameters set at job creation: resource (not used), timeout (seconds), and max-filter-ratio (maximum fraction of rows that can be filtered due to data quality issues). |
jobDetails | Number of tasks, imported file count and size, total data volume, and row count. |
errorMessage | null when the job is in PENDING, LOADING, or FINISHED state. When CANCELLED, contains type and msg. See the errorMessage type values below. |
trackingSQL | SQL statement to query the error log directly. |
trackingLogs | Error log details. |
`errorMessage` type values:
| Type | Meaning | Next step |
|---|---|---|
USER_CANCEL | The job was manually canceled. | No action required. |
ETL_SUBMIT_FAIL | The job failed during submission. | Check network connectivity and job configuration. |
ETL_QUALITY_UNSATISFIED | The error rate exceeded max-filter-ratio. | Review max-filter-ratio in taskInfo and inspect trackingLogs for filtered rows. |
LOAD_RUN_FAIL | The job failed during the loading phase. | Inspect trackingLogs for the root cause. |
TIMEOUT | The job did not complete within the timeout period. | Increase the timeout value in taskInfo or reduce the data volume per job. |
UNKNOWN | An unexpected error occurred. | Inspect trackingLogs for details. |
Routine Load
| Field | Description |
|---|---|
jobProperties | Job configuration properties. |
dataSourceProperties | Data source configuration, such as Kafka topic and partition offsets. |
customProperties | User-defined properties. |
statistics | Row count and data volume processed so far. |
reasonOfStateChanged | Explanation of the most recent state transition. |
errorLogUrls | URL to the error log for failed jobs. |
otherMsg | Additional diagnostic information. |
trackingSQL | SQL statement to query the error log directly. |
trackingLogs | Error log details. |
Stream Load
| Field | Description |
|---|---|
errorMessage | Error message for failed jobs. |
trackingSQL | SQL statement to query the error log directly. |
trackingLogs | Error log details. |
Insert
| Field | Description |
|---|---|
etlInfo | ETL information. |
taskInfo | Parameters set at job creation: resource (not used in Insert jobs), timeout (seconds), and max-filter-ratio. |
jobDetails | Number of tasks, imported file count and size, total data volume, and row count. |
errorMessage | null when the job is in PENDING, LOADING, or FINISHED state. When CANCELLED, contains type and msg (same types as Broker Load). |
trackingSQL | SQL statement to query the error log directly. |
trackingLogs | Error log details. |
View job profiles
A job profile contains performance metrics for diagnosing slow or inefficient import jobs.
On the Import Tasks page, click the tab for the import mode.
Find the job and click its ID in the Task ID column.
Click the Task Profile tab.
Profile retention limits:
Only the most recent 500 job profiles are retained per StarRocks instance. This applies to both Broker Load and Stream Load jobs.
For Stream Load, profiles are collected only for jobs that run for more than 10 seconds. High-frequency real-time imports generate many short-lived tasks, so most are excluded by default.
If you need to inspect jobs beyond the 500-profile limit, query the StarRocks information schema directly using SHOW LOAD or SHOW ROUTINE LOAD in the SQL editor.
Manage import jobs
You can take action on jobs in Broker Load or Routine Load mode that have not yet reached a terminal state.
| Mode | Action | Result |
|---|---|---|
| Broker Load | Cancel | The job enters CANCELLED state and stops immediately. |
| Routine Load | Pause | The job enters PAUSED state. Click Resume in the Actions column to restart it. |
| Routine Load | Restore | The job briefly enters NEED_SCHEDULE state while being rescheduled, then returns to RUNNING and resumes consuming Kafka messages. |
| Routine Load | Stop | The job enters STOPPED state permanently. This action cannot be undone. |
Example: monitor and troubleshoot Broker Load jobs
This example shows how to create two Broker Load jobs — one successful and one that fails due to dirty data — and then use StarRocks Manager to diagnose the failure.
Create two import jobs in Broker Load mode. For more information, see Broker Load. For the second job, modify the table data to introduce dirty data. This simulates a job that exceeds the
max-filter-ratiothreshold and enters CANCELLED state. For other import modes, see Routine Load and Stream Load.Open StarRocks Manager:
Log on to the EMR console.
In the left-side navigation pane, choose EMR Serverless > StarRocks.
In the top navigation bar, select the region where your instance is deployed.
Click StarRocks Manager, or find the instance and click Connect in the Actions column. For more information, see Use EMR StarRocks Manager to connect to an EMR Serverless StarRocks instance.
Connect to the StarRocks instance. For more information, see SQL editor.
In the left-side navigation pane, click Import Tasks. The page lists all import jobs in your account. For jobs in CANCELLED state, hover over the status to see a brief error summary.
Click the Broker Load tab (selected by default).
Find the failed job and click its job ID.
On the Task Details tab, check
errorMessageto identify the failure type. ForETL_QUALITY_UNSATISFIEDerrors, reviewmax-filter-ratiointaskInfoand inspecttrackingLogsfor the specific rows that were filtered.On the Task Profile tab, review performance metrics to identify bottlenecks if the job ran slowly before failing.