This is an automated email from the ASF dual-hosted git repository.
lzljs3620320 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/paimon.git
The following commit(s) were added to refs/heads/master by this push:
new c70d9afd4b [doc] Add REST catalog doc (#5100)
c70d9afd4b is described below
commit c70d9afd4bcc1ba621e436f55b4fbd1357189a24
Author: jerry <[email protected]>
AuthorDate: Tue Feb 18 14:49:38 2025 +0800
[doc] Add REST catalog doc (#5100)
---
docs/README.md | 3 ++
docs/content/concepts/catalog.md | 6 ++-
docs/content/concepts/data-types.md | 2 +-
docs/content/concepts/rest-catalog.md | 88 ++++++++++++++++++++++++++++++++++
docs/content/concepts/spec/_index.md | 2 +-
docs/content/concepts/system-tables.md | 2 +-
docs/content/concepts/table-types.md | 2 +-
docs/static/img/rest-catalog.svg | 2 +
8 files changed, 102 insertions(+), 5 deletions(-)
diff --git a/docs/README.md b/docs/README.md
index de0a7d16b4..fb96248516 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,6 +10,9 @@ that you always have docs corresponding to your checked-out
version.
Make sure you have installed Hugo on your system.
Note: An extended version of Hugo <= 0.124.1 is required. you can Find this at
[Hugo](https://github.com/gohugoio/hugo/releases/tag/v0.124.1)
+```sh
+go install -tags extended,withdeploy github.com/gohugoio/[email protected]
+```
From this directory:
diff --git a/docs/content/concepts/catalog.md b/docs/content/concepts/catalog.md
index 9775113a6e..051df2e1cc 100644
--- a/docs/content/concepts/catalog.md
+++ b/docs/content/concepts/catalog.md
@@ -32,11 +32,12 @@ access the Paimon table.
## Catalogs
-Paimon catalogs currently support three types of metastores:
+Paimon catalogs currently support four types of metastores:
* `filesystem` metastore (default), which stores both metadata and table files
in filesystems.
* `hive` metastore, which additionally stores metadata in Hive metastore.
Users can directly access the tables from Hive.
* `jdbc` metastore, which additionally stores metadata in relational databases
such as MySQL, Postgres, etc.
+* `rest` metastore, which is designed to provide a lightweight way to access
any catalog backend from a single client.
## Filesystem Catalog
@@ -88,3 +89,6 @@ CREATE CATALOG my_jdbc WITH (
'warehouse' = 'hdfs:///path/to/warehouse'
);
```
+## REST Catalog
+By using the Paimon REST catalog, changes to the catalog will be directly
stored in a remote catalog server which exposed through REST API.
+See [Paimon REST Catalog]({{< ref "concepts/rest-catalog" >}}).
diff --git a/docs/content/concepts/data-types.md
b/docs/content/concepts/data-types.md
index d778c7c8f1..4bee2dba2f 100644
--- a/docs/content/concepts/data-types.md
+++ b/docs/content/concepts/data-types.md
@@ -1,6 +1,6 @@
---
title: "Data Types"
-weight: 7
+weight: 8
type: docs
aliases:
- /concepts/data-types.html
diff --git a/docs/content/concepts/rest-catalog.md
b/docs/content/concepts/rest-catalog.md
new file mode 100644
index 0000000000..4645d86418
--- /dev/null
+++ b/docs/content/concepts/rest-catalog.md
@@ -0,0 +1,88 @@
+---
+title: "RESTCatalog"
+weight: 5
+type: docs
+aliases:
+- /concepts/rest-catalog.html
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# RESTCatalog
+## Overview
+
+Paimon REST Catalog provides a lightweight implementation to access the
catalog service. Paimon could access the catalog service through a catalog
server which implements REST API.You can see all APIs in [REST
API](https://github.com/apache/paimon/blob/master/paimon-open-api/rest-catalog-open-api.yaml).
+
+{{< img src="/img/rest-catalog.svg">}}
+
+## Key Features
+
+1. User Defined Technology-Specific Logic Implementation
+ - All technology-specific logic within the catalog server.
+ - This ensures that the user can define logic that could be owned by the
user.
+2. Decoupled Architecture
+ - The REST Catalog interacts with the catalog server through a well-defined
REST API.
+ - This decoupling allows for independent evolution and scaling of the
catalog server and clients.
+3. Language Agnostic
+ - Developers can implement the catalog server in any programming language,
provided that it adheres to the specified REST API.
+ - This flexibility enables teams to utilize their existing tech stacks and
expertise.
+4. Support for Any Catalog Backend
+ - Paimon REST Catalog is designed to work with any catalog backend.
+ - As long as they implement the relevant APIs, they can seamlessly integrate
with Paimon REST Catalog.
+
+## Usage
+- Bear token
+```sql
+CREATE CATALOG `paimon-rest-catalog`
+WITH (
+'type' = 'paimon',
+'uri' = '<catalog server url>',
+'metastore' = 'rest',
+'token.provider' = 'bear'
+'token' = '<token>'
+);
+```
+- DLF ak
+```sql
+CREATE CATALOG `paimon-rest-catalog`
+WITH (
+'type' = 'paimon',
+'uri' = '<catalog server url>',
+'metastore' = 'rest',
+'token.provider' = 'dlf',
+'dlf.accessKeyId'='<accessKeyId>',
+'dlf.accessKeySecret'='<accessKeySecret>',
+);
+```
+- DLF token path
+```sql
+CREATE CATALOG `paimon-rest-catalog`
+WITH (
+'type' = 'paimon',
+'uri' = '<catalog server url>',
+'metastore' = 'rest',
+'token.provider' = 'dlf',
+'dlf.token-path' = '<token-path>'
+);
+```
+
+## Conclusion
+
+Paimon REST Catalog offers adaptable solution for accessing the catalog
service. According to [REST
API](https://github.com/apache/paimon/blob/master/paimon-open-api/rest-catalog-open-api.yaml)
is decoupled from the catalog service.
+Technology-specific Logic is encapsulated on the catalog server. At the same
time, the catalog server supports any backend and languages.
\ No newline at end of file
diff --git a/docs/content/concepts/spec/_index.md
b/docs/content/concepts/spec/_index.md
index cc148d6a8b..03bcd72234 100644
--- a/docs/content/concepts/spec/_index.md
+++ b/docs/content/concepts/spec/_index.md
@@ -1,7 +1,7 @@
---
title: Specification
bookCollapseSection: true
-weight: 8
+weight: 9
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
diff --git a/docs/content/concepts/system-tables.md
b/docs/content/concepts/system-tables.md
index aea72c000a..5385f7961f 100644
--- a/docs/content/concepts/system-tables.md
+++ b/docs/content/concepts/system-tables.md
@@ -1,6 +1,6 @@
---
title: "System Tables"
-weight: 6
+weight: 7
type: docs
aliases:
- /concepts/system-tables.html
diff --git a/docs/content/concepts/table-types.md
b/docs/content/concepts/table-types.md
index b5a1fafa3d..1a04096d5c 100644
--- a/docs/content/concepts/table-types.md
+++ b/docs/content/concepts/table-types.md
@@ -1,6 +1,6 @@
---
title: "Table Types"
-weight: 5
+weight: 6
type: docs
aliases:
- /concepts/table-types.html
diff --git a/docs/static/img/rest-catalog.svg b/docs/static/img/rest-catalog.svg
new file mode 100644
index 0000000000..629ee91a33
--- /dev/null
+++ b/docs/static/img/rest-catalog.svg
@@ -0,0 +1,2 @@
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg"; viewBox="0 0
366.587890625 494.02929687499994" width="366.587890625"
height="494.02929687499994"><!-- svg-source:excalidraw
--><metadata></metadata><defs><style class="style-fonts">
+ @font-face { font-family: Excalifont; src:
url(data:font/woff2;base64,d09GMgABAAAAAA5kAA4AAAAAGDgAAA4PAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGhYbhEwcNAZgAIEEEQgKogiZFQswAAE2AiQDXAQgBYMYByAbpBIjA3WBsYoi+4sE25j2QxehJBabNTuooR3005Yu/9eytcYwEK7JBTn1CFpmeCWI+rHf3j35qCU8iXo1S2aVZFaKT/eQKRkS0StveLr57+6SLnDIg+LAwNk1qbVven9fJkbs9hcABhgkCXjzuVlPWni/GyCElZNkkzNx5JuWv+hJO7QjSOJIbPWyJ6YDfOl/AP/+/n/7tTzrVbto3VB3sdIp7c9H7n+YPRaLMySTtJIIkUxoNJpqVkmc7qWQG7VBqbxk65hVzMJo1I+I8QgQB74IimDIACFADBUMMD19qblAeHp7
[...]
\ No newline at end of file
