This is an automated email from the ASF dual-hosted git repository.
jshao pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/main by this push:
new 07dd3a07d [MINOR] improve(doc): Straight-forward improvements (#4997)
07dd3a07d is described below
commit 07dd3a07dc738b29d51f5f387e3e82923e85ca3b
Author: Jun Ma <[email protected]>
AuthorDate: Thu Sep 26 10:33:12 2024 +0800
[MINOR] improve(doc): Straight-forward improvements (#4997)
### What changes were proposed in this pull request?
This PR addresses the following improvements to the Manage Metalake
topic from a tech writing perspective.
1. Move term-specific content into the Glossary topic for the single
source of truth.
2. Remove the unnecessary heading 2 to make the TOC more compact.
3. Align the descriptions and examples among actions and methods. For
example, add options for altering a metalake in Python and remove "Java"
from the client descriptions.
### Why are the changes needed?
To improve the doc quality in terms of information architecture, content
mapping, accuracy, and consistency.
### Does this PR introduce _any_ user-facing change?
Yes, this PR introduces user-facing changes.
### How was this patch tested?
I've previewed the changes in .HTML format locally and the result looks
good.
If there is any required process or command to test it in a staging env,
feel free to let me know.
---
docs/glossary.md | 2 +-
docs/manage-metalake-using-gravitino.md | 80 ++++++++++++++++-----------------
2 files changed, 40 insertions(+), 42 deletions(-)
diff --git a/docs/glossary.md b/docs/glossary.md
index 22002168a..be06940c1 100644
--- a/docs/glossary.md
+++ b/docs/glossary.md
@@ -254,7 +254,7 @@ license: "This software is licensed under the Apache
License version 2."
## Metalake
-- The top-level container for metadata.
+- The top-level container for metadata. Typically, a metalake is a tenant-like
mapping to an organization or a company. All the catalogs, users, and roles are
under one metalake.
## Metastore
diff --git a/docs/manage-metalake-using-gravitino.md
b/docs/manage-metalake-using-gravitino.md
index 4dc2b4dc4..0aa464fe9 100644
--- a/docs/manage-metalake-using-gravitino.md
+++ b/docs/manage-metalake-using-gravitino.md
@@ -9,20 +9,18 @@ license: This software is licensed under the Apache License
version 2.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-This page introduces how to manage metalake by Apache Gravitino. Metalake is a
tenant-like concept in
-Gravitino, all the catalogs, users and roles are under a metalake. Typically,
a metalake is
-mapping to a organization or a company.
+This page introduces how to create, modify, view, and delete
[metalakes](./glossary.md#metalake) by using Gravitino.
-Through Gravitino, you can create, edit, and delete metalake. This page
includes the following
-contents:
+## Prerequsites
-Assuming Gravitino has just started, and the host and port is
[http://localhost:8090](http://localhost:8090).
+You have installed and launched Gravitino. For more details, see [Get
started](./getting-started.md).
-## Metalake operations
+Let's say, the access is [http://localhost:8090](http://localhost:8090).
-### Create a metalake
+## Create a metalake
+
+To create a metalake, you can send a `POST` request to the `/api/metalakes`
endpoint or use the Gravitino Admin client.
-You can create a metalake by sending a `POST` request to the `/api/metalakes`
endpoint or just use the Gravitino Admin Java client.
The following is an example of creating a metalake:
<Tabs groupId="language" queryString>
@@ -30,7 +28,7 @@ The following is an example of creating a metalake:
```shell
curl -X POST -H "Accept: application/vnd.gravitino.v1+json" \
--H "Content-Type: application/json" -d
'{"name":"metalake","comment":"comment","properties":{}}' \
+-H "Content-Type: application/json" -d '{"name":"metalake","comment":"This is
a new metalake","properties":{}}' \
http://localhost:8090/api/metalakes
```
@@ -62,9 +60,11 @@ gravitino_admin_client.create_metalake(name="metalake",
</TabItem>
</Tabs>
-### Load a metalake
+## Load a metalake
+
+To load a metalake, you can send a `GET` request to the
`/api/metalakes/{metalake_name}` endpoint or use the Gravitino Admin client.
-You can load a metalake by sending a `GET` request to the
`/api/metalakes/{metalake_name}` endpoint or just use the Gravitino Java
client. The following is an example of loading a metalake:
+The following is an example of loading a metalake:
<Tabs groupId="language" queryString>
<TabItem value="shell" label="Shell">
@@ -94,9 +94,11 @@ gravitino_admin_client.load_metalake("metalake")
</TabItem>
</Tabs>
-### Alter a metalake
+## Alter a metalake
-You can modify a metalake by sending a `PUT` request to the
`/api/metalakes/{metalake_name}` endpoint or just use the Gravitino Java
client. The following is an example of altering a metalake:
+To alter a metalake, you can send a `PUT` request to the
`/api/metalakes/{metalake_name}` endpoint or use the Gravitino Admin client.
+
+The following is an example of renaming a metalake:
<Tabs groupId="language" queryString>
<TabItem value="shell" label="Shell">
@@ -107,15 +109,10 @@ curl -X PUT -H "Accept:
application/vnd.gravitino.v1+json" \
"updates": [
{
"@type": "rename",
- "newName": "metalake"
- },
- {
- "@type": "setProperty",
- "property": "key2",
- "value": "value2"
+ "newName": "metalake_renamed"
}
]
-}' http://localhost:8090/api/metalakes/new_metalake
+}' http://localhost:8090/api/metalakes/metalake
```
</TabItem>
@@ -124,8 +121,8 @@ curl -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
```java
// ...
GravitinoMetalake renamed = gravitinoAdminClient.alterMetalake(
- NameIdentifier.of("new_metalake"),
- MetalakeChange.rename("new_metalake_renamed")
+ NameIdentifier.of("metalake"),
+ MetalakeChange.rename("metalake_renamed")
);
// ...
```
@@ -135,32 +132,31 @@ GravitinoMetalake renamed =
gravitinoAdminClient.alterMetalake(
```python
changes = (
- MetalakeChange.rename("metalake_new_name"),
- MetalakeChange.update_comment("metalake_new_comment"),
- MetalakeChange.remove_property("metalake_properties_key1"),
- MetalakeChange.set_property("metalake_properties_key2",
"metalake_properties_new_value"),
+ MetalakeChange.rename("metalake_renamed"),
)
-metalake = gravitino_admin_client.alter_metalake("metalake_name", *changes)
+metalake = gravitino_admin_client.alter_metalake("metalake", *changes)
```
</TabItem>
</Tabs>
-Currently, Gravitino supports the following changes to a metalake:
+The following table outlines the supported modifications that you can make to
a metalake:
+
+| Supported modification | JSON
| Java | Python
|
+|------------------------|--------------------------------------------------------------|-------------------------------------------------|-------------------------------------------------------------------------------------------|
+| Rename metalake | `{"@type":"rename","newName":"metalake_renamed"}`
| `MetalakeChange.rename("metalake_renamed")` |
`MetalakeChange.rename("metalake_renamed")`
|
+| Update comment |
`{"@type":"updateComment","newComment":"new_comment"}` |
`MetalakeChange.updateComment("new_comment")` |
`MetalakeChange.update_comment("new_comment")`
|
+| Set property |
`{"@type":"setProperty","property":"key1","value":"value1"}` |
`MetalakeChange.setProperty("key1", "value1")` |
`MetalakeChange.set_property("key1", "value1")` |
+| Remove property | `{"@type":"removeProperty","property":"key1"}`
| `MetalakeChange.removeProperty("key1")` |
`MetalakeChange.remove_property("key1")` |
-| Supported modification | JSON
| Java |
-|------------------------|--------------------------------------------------------------|-------------------------------------------------|
-| Rename metalake | `{"@type":"rename","newName":"metalake_renamed"}`
| `MetalakeChange.rename("metalake_renamed")` |
-| Update comment |
`{"@type":"updateComment","newComment":"new_comment"}` |
`MetalakeChange.updateComment("new_comment")` |
-| Set a property |
`{"@type":"setProperty","property":"key1","value":"value1"}` |
`MetalakeChange.setProperty("key1", "value1")` |
-| Remove a property | `{"@type":"removeProperty","property":"key1"}`
| `MetalakeChange.removeProperty("key1")` |
+## Drop a metalake
-### Drop a metalake
+To drop a metalake, you can send a `DELETE` request to the
`/api/metalakes/{metalake_name}` endpoint or use the Gravitino Admin client.
-You can remove a metalake by sending a `DELETE` request to the
`/api/metalakes/{metalake_name}` endpoint or just use the Gravitino Java
client. The following is an example of dropping a metalake:
+The following is an example of dropping a metalake:
<Tabs groupId="language" queryString>
<TabItem value="shell" label="Shell">
@@ -190,13 +186,15 @@ gravitino_admin_client.drop_metalake("metalake")
</Tabs>
:::note
-Current Gravitino doesn't support dropping a metalake in cascade mode, which
means all the
-catalogs, schemas and tables under the metalake need to be removed before
dropping the metalake.
+Dropping a metalake in cascade mode is not allowed. That is, all the
+catalogs, schemas, and tables under a metalake must be removed before you can
drop the metalake.
:::
-### List all metalakes
+## List all metalakes
+
+To view all your metalakes, you can send a `GET` request to the
`/api/metalakes` endpoint or use the Gravitino Admin client.
-You can list metalakes by sending a `GET` request to the `/api/metalakes`
endpoint or just use the Gravitino Java client. The following is an example of
listing all the metalake names:
+The following is an example of listing all metalakes:
<Tabs groupId="language" queryString>
<TabItem value="shell" label="Shell">
