Skip to content

catalog: document the source and sink statuses the code produces #38585

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
ggevay wants to merge 1 commit into
base: main
Choose a base branch
from
Open

catalog: document the source and sink statuses the code produces #38585

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
8 changes: 4 additions & 4 deletions doc/user/content/reference/system-catalog/mz_internal.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1280,7 +1280,7 @@ debugging.
| `name` | [`text`] | The name of the sink. |
| `type` | [`text`] | The type of the sink. |
| `last_status_change_at` | [`timestamp with time zone`] | Wall-clock timestamp of the sink status change. |
| `status` | [`text`] | The status of the sink: one of `created`, `starting`, `running`, `stalled`, `failed`, or `dropped`. |
| `status` | [`text`] | The status of the sink: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`. |
| `error` | [`text`] | If the sink is in an error state, the error message. |
| `details` | [`jsonb`] | Additional metadata provided by the sink. In case of error, may contain a `hint` field with helpful suggestions. |

Expand All @@ -1295,7 +1295,7 @@ messages and additional metadata helpful for debugging.
| -------------- | ------------------------------- | -------- |
| `occurred_at` | [`timestamp with time zone`] | Wall-clock timestamp of the sink status change. |
| `sink_id` | [`text`] | The ID of the sink. Corresponds to [`mz_catalog.mz_sinks.id`](../mz_catalog#mz_sinks). |
| `status` | [`text`] | The status of the sink: one of `created`, `starting`, `running`, `stalled`, `failed`, or `dropped`. |
| `status` | [`text`] | The status of the sink: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`. |

@martykulma martykulma Aug 31, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't think created was valid in mz_sink_status_history, it shows up in mz_sink_statuses due to coalesce(status, 'created') as status so it wouldn't be NULL when joining against mz_sinks.

