# Update

Launch stage: GA

`PATCH /api/2.0/alerts/{alert.id}`

Update alert

API scopes: alerts

## Path parameters

- `alert` (object, optional)
  - `id` (string, optional)
    UUID identifying the alert.
    Example: `fe25e731-92f2-4838-9fb2-1ca364320a3d`
  - `display_name` (string, optional)
    The display name of the alert.
    Example: `Example alert`
  - `owner_user_name` (string, optional)
    The owner's username. This field is set to "Unavailable" if the user has been deleted.
    Example: `user@acme.com`
  - `create_time` (string, optional)
    The timestamp indicating when the alert was created.
  - `update_time` (string, optional)
    The timestamp indicating when the alert was updated.
  - `parent_path` (string, optional)
    The workspace path of the folder containing the alert. Can only be set on create, and cannot be updated.
    Example: `/Users/user@acme.com`
  - `query_text` (string, optional)
    Text of the query to be run.
    Example: `SELECT 1`
  - `warehouse_id` (string, optional)
    ID of the SQL warehouse attached to the alert.
    Example: `a7066a8ef796be84`
  - `run_as_user_name` (string, optional)
    The run as username or application ID of service principal.
     On Create and Update, this field can be set to application ID of an active service principal. Setting this field requires the servicePrincipal/user role.
     Deprecated: Use `run_as` field instead. This field will be removed in a future release.
    Example: `user@acme.com`
  - `evaluation` (object, optional)
    - `source` (object, optional)
      Source column from result to use to evaluate alert
      - `name` (string, optional)
      - `display` (string, optional)
      - `aggregation` (string, optional)
        If not set, the behavior is equivalent to using `First row` in the UI.
        Possible values: `SUM`, `COUNT`, `COUNT_DISTINCT`, `AVG`, `MEDIAN`, `MIN`, `MAX`, `STDDEV`
    - `comparison_operator` (string, optional)
      Operator used for comparison in alert evaluation.
      Possible values: `LESS_THAN`, `GREATER_THAN`, `EQUAL`, `NOT_EQUAL`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_NULL`, `IS_NOT_NULL`
    - `threshold` (object, optional)
      Threshold to user for alert evaluation, can be a column or a value.
      - `column` (object, required)
      - `value` (object, required)
    - `notification` (object, optional)
      User or Notification Destination to notify when alert is triggered.
      - `subscriptions` (array of object, optional)
      - `retrigger_seconds` (int32, optional)
        Number of seconds an alert waits after being triggered before it is allowed to send another notification.
         If set to 0 or omitted, the alert will not send any further notifications after the first trigger
         Setting this value to 1 allows the alert to send a notification on every evaluation where the condition is met, effectively making it always retrigger for notification purposes.
        Example: `0`
      - `notify_on_ok` (boolean, optional)
        Whether to notify alert subscribers when alert returns back to normal.
    - `state` (string, optional)
      Latest state of alert evaluation.
      Possible values: `UNKNOWN`, `TRIGGERED`, `OK`, `ERROR`
    - `last_evaluated_at` (string, optional)
      Timestamp of the last evaluation.
    - `empty_result_state` (string, optional)
      Alert state if result is empty. Please avoid setting this field to be `UNKNOWN` because `UNKNOWN` state is planned to be deprecated.
      Possible values: `UNKNOWN`, `TRIGGERED`, `OK`, `ERROR`
  - `schedule` (object, optional)
    - `quartz_cron_schedule` (string, optional)
      A cron expression using quartz syntax that specifies the schedule for this pipeline.
       Should use the quartz format described here: http://www.quartz-scheduler.org/documentation/quartz-2.1.7/tutorials/tutorial-lesson-06.html
    - `timezone_id` (string, optional)
      A Java timezone id. The schedule will be resolved using this timezone.
       This will be combined with the quartz_cron_schedule to determine the schedule.
       See https://docs.databricks.com/sql/language-manual/sql-ref-syntax-aux-conf-mgmt-set-timezone.html for details.
    - `pause_status` (string, optional)
      Indicate whether this schedule is paused or not.
      Possible values: `UNPAUSED`, `PAUSED`
      Default: `UNPAUSED`
  - `lifecycle_state` (string, optional)
    Indicates whether the query is trashed.
    Possible values: `ACTIVE`, `DELETED`
  - `custom_summary` (string, optional)
    Custom summary for the alert. support mustache template.
  - `custom_description` (string, optional)
    Custom description for the alert. support mustache template.
  - `run_as` (object, optional)
    Specifies the identity that will be used to run the alert.
     This field allows you to configure alerts to run as a specific user or service principal.
     - For user identity: Set `user_name` to the email of an active workspace user. Users can only set this to their own email.
     - For service principal: Set `service_principal_name` to the application ID. Requires the `servicePrincipal/user` role.
     If not specified, the alert will run as the request user.
    - `user_name` (string, required)
      The email of an active workspace user. Can only set this field to their own email.
      Example: `user@databricks.com`
    - `service_principal_name` (string, required)
      Application ID of an active service principal. Setting this field requires the `servicePrincipal/user` role.
      Example: `692bc6d0-ffa3-11ed-be56-0242ac120002`
  - `effective_run_as` (object, optional)
    The actual identity that will be used to execute the alert.
     This is an output-only field that shows the resolved run-as identity after applying
     permissions and defaults.
    - `user_name` (string, required)
      The email of an active workspace user. Can only set this field to their own email.
      Example: `user@databricks.com`
    - `service_principal_name` (string, required)
      Application ID of an active service principal. Setting this field requires the `servicePrincipal/user` role.
      Example: `692bc6d0-ffa3-11ed-be56-0242ac120002`

## Query parameters

- `update_mask` (string, optional)

## Returns

- `id` (string, optional)
  UUID identifying the alert.
  Example: `fe25e731-92f2-4838-9fb2-1ca364320a3d`
- `display_name` (string, optional)
  The display name of the alert.
  Example: `Example alert`
- `owner_user_name` (string, optional)
  The owner's username. This field is set to "Unavailable" if the user has been deleted.
  Example: `user@acme.com`
- `create_time` (string, optional)
  The timestamp indicating when the alert was created.
- `update_time` (string, optional)
  The timestamp indicating when the alert was updated.
- `parent_path` (string, optional)
  The workspace path of the folder containing the alert. Can only be set on create, and cannot be updated.
  Example: `/Users/user@acme.com`
- `query_text` (string, optional)
  Text of the query to be run.
  Example: `SELECT 1`
- `warehouse_id` (string, optional)
  ID of the SQL warehouse attached to the alert.
  Example: `a7066a8ef796be84`
- `run_as_user_name` (string, optional)
  The run as username or application ID of service principal.
   On Create and Update, this field can be set to application ID of an active service principal. Setting this field requires the servicePrincipal/user role.
   Deprecated: Use `run_as` field instead. This field will be removed in a future release.
  Example: `user@acme.com`
- `evaluation` (object, optional)
  - `source` (object, optional)
    Source column from result to use to evaluate alert
    - `name` (string, optional)
    - `display` (string, optional)
    - `aggregation` (string, optional)
      If not set, the behavior is equivalent to using `First row` in the UI.
      Possible values: `SUM`, `COUNT`, `COUNT_DISTINCT`, `AVG`, `MEDIAN`, `MIN`, `MAX`, `STDDEV`
  - `comparison_operator` (string, optional)
    Operator used for comparison in alert evaluation.
    Possible values: `LESS_THAN`, `GREATER_THAN`, `EQUAL`, `NOT_EQUAL`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN_OR_EQUAL`, `IS_NULL`, `IS_NOT_NULL`
  - `threshold` (object, optional)
    Threshold to user for alert evaluation, can be a column or a value.
    - `column` (object, required)
      - `name` (string, optional)
      - `display` (string, optional)
      - `aggregation` (string, optional)
        If not set, the behavior is equivalent to using `First row` in the UI.
        Possible values: `SUM`, `COUNT`, `COUNT_DISTINCT`, `AVG`, `MEDIAN`, `MIN`, `MAX`, `STDDEV`
    - `value` (object, required)
      - `string_value` (string, required)
        Example: `foo`
      - `double_value` (double, required)
        Example: `1.25`
      - `bool_value` (boolean, required)
        Example: `true`
  - `notification` (object, optional)
    User or Notification Destination to notify when alert is triggered.
    - `subscriptions` (array of object, optional)
      - `user_email` (string, required)
      - `destination_id` (string, required)
    - `retrigger_seconds` (int32, optional)
      Number of seconds an alert waits after being triggered before it is allowed to send another notification.
       If set to 0 or omitted, the alert will not send any further notifications after the first trigger
       Setting this value to 1 allows the alert to send a notification on every evaluation where the condition is met, effectively making it always retrigger for notification purposes.
      Example: `0`
    - `notify_on_ok` (boolean, optional)
      Whether to notify alert subscribers when alert returns back to normal.
  - `state` (string, optional)
    Latest state of alert evaluation.
    Possible values: `UNKNOWN`, `TRIGGERED`, `OK`, `ERROR`
  - `last_evaluated_at` (string, optional)
    Timestamp of the last evaluation.
  - `empty_result_state` (string, optional)
    Alert state if result is empty. Please avoid setting this field to be `UNKNOWN` because `UNKNOWN` state is planned to be deprecated.
    Possible values: `UNKNOWN`, `TRIGGERED`, `OK`, `ERROR`
