apache / gravitino

World's most powerful open data catalog for building a high-performance, geo-distributed and federated metadata lake.
https://gravitino.apache.org
Apache License 2.0
1.1k stars 344 forks source link

[Improvement] Sample command in CLI document may report error #5541

Open shaofengshi opened 1 week ago

shaofengshi commented 1 week ago

What would you like to be improved?

In the "cli.md" document, there are some sample commands to illustrate how to use the CLI. While if user just copy & paste them, they may get error as some name conflicts. For example, when run:

"gcli catalog update --name catalog_mysql --rename mysql"

If he already run the commands prior to this, the name "mysql" is aready been occupied. As @justinmclean suggested, this should be recorded and improved later.

How should we improve?

The document can improved to avoid such conflict.

justinmclean commented 1 week ago

I don't think there is any simple solution to this: a) If they are not running the playground, they will likely get an error (as the catalog may not exist). Other commands before this would have also failed. b) If they have run the other catalog create command, this will also fail as they would be trying to create a catalog that already exists. c) Even if we change it to a new unused catalog name, then commands after this will fail as that catalog doesn't exist anymore. d) If we change the later commands, they will fail if a user doesn't rename the catalog.

As far as I can see, the commands can potentially fail no matter what solution we pick.

Does it matter if a rename command fails with reason if it is there just to show the syntax? I think we prefer one command failing to multiple commands failing?

justinmclean commented 1 week ago

@shaofengshi Any suggestions on the best path?