justinmclean commented on code in PR #5840: URL: https://github.com/apache/gravitino/pull/5840#discussion_r1881019130
########## 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. + +Example CSV file: -Example CSV file ```text Name,Datatype,Comment,Nullable,AutoIncrement,DefaultValue,DefaultType name,String,person's name ID,Integer,unique id,false,true location,String,city they work in,false,false,Sydney,String ``` -#### Show all tables - -```bash -gcli table list --name catalog_postgres.hr -``` - -#### Show tables details - -```bash -gcli table details --name catalog_postgres.hr.departments -``` - -#### Show tables audit information - -```bash -gcli table details --name catalog_postgres.hr.departments --audit -``` - -#### Show tables distribution information -```bash -gcli table details --name catalog_postgres.hr.departments --distribution -``` - -#### Show tables partition information -```bash -gcli table details --name catalog_postgres.hr.departments --partition -``` - -#### Show tables sort order information -```bash -gcli table details --name catalog_postgres.hr.departments --sortorder -``` - -### Show table indexes +In the commands below, note that the table name is in the format +`<catalog>.<schema>.<table>`. -```bash -gcli table details --name catalog_mysql.db.iceberg_namespace_properties --index -``` +`gcli table create --name <table> --comment "<comment>" --columnfile <csv-file>` +: Create a table. Note that the table name is in the format `<catalog>.<schema>.<table>`. -#### Delete a table +`gcli table list --name <schema>` +: List all tables for a schema. -```bash -gcli table delete --name catalog_postgres.hr.salaries -``` +`gcli table details --name <table>` +: Show the details about a table. +`gcli table details --name <table> --audit` +: Show the audit information for a specified table. -#### Display a tables's properties +`gcli table details --name <table> --distribution` +: Show distribution information for a specified table. -```bash -gcli table properties --name catalog_postgres.hr.salaries -``` +`gcli table details --name <table> --partition` +: Show the partition information for a specified table. -#### Set a tables's property +`gcli table details --name <table> --sortorder` +: Show the sorting order for the table specified. -```bash -gcli table set --name catalog_postgres.hr.salaries --property test --value value -``` +`gcli table details --name <table> --index` +: Show the index information for the table specified. -#### Remove a tables's property +`gcli table delete --name <table>` +: Delete a table. -```bash -gcli table remove --name catalog_postgres.hr.salaries --property test -``` +`gcli table properties --name <table>` +: Show the properties for a specific table. -#### Create a table +`gcli table set --name <table> --property <property> --value <value>` +: Set a property for a specific table. -```bash -gcli table create --name catalog_postgres.hr.salaries --comment "comment" --columnfile ~/table.csv -``` +`gcli table remove --name <table> --property <property>` +: Remove the specified property from the specified table. ### User commands -#### Create a user - -```bash -gcli user create --user new_user -``` - -#### Show a user's details - -```bash -gcli user details --user new_user -``` - -#### List all users +`gcli user create --user <user>` +: Create a new user. -```bash -gcli user list -``` +`gcli user details --user <user>` +: Show the details about the specified user. -#### Delete a user +`gcli user delete --user <user>` +: Delete the specified user. -```bash -gcli user delete --user new_user -``` +`gcli user list` +: List all users ### Group commands -#### Create a group +`gcli group create --group <group>` +: Create a group. -```bash -gcli group create --group new_group -``` +`gcli group details --group <group>` +: Display the details about a group. -#### Display a group's details +`gcli group list` +: List all groups. -```bash -gcli group details --group new_group -``` - -#### List all groups - -```bash -gcli group list -``` - -#### Delete a group - -```bash -gcli group delete --group new_group -``` +`gcli group delete --group <group>` +: Delete a group. ### Tag commands -#### Display a tag's details +`gcli tag create --tag <tag-A> <tagB>` +: Create tags. -```bash -gcli tag details --tag tagA -``` - -#### Create tags +`gcli tag details --tag <tag>` +: Display the details about a tag. -```bash - gcli tag create --tag tagA tagB - ``` +`gcli tag list` +: List all tags. -#### List all tag - -```bash -gcli tag list -``` - -#### Delete tags - -```bash -gcli tag delete --tag tagA tagB -``` +`gcli tag delete --tag <tag-A> <tag-B>` +: Delete tags. -#### Add tags to an entity +`gcli tag set --name <entity> --tag tagA tagB` +: Add tags to an entity. The type of the entity is implied by its name. -```bash -gcli tag set --name catalog_postgres.hr --tag tagA tagB -``` +`gcli tag remove --name <entity> --tag <tagA> <tagB>` +: Remove tags from an entity. The type of the entity is implied by its name. -#### Remove tags from an entity +`gcli tag remove --name <entity>` +: Remove all tags from an entity. The type of the entity is implied by its name. -```bash -gcli tag remove --name catalog_postgres.hr --tag tagA tagB -``` +`gcli tag list --name <entity>` +: List all tags on an entity -#### Remove all tags from an entity +`gcli tag properties --tag <tag>` +: List the properties of a tag. -```bash -gcli tag remove --name catalog_postgres.hr -``` +`gcli tag set --tag <tag> --property <property> --value <value>` +: Set a property for a tag. -#### List all tags on an entity +`gcli tag remove --tag <tag> --property <property>` +: Delete a property from a tag. -```bash -gcli tag list --name catalog_postgres.hr -``` +`gcli tag update --tag <tag> --rename <new-name>` +: Rename a tag. -#### List the properties of a tag - -```bash -gcli tag properties --tag tagA -``` - -#### Set a properties of a tag - -```bash -gcli tag set --tag tagA --property test --value value -``` - -#### Delete a property of a tag - -```bash -gcli tag remove --tag tagA --property test -``` - -#### Rename a tag - -```bash -gcli tag update --tag tagA --rename newTag -``` - -#### Update a tag's comment - -```bash -gcli tag update --tag tagA --comment "new comment" -``` +`gcli tag update --tag <tag> --comment "<new-comment>"` +: Update the comment for a tag. ### Owner commands -#### List an owner +`gcli catalog details --name <catalog> --owner` +: Show the details about an owner for a catalog. -```bash -gcli catalog details --owner --name postgres -``` +`gcli catalog set --name <catalog> --owner --user <user>` +: Set the specified user as the owner for the specified catalog. Review Comment: "or the specified catalog." -> "of the specified catalog." -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