- `schedule` (object, optional)
  - `quartz_cron_schedule` (string, optional)
    A cron expression using quartz syntax that specifies the schedule for this pipeline.
     Should use the quartz format described here: http://www.quartz-scheduler.org/documentation/quartz-2.1.7/tutorials/tutorial-lesson-06.html
  - `timezone_id` (string, optional)
    A Java timezone id. The schedule will be resolved using this timezone.
     This will be combined with the quartz_cron_schedule to determine the schedule.
     See https://docs.databricks.com/sql/language-manual/sql-ref-syntax-aux-conf-mgmt-set-timezone.html for details.
  - `pause_status` (string, optional)
    Indicate whether this schedule is paused or not.
    Possible values: `UNPAUSED`, `PAUSED`
    Default: `UNPAUSED`
- `lifecycle_state` (string, optional)
  Indicates whether the query is trashed.
  Possible values: `ACTIVE`, `DELETED`
- `custom_summary` (string, optional)
  Custom summary for the alert. support mustache template.
- `custom_description` (string, optional)
  Custom description for the alert. support mustache template.
- `run_as` (object, optional)
  Specifies the identity that will be used to run the alert.
   This field allows you to configure alerts to run as a specific user or service principal.
   - For user identity: Set `user_name` to the email of an active workspace user. Users can only set this to their own email.
   - For service principal: Set `service_principal_name` to the application ID. Requires the `servicePrincipal/user` role.
   If not specified, the alert will run as the request user.
  - `user_name` (string, required)
    The email of an active workspace user. Can only set this field to their own email.
    Example: `user@databricks.com`
  - `service_principal_name` (string, required)
    Application ID of an active service principal. Setting this field requires the `servicePrincipal/user` role.
    Example: `692bc6d0-ffa3-11ed-be56-0242ac120002`
