Skip to content

[doc](opt) Add mv task job mv_info opt docs #3637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
seawinde wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[doc](opt) Add mv task job mv_info opt docs #3637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 65 additions & 21 deletions docs/sql-manual/sql-functions/table-valued-functions/jobs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---

Check notice on line 1 in docs/sql-manual/sql-functions/table-valued-functions/jobs.md

View workflow job for this annotation

GitHub Actions / Build Check

i18n-sync-locale-candidate 

Japanese docs are report-only. Generate a candidate translation from the changed files and merge it only after human review. Owner%3A @zclllyybb

Check notice on line 1 in docs/sql-manual/sql-functions/table-valued-functions/jobs.md

View workflow job for this annotation

GitHub Actions / Build Check

i18n-sync-version-candidate 

A 3.x counterpart exists. Confirm whether the change is supported in 3.x before leaving it unsynced. Owner%3A @zclllyybb

Check warning on line 1 in docs/sql-manual/sql-functions/table-valued-functions/jobs.md

View workflow job for this annotation

GitHub Actions / Build Check

seo-title-duplicate 

Rendered SEO title is duplicated across indexable pages%3A "JOBS - Apache Doris". Add a version%2C locale%2C or page-specific qualifier. Owner%3A @zclllyybb
{
"title": "JOBS",
"language": "en",
Expand Down Expand Up @@ -49,34 +49,78 @@

| Field | Description |
|----------------------|-------------------------------------------------------------|
| Id | job ID |
| Name | job name |
| MvId | Materialized View ID |
| MvName | Materialized View Name |
| MvDatabaseId | DB ID of the materialized view |
| MvDatabaseName | Name of the database to which the materialized view belongs |
| ExecuteType | Execution type |
| RecurringStrategy | Loop strategy |
| Status | Job status |
| CreateTime | Task creation time |
| Id | Job ID. For MV jobs, it corresponds to `tasks("type"="mv").JobId`. |
| Name | Job name. For MV jobs, it corresponds to `mv_infos("database"="...").JobName` and `tasks("type"="mv").JobName`. |
| MvId | ID of the materialized view maintained by this job. |
| MvName | Name of the materialized view maintained by this job. |
| MvDatabaseId | ID of the database that contains the materialized view. |
| MvDatabaseName | Name of the database that contains the materialized view. |
| ExecuteType | Job execution type. For MV jobs, possible values are `MANUAL` and `RECURRING`. `MANUAL` means refresh tasks are triggered manually, by commit, or by internal events. `RECURRING` means refresh tasks are scheduled periodically. |
| RecurringStrategy | Scheduling description derived from `ExecuteType`. `MANUAL TRIGGER` means the job does not run on a timer. `EVERY ... STARTS ... [ENDS ...]` means the job runs periodically. |
| Status | Job status. Possible values: `PENDING` means the job is waiting for scheduling; `RUNNING` means the job can produce tasks; `PAUSED` means the job is paused and can be resumed; `STOPPED` means the job has been stopped and cannot be resumed; `FINISHED` means the job has finished. |
| CreateTime | Time when the job was created. |

### MV job enum fields

The following enum fields are commonly used when checking materialized view refresh jobs:

- `ExecuteType`: how the job creates refresh tasks.
- `MANUAL`: the job does not run on its own timer. A task is created only when a refresh is triggered manually, by commit, or by the system.
- `RECURRING`: the job runs on a schedule and periodically creates refresh tasks.
- `RecurringStrategy`: human-readable scheduling rule generated from `ExecuteType`.
- `MANUAL TRIGGER`: the job is not scheduled periodically. This is the usual value when `ExecuteType` is `MANUAL`.
- `EVERY <interval> <unit> STARTS <time> [ENDS <time>]`: the job is scheduled periodically. For example, `EVERY 10 MINUTE STARTS 2025-01-17 14:42:53`.
- `Status`: current state of the job itself.
- `PENDING`: the job is waiting to be scheduled.
- `RUNNING`: the job is active and can create refresh tasks.
- `PAUSED`: the job is paused. It will not create new refresh tasks until it is resumed.
- `STOPPED`: the job has been stopped and cannot be resumed.
- `FINISHED`: the job has finished. This is uncommon for long-lived MV refresh jobs, but it can appear in the generic job framework.

For materialized views, one materialized view has one refresh job, and one refresh job can create many refresh tasks. Use `jobs("type"="mv").Name` to connect the job to `mv_infos("database"="...").JobName` and `tasks("type"="mv").JobName`.


## Examples

View jobs in all materialized views
View the refresh job of a materialized view.

```sql
select * from jobs("type"="mv");
select *
from jobs("type"="mv")
where MvDatabaseName = "test" and MvName = "mv1"\G
```
```text
+-------+------------------+-------+--------------------------+--------------+--------------------------------------------------------+-------------+-------------------+---------+---------------------+
| Id | Name | MvId | MvName | MvDatabaseId | MvDatabaseName | ExecuteType | RecurringStrategy | Status | CreateTime |
+-------+------------------+-------+--------------------------+--------------+--------------------------------------------------------+-------------+-------------------+---------+---------------------+
| 23369 | inner_mtmv_23363 | 23363 | range_date_up_union_mv1 | 21805 | regression_test_nereids_rules_p0_mv_create_part_and_up | MANUAL | MANUAL TRIGGER | RUNNING | 2025-01-08 18:19:10 |
| 23377 | inner_mtmv_23371 | 23371 | range_date_up_union_mv2 | 21805 | regression_test_nereids_rules_p0_mv_create_part_and_up | MANUAL | MANUAL TRIGGER | RUNNING | 2025-01-08 18:19:10 |
| 21794 | inner_mtmv_21788 | 21788 | test_tablet_type_mtmv_mv | 16016 | zd | MANUAL | MANUAL TRIGGER | RUNNING | 2025-01-08 12:26:06 |
| 19508 | inner_mtmv_19494 | 19494 | mv1 | 16016 | zd | MANUAL | MANUAL TRIGGER | RUNNING | 2025-01-07 22:13:31 |
+-------+------------------+-------+--------------------------+--------------+--------------------------------------------------------+-------------+-------------------+---------+---------------------+
*************************** 1. row ***************************
Id: 19508
Name: inner_mtmv_19494
MvId: 19494
MvName: mv1
MvDatabaseId: 16016
MvDatabaseName: test
ExecuteType: MANUAL
RecurringStrategy: MANUAL TRIGGER
Status: RUNNING
CreateTime: 2025-01-07 22:13:31
```

In this result:

- `Id` is the MV refresh job ID. It is the same value as `JobId` in `tasks("type"="mv")`.
- `Name` is the MV refresh job name. It is the same value as `JobName` in `mv_infos("database"="test")` and `tasks("type"="mv")`.
- `MvId` and `MvName` identify the materialized view maintained by this job.
- `MvDatabaseId` and `MvDatabaseName` identify the database that contains the materialized view.
- `ExecuteType` is `MANUAL`, so this job does not run by its own timer. A refresh task is created when the materialized view is manually refreshed, refreshed on commit, or triggered by the system.
- `RecurringStrategy` is `MANUAL TRIGGER`, which matches `ExecuteType = MANUAL`. For a scheduled materialized view, this field is displayed as `EVERY ... STARTS ...`.
- `Status` is `RUNNING`, so the job can generate refresh tasks. If it is `PAUSED`, resume the materialized view job before expecting new tasks.
- `CreateTime` is the time when this MV refresh job was created.

To view the tasks generated by this job, use the job name:

```sql
select *
from tasks("type"="mv")
where JobName = "inner_mtmv_19494"
order by CreateTime desc;
```

View all insert jobs
Expand All @@ -89,4 +133,4 @@
+----------------+----------------+---------+-------------+--------------------------------------------+---------+--------------------------------------------------------------+---------------------+------------------+-----------------+-------------------+---------+
| 78533940810334 | insert_tab_job | root | RECURRING | EVERY 10 MINUTE STARTS 2025-01-17 14:42:53 | RUNNING | INSERT INTO test.insert_tab SELECT * FROM test.example_table | 2025-01-17 14:32:53 | 0 | 0 | 0 | |
+----------------+----------------+---------+-------------+--------------------------------------------+---------+--------------------------------------------------------------+---------------------+------------------+-----------------+-------------------+---------+
```
```
Loading
Loading