| `error` | [`text`] | If the sink is in an error state, the error message. |
| `details` | [`jsonb`] | Additional metadata provided by the sink. In case of error, may contain a `hint` field with helpful suggestions. |
| `replica_id` | [`text`] | The ID of the replica that an instance of a sink is running on. |
Expand Down Expand Up @@ -1402,7 +1402,7 @@ debugging.
| `name` | [`text`] | The name of the source. |
| `type` | [`text`] | The type of the source. |
| `last_status_change_at` | [`timestamp with time zone`] | Wall-clock timestamp of the source status change. |
| `status` | [`text`] | The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, `failed`, or `dropped`. |
| `status` | [`text`] | The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`. |
| `error` | [`text`] | If the source is in an error state, the error message. |
| `details` | [`jsonb`] | Additional metadata provided by the source. In case of error, may contain a `hint` field with helpful suggestions. |

Expand All @@ -1417,7 +1417,7 @@ messages and additional metadata helpful for debugging.
| -------------- | ------------------------------- | -------- |
| `occurred_at` | [`timestamp with time zone`] | Wall-clock timestamp of the source status change. |
| `source_id` | [`text`] | The ID of the source. Corresponds to [`mz_catalog.mz_sources.id`](../mz_catalog#mz_sources). |
| `status` | [`text`] | The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, `failed`, or `dropped`. |
| `status` | [`text`] | The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`. |
| `error` | [`text`] | If the source is in an error state, the error message. |
| `details` | [`jsonb`] | Additional metadata provided by the source. In case of error, may contain a `hint` field with helpful suggestions. |
| `replica_id` | [`text`] | The ID of the replica that an instance of a source is running on. |
Expand Down
4 changes: 2 additions & 2 deletions doc/user/content/serve-results/sink/sink-troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ SELECT * FROM mz_internal.mz_sink_statuses
WHERE name = <SINK_NAME>;
```

If your sink reports a status of `stalled` or `failed`, you likely have a
configuration issue. The returned `error` field will provide details.
If your sink reports a status of `stalled`, you likely have a configuration
issue. The returned `error` field will provide details.

If your sink reports a status of `starting` for more than a few minutes,
[contact support](/support).
Expand Down
8 changes: 4 additions & 4 deletions src/catalog/src/builtin/mz_internal.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1318,7 +1318,7 @@ pub static MZ_SOURCE_STATUS_HISTORY: LazyLock<BuiltinSource> = LazyLock::new(||
),
(
"status",
"The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, `failed`, or `dropped`.",
"The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`.",
),
(
"error",
Expand Down Expand Up @@ -2169,7 +2169,7 @@ pub static MZ_SOURCE_STATUSES: LazyLock<BuiltinView> = LazyLock::new(|| BuiltinV
),
(
"status",
"The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, `failed`, or `dropped`.",
"The status of the source: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`.",
),
(
"error",
Expand Down Expand Up @@ -2368,7 +2368,7 @@ pub static MZ_SINK_STATUS_HISTORY: LazyLock<BuiltinSource> = LazyLock::new(|| Bu
),
(
"status",
"The status of the sink: one of `created`, `starting`, `running`, `stalled`, `failed`, or `dropped`.",
"The status of the sink: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`.",
),
(
"error",
Expand Down Expand Up @@ -2451,7 +2451,7 @@ pub static MZ_SINK_STATUSES: LazyLock<BuiltinView> = LazyLock::new(|| BuiltinVie
),
(
"status",
"The status of the sink: one of `created`, `starting`, `running`, `stalled`, `failed`, or `dropped`.",
"The status of the sink: one of `created`, `starting`, `running`, `paused`, `stalled`, or `dropped`.",
),
(
"error",
Expand Down
8 changes: 4 additions & 4 deletions test/sqllogictest/autogenerated/mz_internal.slt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -683,7 +683,7 @@ id text The␠ID␠of␠the␠sink.␠Corresponds␠to␠`mz_catalog.mz_sinks.
name text The␠name␠of␠the␠sink.
type text The␠type␠of␠the␠sink.
last_status_change_at timestamp␠with␠time␠zone Wall-clock␠timestamp␠of␠the␠sink␠status␠change.
status text The␠status␠of␠the␠sink:␠one␠of␠`created`,␠`starting`,␠`running`,␠`stalled`,␠`failed`,␠or␠`dropped`.
status text The␠status␠of␠the␠sink:␠one␠of␠`created`,␠`starting`,␠`running`,␠`paused`,␠`stalled`,␠or␠`dropped`.
error text If␠the␠sink␠is␠in␠an␠error␠state,␠the␠error␠message.
details jsonb Additional␠metadata␠provided␠by␠the␠sink.␠In␠case␠of␠error,␠may␠contain␠a␠`hint`␠field␠with␠helpful␠suggestions.

Expand All @@ -692,7 +692,7 @@ SELECT name, type, comment FROM objects WHERE schema = 'mz_internal' AND object
----
occurred_at timestamp␠with␠time␠zone Wall-clock␠timestamp␠of␠the␠sink␠status␠change.
sink_id text The␠ID␠of␠the␠sink.␠Corresponds␠to␠`mz_catalog.mz_sinks.id`.
status text The␠status␠of␠the␠sink:␠one␠of␠`created`,␠`starting`,␠`running`,␠`stalled`,␠`failed`,␠or␠`dropped`.
status text The␠status␠of␠the␠sink:␠one␠of␠`created`,␠`starting`,␠`running`,␠`paused`,␠`stalled`,␠or␠`dropped`.
error text If␠the␠sink␠is␠in␠an␠error␠state,␠the␠error␠message.
details jsonb Additional␠metadata␠provided␠by␠the␠sink.␠In␠case␠of␠error,␠may␠contain␠a␠`hint`␠field␠with␠helpful␠suggestions.
replica_id text The␠ID␠of␠the␠replica␠that␠an␠instance␠of␠a␠sink␠is␠running␠on.
Expand Down Expand Up @@ -722,7 +722,7 @@ id text The␠ID␠of␠the␠source.␠Corresponds␠to␠`mz_catalog.mz_sour
name text The␠name␠of␠the␠source.
type text The␠type␠of␠the␠source.
last_status_change_at timestamp␠with␠time␠zone Wall-clock␠timestamp␠of␠the␠source␠status␠change.
status text The␠status␠of␠the␠source:␠one␠of␠`created`,␠`starting`,␠`running`,␠`paused`,␠`stalled`,␠`failed`,␠or␠`dropped`.
status text The␠status␠of␠the␠source:␠one␠of␠`created`,␠`starting`,␠`running`,␠`paused`,␠`stalled`,␠or␠`dropped`.
error text If␠the␠source␠is␠in␠an␠error␠state,␠the␠error␠message.
details jsonb Additional␠metadata␠provided␠by␠the␠source.␠In␠case␠of␠error,␠may␠contain␠a␠`hint`␠field␠with␠helpful␠suggestions.

Expand All @@ -731,7 +731,7 @@ SELECT name, type, comment FROM objects WHERE schema = 'mz_internal' AND object
----
occurred_at timestamp␠with␠time␠zone Wall-clock␠timestamp␠of␠the␠source␠status␠change.
source_id text The␠ID␠of␠the␠source.␠Corresponds␠to␠`mz_catalog.mz_sources.id`.
status text The␠status␠of␠the␠source:␠one␠of␠`created`,␠`starting`,␠`running`,␠`paused`,␠`stalled`,␠`failed`,␠or␠`dropped`.
status text The␠status␠of␠the␠source:␠one␠of␠`created`,␠`starting`,␠`running`,␠`paused`,␠`stalled`,␠or␠`dropped`.
error text If␠the␠source␠is␠in␠an␠error␠state,␠the␠error␠message.
details jsonb Additional␠metadata␠provided␠by␠the␠source.␠In␠case␠of␠error,␠may␠contain␠a␠`hint`␠field␠with␠helpful␠suggestions.
replica_id text The␠ID␠of␠the␠replica␠that␠an␠instance␠of␠a␠source␠is␠running␠on.
Expand Down
Loading