- `effective_run_as` (object, optional)
  The actual identity that will be used to execute the alert.
   This is an output-only field that shows the resolved run-as identity after applying
   permissions and defaults.
  - `user_name` (string, required)
    The email of an active workspace user. Can only set this field to their own email.
    Example: `user@databricks.com`
  - `service_principal_name` (string, required)
    Application ID of an active service principal. Setting this field requires the `servicePrincipal/user` role.
    Example: `692bc6d0-ffa3-11ed-be56-0242ac120002`

## Request

```json
{
  "display_name": "Renamed alert",
  "evaluation": {
    "comparison_operator": "GREATER_THAN",
    "empty_result_state": "UNKNOWN",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 0,
      "subscriptions": [
        {
          "user_email": "user@acme.com"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "x",
      "name": "x"
    },
    "threshold": {
      "value": {
        "double_value": 1.25
      }
    }
  },
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "query_text": "SELECT 2 as x"
}
```

## Response

```json
{
  "create_time": "2019-08-24T14:15:22Z",
  "custom_description": "Custom email body",
  "custom_summary": "Custom email subject",
  "display_name": "Renamed alert",
  "evaluation": {
    "comparison_operator": "GREATER_THAN",
    "empty_result_state": "UNKNOWN",
    "notification": {
      "notify_on_ok": true,
      "retrigger_seconds": 0,
      "subscriptions": [
        {
          "user_email": "user@acme.com"
        }
      ]
    },
    "source": {
      "aggregation": "SUM",
      "display": "x",
      "name": "x"
    },
    "threshold": {
      "value": {
        "double_value": 1.25
      }
    }
  },
  "id": "fe25e731-92f2-4838-9fb2-1ca364320a3d",
  "lifecycle_state": "ACTIVE",
  "owner_user_name": "user@acme.com",
  "parent_path": "/Users/user@acme.com",
  "query_text": "SELECT 2 as x",
  "schedule": {
    "pause_status": "UNPAUSED",
    "quartz_cron_schedule": "0 0 10 * * ?",
    "timezone_id": "UTC"
  },
  "update_time": "2019-08-24T14:15:22Z",
  "warehouse_id": "a7066a8ef796be84"
}
```