tengqm commented on code in PR #5840: URL: https://github.com/apache/gravitino/pull/5840#discussion_r1881413531
########## docs/cli.md: ########## @@ -152,710 +163,464 @@ keytabFile=file.keytab ### Potentially unsafe operations -For operations that delete data or rename a metalake the user with be prompted to make sure they wish to run this command. The `--force` option can be specified to override this behaviour. +For operations that delete data or rename a metalake, the users will be prompted to +make sure they wish to run this command. +The `--force` option can be specified to override this behaviour. ### Manage metadata All the commands are performed by using the [Java API](api/java-api) internally. -### Display help +### Show help -To display help on command usage: +To view the help on command usage: ```bash gcli --help ``` -### Display client version +### Show version -To display the client version: +`gcli --version` +: Show the client version. -```bash -gcli --version -``` +`gcli --server` +: Show the server version. -### Display server version +:::note +**Client/server version mismatch** -To display the server version: +If the client and server are running different versions of the Gravitino software, +you may need to ignore the client/server version check for the command to be run. +This can be done in several ways: -```bash -gcli --server -``` - -### Client/server version mismatch - -If the client and server are running different versions of the Gravitino software then you may need to ignore the client/server version check for the command to run. This can be done in several ways: - -1. Passed in on the command line via the `--ignore` parameter. -2. Set via the `GRAVITINO_IGNORE` environment variable. -3. Stored in the Gravitino CLI configuration file. +1. Specify the `--ignore` argument in the command line. +1. Set the `GRAVITINO_IGNORE` environment variable. +1. Save it in the Gravitino CLI configuration file. +::: ### Multiple properties For commands that accept multiple properties they can be specified in a couple of different ways: -1. gcli --properties n1=v1,n2=v2,n3=v3 - -2. gcli --properties n1=v1 n2=v2 n3=v3 - -3. gcli --properties n1=v1 --properties n2=v2 --properties n3=v3 +1. `gcli --properties n1=v1,n2=v2,n3=v3` +2. `gcli --properties n1=v1 n2=v2 n3=v3` +3. `gcli --properties n1=v1 --properties n2=v2 --properties n3=v3` ### Setting properties and tags - Different options are needed to add a tag and set a property of a tag with `gcli tag set`. To add a - tag, specify the tag (via --tag) and the entity to tag (via --name). To set the property of a tag - (via --tag) you need to specify the property (via --property) and value (via --value) you want to - set. +Different options are needed to add a tag or to set a property for a tag using `gcli tag set`. +To add a tag, specify the tag (via `--tag`) and the entity to tag (via `--name`). +To set the property of a tag (via `--tag`) you need to specify the property (via `--property`) +and value (via `--value`) you want to set. - To delete a tag, again, you need to specify the tag and entity, to remove a tag's property you need - to select the tag and property. +To delete a tag, again, you need to specify the tag and the entity; to remove a tag's property, +you need to select the tag and property. -### CLI commands +## Command examples -Please set the metalake in the Gravitino configuration file or the environment variable before running any of these commands. +Please set the metalake in the Gravitino configuration file or the environment variable before +running any of these commands. ### Metalake commands -#### Show all metalakes +`gcli metalake create --metalake <name> --comment <comment>` +: Create a metalake. -```bash -gcli metalake list -``` +`gcli metalake properties` +: Show the properties for a metalake. -#### Show a metalake details +`gcli metalake delete` +: Delete a metalake. -```bash -gcli metalake details -``` +`gcli metalake list` +: List all metalakes -#### Show a metalake audit information +`gcli metalake details` +: Check the details of a specific a metalake. -```bash -gcli metalake details --audit -``` - -#### Create a metalake - -```bash -gcli metalake create --metalake my_metalake --comment "This is my metalake" -``` - -#### Delete a metalake - -```bash -gcli metalake delete -``` +`gcli metalake details --audit` +: Show the audit information for a metalake -#### Rename a metalake +`gcli metalake update --rename <new-name>` +: Rename a metalake -```bash -gcli metalake update --rename demo -``` +`gcli metalake update --comment "<new comment>"` +: Update the comment for a metalake -#### Update a metalake's comment +`gcli metalake set --property <property> --value <value>` +: Set the property for a metalake. -```bash -gcli metalake update --comment "new comment" -``` - -#### Display a metalake's properties - -```bash -gcli metalake properties -``` - -#### Set a metalake's property - -```bash -gcli metalake set --property test --value value -``` - -#### Remove a metalake's property - -```bash -gcli metalake remove --property test -``` +`gcli metalake remove --property <name>` +: Remove the specified property from a metalake. ### Catalog commands -#### Show all catalogs in a metalake - -```bash -gcli catalog list -``` - -#### Show a catalog details +`gcli catalog list` +: Show all catalogs in a metalake -```bash -gcli catalog details --name catalog_postgres -``` +`gcli catalog details --name <name>` +: Show a catalog details -#### Show a catalog audit information - -```bash -gcli catalog details --name catalog_postgres --audit -``` +`gcli catalog details --name <name> --audit` +: Show a catalog audit information #### Creating a catalog -The type of catalog to be created is specified by the `--provider` option. Different catalogs require different properties, for example, a Hive catalog requires a metastore-uri property. +The type of catalog to be created is specified by the `--provider` option. -##### Create a Hive catalog +`gcli catalog create --provider hive --name <name> --properties <property key-value pairs>` +: Create a catalog. -```bash -gcli catalog create --name hive --provider hive --properties metastore.uris=thrift://hive-host:9083 -``` +Different catalogs require different properties. +For example, a Hive catalog requires a `--metastore-uris` property. + +- For a Hive cata log, you need to specify the `metastore.uris` property. For example: -##### Create an Iceberg catalog + `metastore.uris=thrift://hive-host:9083` -```bash -gcli catalog create -name iceberg --provider iceberg --properties uri=thrift://hive-host:9083,catalog-backend=hive,warehouse=hdfs://hdfs-host:9000/user/iceberg/warehouse -``` +- For an Icebeg catalog, you need to specify the `uri`property. For example: -##### Create a MySQL catalog + `uri=thrift://hive-host:9083,catalog-backend=hive,warehouse=hdfs://hdfs-host:9000/user/iceberg/warehouse` -```bash -gcli catalog create -name mysql --provider mysql --properties jdbc-url=jdbc:mysql://mysql-host:3306?useSSL=false,jdbc-user=user,jdbc-password=password,jdbc-driver=com.mysql.cj.jdbc.Driver -``` +- For a MySQL Postgres catalog, you need to specify the `jdbc-url`, `jdbc-user`, `jdbc-password`, + `jdbc-driver` property. For example: -##### Create a Postgres catalog + `jdbc-url=jdbc:mysql://mysql-host:3306?useSSL=false,jdbc-user=user,jdbc-password=password,jdbc-driver=com.mysql.cj.jdbc.Driver` + +- For a Postgres catalog, you need to specify the `jdbc-url`, `jdbc-user`, `jdbc-password`, + `jdbc-driver`, `db` property. For example: -```bash -gcli catalog create -name postgres --provider postgres --properties jdbc-url=jdbc:postgresql://postgresql-host/mydb,jdbc-user=user,jdbc-password=password,jdbc-database=db,jdbc-driver=org.postgresql.Driver -``` + `jdbc-url=jdbc:postgresql://postgresql-host/mydb,jdbc-user=user,jdbc-password=password,jdbc-database=db,jdbc-driver=org.postgresql.Driver` -##### Create a Kafka catalog +- For a Kafka catalog, you need to specify the `boostrap.servers` property. For example: -```bash -gcli catalog create --name kafka --provider kafka --properties bootstrap.servers=127.0.0.1:9092,127.0.0.2:9092 -``` + `bootstrap.servers=127.0.0.1:9092,127.0.0.2:9092` -##### Create a Doris catalog +- For a Doris catalog, you need to specify the `jdbc-driver`, `jdbc-url`, `jdbc-user`, `jdb-password` property. + For example: -```bash -gcli catalog create --name doris --provider doris --properties jdbc-url=jdbc:mysql://localhost:9030,jdbc-driver=com.mysql.jdbc.Driver,jdbc-user=admin,jdbc-password=password -``` + `jdbc-url=jdbc:mysql://localhost:9030,jdbc-driver=com.mysql.jdbc.Driver,jdbc-user=admin,jdbc-password=password` -##### Create a Paimon catalog +- For a Paimon catalog, you need to specify the `catalog-backend`, `uri`, `authentication.type` properties. + For example: -```bash -gcli catalog create --name paimon --provider paimon --properties catalog-backend=jdbc,uri=jdbc:mysql://127.0.0.1:3306/metastore_db,authentication.type=simple -``` + `catalog-backend=jdbc,uri=jdbc:mysql://127.0.0.1:3306/metastore_db,authentication.type=simple` -#### Create a Hudi catalog +- For a Hudi catalog, you need to specify the `catalog-backend`, `uri` properties. For example: -```bash -gcli catalog create --name hudi --provider hudi --properties catalog-backend=hms,uri=thrift://127.0.0.1:9083 -``` + `catalog-backend=hms,uri=thrift://127.0.0.1:9083` -#### Create an Oceanbase catalog +- For an Oceanbase catalog, you need to specify the `jdbc-driver`, `jdbc-url`, `jdbc-user`, and + `jdbc-password` properties. For example: -```bash -gcli catalog create --name oceanbase --provider oceanbase --properties jdbc-url=jdbc:mysql://localhost:2881,jdbc-driver=com.mysql.jdbc.Driver,jdbc-user=admin,jdbc-password=password -``` + `jdbc-url=jdbc:mysql://localhost:2881,jdbc-driver=com.mysql.jdbc.Driver,jdbc-user=admin,jdbc-password=password` -#### Delete a catalog +`gcli catalog delete --name <name>` +: Delete a catalog. -```bash -gcli catalog delete --name hive -``` - -#### Rename a catalog - -```bash -gcli catalog update --name catalog_mysql --rename mysql -``` - -#### Change a catalog comment - -```bash -gcli catalog update --name catalog_mysql --comment "new comment" -``` +`gcli catalog update --name <old-name> --rename <new-name>` +:Rename a catalog. -#### Display a catalog's properties +`gcli catalog update --name <name> --comment "<new comment>"` +: Change the comment for a catalog. -```bash -gcli catalog properties --name catalog_mysql -``` - -#### Set a catalog's property +`gcli catalog properties --name <name>` +: List the properties for a catalog. -```bash -gcli catalog set --name catalog_mysql --property test --value value -``` +`gcli catalog set --name <name> --property <property> --value <value>` +: Set a property for a catalog. -#### Remove a catalog's property - -```bash -gcli catalog remove --name catalog_mysql --property test -``` +`gcli catalog remove --name <name> --property <property>` +: Remove a property from a catalog. ### Schema commands -#### Show all schemas in a catalog - -```bash -gcli schema list --name catalog_postgres -``` - -#### Show schema details - -```bash -gcli schema details --name catalog_postgres.hr -``` - -#### Show schema audit information - -```bash -gcli schema details --name catalog_postgres.hr --audit -``` +`gcli schema create --name <schema>` +: Create a schema. -#### Create a schema +`gcli schema properties --name <schema> -i` +: Display the properties about a schema. -```bash -gcli schema create --name catalog_postgres.new_db -``` +`gcli schema list --name <catalog>` +: List all schemas in the specified catalog. -#### Display schema properties +`gcli schema details --name <schema>` +: Show the details about schemas -```bash -gcli schema properties --name catalog_postgres.hr -i -``` +`gcli schema details --name <schema> --audit` +: Show schema audit information -Setting and removing schema properties is not currently supported by the Java API or the Gravitino CLI. +:::note +Setting and removing schema properties is currently not supported in the Java API +or the Gravitino CLI. +::: ### Table commands -When creating a table the columns are specified in CSV file specifying the name of the column, the datatype, a comment, true or false if the column is nullable, true or false if the column is auto incremented, a default value and a default type. Not all of the columns need to be specifed just the name and datatype columns. If not specified comment default to null, nullability to true and auto increment to false. If only the default value is specified it defaults to the same data type as the column. +When creating a table, the columns are specified in a CSV file containing the properties +of each column, including + +- the column name (required) +- the data type (required) +- the comment string which defaults to null +- a string format boolean indicating whether the column can be null (default=true) +- a string format boolean indicating whether the column is auto-incremented (default=false) +- the default value +- the default data type, defaults to the column data type if a default value is specified. Review Comment: > If you specify a default value, then the default column type defaults to the column data type Yes. That is exactly what I captured from your clarification. Maybe you can provide a clearer description? BTW, this logic is ugly and needs some rethinking. Are we sure we want to do this? You can see I have had a difficult time to understand this logic. The same difficulty will be a pain for other users/developers. If we have a logic that is so difficult to explain, I'd suggest we drop this smart hack. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: commits-unsubscr...@gravitino.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
