# **ALTER STAGE**

## **Grammar Description**

`ALTER STAGE` is used to modify the attributes used to modify an existing stage.

:::{note}
`ALTER STAGE` can only modify one parameter at a time. Therefore, if you need to update multiple parameters at the same time, such as `URL` and `COMMENT`, you need to execute the `ALTER STAGE` statement multiple times, modifying one parameter at a time.
:::
## **Grammar Structure**

```sql
ALTER STAGE [ IF EXISTS ] { stage_name } SET
   { StageParams }
   [ COMMENT = '<string_literal>' ]

StageParams (for Amazon S3):
URL = "s3://<bucket>[/<path>/]" CREDENTIALS = {"AWS_KEY_ID"='<string>', "AWS_SECRET_KEY"='<string>', "AWS_ROLE"='<string>', "AWS_TOKEN"='<string>', "AWS_REGION"='<string>', "COMPRESSION"='<string>', 'PROVIDER'='<string>', 'ENDPOINT'='<string>'}

StageParams (for File System):
URL= 'file://[/path/]'

StageParams (for sub-stage):
URL= "stage://<stagename>[/path/]"
```

## **Grammar Explanation**

- `IF NOT EXISTS`: Optional parameter to check whether the Stage of the same name already exists when creating a Stage, and avoid repeated creation.

- `stage_name`: The name of the Stage to be created.

- `StageParams (for MinIO/Amazon S3): Used to specify the configuration parameters for Stages whose objects are stored as MinIO or S3.

    - `URL`: Specify the file path or directory in S3 storage
    - `CREDENTIALS`: This is a JSON object that contains the credential information required to connect to the object storage service.

         + `access_key_id`: The access key ID used for authentication.
         + `secret_access_key`: The key associated with the access key ID.
         + `aws_role`: Non-required, if an IAM role is used, it is used to specify the role name. Roles can be configured on AWS to assign different permissions.
         + `aws_token`: Non-required, security token for temporary access to AWS services.
         + `aws_region`: Specifies the AWS Region where Amazon S3 storage resides.
         + `compression`: Non-required, specify the compression type of the file.
         + `provider`: Specify cloud storage provider.
         + `endpint`: Specifies a service that connects to custom or third-party S3 API compatible.

- `StageParams (for File System)`: Used to specify the configuration parameters of the Stage stored in the file system.

    - `URL`: Specifies the file path or directory in the file store.

- `StageParams (for sub-stage)`: Configuration parameters for sub-stage.

    - `URL`: Specifies the file path or directory in the file store.

- `COMMENT`: Comment.

## **Example**

```text
create stage stage_fs url = 'file:///Users/admin/test' comment='this is a stage';

mysql> select * from mo_catalog.mo_stages where stage_name='stage_fs';
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| stage_id | stage_name | url | stage_credentials | stage_status | created_time | comment |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| 1 | stage_fs | file:///Users/admin/test | | disabled | 2024-10-09 03:46:00 | this is a stage |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1 row in set (0.00 sec)

alter stage stage_fs set url = 'file:///Users/admin/test1';
alter stage stage_fs set comment='stage_fs has been changed';

mysql> select * from mo_catalog.mo_stages where stage_name='stage_fs';
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| stage_id | stage_name | url | stage_credentials | stage_status | created_time | comment |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| 1 | stage_fs | file:///Users/admin/test1 | | disabled | 2024-10-09 03:46:00 | stage_fs has been changed |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
1 row in set (0.00 sec)
```