You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by "hackergin (via GitHub)" <gi...@apache.org> on 2023/08/01 05:24:35 UTC

[GitHub] [flink] hackergin opened a new pull request, #23110: [FLINK-32653][docs] Add doc for catalog store

hackergin opened a new pull request, #23110:
URL: https://github.com/apache/flink/pull/23110

   <!--
   *Thank you very much for contributing to Apache Flink - we are happy that you want to help us improve Flink. To help the community review your contribution in the best possible way, please go through the checklist below, which will get the contribution into a shape in which it can be best reviewed.*
   
   *Please understand that we do not do this to make contributions to Flink a hassle. In order to uphold a high standard of quality for code contributions, while at the same time managing a large number of contributions, we need contributors to prepare the contributions well, and give reviewers enough contextual information for the review. Please also understand that contributions that do not follow this guide will take longer to review and thus typically be picked up with lower priority by the community.*
   
   ## Contribution Checklist
   
     - Make sure that the pull request corresponds to a [JIRA issue](https://issues.apache.org/jira/projects/FLINK/issues). Exceptions are made for typos in JavaDoc or documentation files, which need no JIRA issue.
     
     - Name the pull request in the form "[FLINK-XXXX] [component] Title of the pull request", where *FLINK-XXXX* should be replaced by the actual issue number. Skip *component* if you are unsure about which is the best component.
     Typo fixes that have no associated JIRA issue should be named following this pattern: `[hotfix] [docs] Fix typo in event time introduction` or `[hotfix] [javadocs] Expand JavaDoc for PuncuatedWatermarkGenerator`.
   
     - Fill out the template below to describe the changes contributed by the pull request. That will give reviewers the context they need to do the review.
     
     - Make sure that the change passes the automated tests, i.e., `mvn clean verify` passes. You can set up Azure Pipelines CI to do that following [this guide](https://cwiki.apache.org/confluence/display/FLINK/Azure+Pipelines#AzurePipelines-Tutorial:SettingupAzurePipelinesforaforkoftheFlinkrepository).
   
     - Each pull request should address only one issue, not mix up code from multiple issues.
     
     - Each commit in the pull request has a meaningful commit message (including the JIRA id)
   
     - Once all items of the checklist are addressed, remove the above text and this checklist, leaving only the filled out template below.
   
   
   **(The sections below can be removed for hotfixes of typos)**
   -->
   
   ## What is the purpose of the change
   
   *Add doc for catalog store*
   
   
   ## Brief change log
   
   * Add doc for catalog store* 
   
   
   ## Verifying this change
   
   This change is a trivial rework / code cleanup without any test coverage.
   
   ## Does this pull request potentially affect one of the following parts:
   
     - Dependencies (does it add or upgrade a dependency): (no)
     - The public API, i.e., is any changed class annotated with `@Public(Evolving)`: (no)
     - The serializers: (no)
     - The runtime per-record code paths (performance sensitive): (no)
     - Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Kubernetes/Yarn, ZooKeeper: (no)
     - The S3 file system connector: (no)
   
   ## Documentation
   
     - Does this pull request introduce a new feature? (no)
     - If yes, how is the feature documented? ( docs)
   


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] hackergin commented on a diff in pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "hackergin (via GitHub)" <gi...@apache.org>.
hackergin commented on code in PR #23110:
URL: https://github.com/apache/flink/pull/23110#discussion_r1293157380


##########
docs/content/docs/dev/table/catalogs.md:
##########
@@ -738,3 +738,192 @@ Flink SQL> show tables;
 ```
 {{< /tab >}}
 {{< /tabs >}}
+
+## Catalog Store
+
+Catalog Store is used to store the configuration of catalogs. When using Catalog Store, the configurations
+of catalogs created in the session will be persisted in the corresponding external system of Catalog Store.

Review Comment:
   I think `session` represent a execution environment, not only in sql-gateway.  Such as session is used in bellow doc. 
   
   https://github.com/apache/flink/blob/fc2b5d8f53a41695117f6eaf4c798cc183cf1e36/docs/content/docs/dev/table/catalogs.md?plain=1#L45
   
   https://github.com/apache/flink/blob/fc2b5d8f53a41695117f6eaf4c798cc183cf1e36/docs/content/docs/dev/table/timezone.md?plain=1#L29



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] FangYongs commented on a diff in pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "FangYongs (via GitHub)" <gi...@apache.org>.
FangYongs commented on code in PR #23110:
URL: https://github.com/apache/flink/pull/23110#discussion_r1291151577


##########
docs/content/docs/dev/table/catalogs.md:
##########
@@ -738,3 +738,192 @@ Flink SQL> show tables;
 ```
 {{< /tab >}}
 {{< /tabs >}}
+
+## Catalog Store
+
+Catalog Store is used to store the configuration of catalogs. When using Catalog Store, the configurations
+of catalogs created in the session will be persisted in the corresponding external system of Catalog Store.
+Even if the session is reconstructed, previously created catalogs can still be retrieved from Catalog Store.
+
+### Configure Catalog Store
+Users can configure the Catalog Store in different ways, one is to use the Table API, and another is to use YAML configuration.
+
+{{< tabs "9bb8994c-7c07-4c49-f5b8-f4ae3548ead4" >}}
+{{< tab "Java/Scala" >}}
+```java
+// Register a catalog store using catalog store instance.
+
+// Initialize a catalog Store
+CatalogStore catalogStore = new FileCatalogStore("file://path/to/catalog/store/");
+
+// set up the catalog store
+final EnvironmentSettings settings =
+        EnvironmentSettings.newInstance().inBatchMode()
+        .withCatalogStore(catalogStore)
+        .build();
+
+final TableEnvironment tableEnv = TableEnvironment.create(settings);
+
+// Register a catalog store using configuration.
+        
+// Set up configuration
+Configuration configuration = new Configuration();
+configuration.set("table.catalog-store.kind", "file");
+configuration.set("table.catalog-store.file.path", "file://path/to/catalog/store/");
+// set up the configuration.
+final EnvironmentSettings settings =
+        EnvironmentSettings.newInstance().inBatchMode()
+        .withConfiguration(configuration)
+        .build();
+
+final TableEnvironment tableEnv = TableEnvironment.create(settings);
+```
+{{< /tab >}}
+{{< tab "SQL Gateway" >}}
+
+In SQL Gateway, it is recommended to configure the settings in a yaml file so that all sessions can automatically 
+use the pre-created Catalog. Usually, you need to configure the kind of Catalog Store and other
+required parameters for the Catalog Store.
+```yaml
+table.catalog-store.kind: file
+table.catalog-store.file.path: /path/to/catalog/store/
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+### Catalog Store Type
+Flink has two built-in Catalog Stores, namely GenericInMemoryCatalogStore and FileCatalogStore.
+Users can also customize their own Catalog Store.

Review Comment:
   Give an example for {catalog name}.yaml in the file path



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] FangYongs commented on a diff in pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "FangYongs (via GitHub)" <gi...@apache.org>.
FangYongs commented on code in PR #23110:
URL: https://github.com/apache/flink/pull/23110#discussion_r1297400125


##########
docs/content/docs/dev/table/catalogs.md:
##########
@@ -807,3 +807,192 @@ the gateway, or you can also use `SET` to specify the listener for ddl, for exam
 Flink SQL> SET 'table.catalog-modification.listeners' = 'your_factory';
 Flink SQL> CREATE TABLE test_table(...);
 ```
+
+## Catalog Store
+
+Catalog Store is used to store the configuration of catalogs. When using Catalog Store, the configurations
+of catalogs created in the session will be persisted in the corresponding external system of Catalog Store.
+Even if the session is reconstructed, previously created catalogs can still be retrieved from Catalog Store.
+
+### Configure Catalog Store
+Users can configure the Catalog Store in different ways, one is to use the Table API, and another is to use YAML configuration.
+
+Register a catalog store using catalog store instance.
+
+```java
+// Initialize a catalog Store instance
+CatalogStore catalogStore = new FileCatalogStore("file://path/to/catalog/store/");
+
+// set up the catalog store
+final EnvironmentSettings settings =
+        EnvironmentSettings.newInstance().inBatchMode()
+        .withCatalogStore(catalogStore)
+        .build();
+```
+
+Register a catalog store using configuration.
+
+```java 
+// Set up configuration
+Configuration configuration = new Configuration();
+configuration.set("table.catalog-store.kind", "file");
+configuration.set("table.catalog-store.file.path", "file://path/to/catalog/store/");
+// set up the configuration.
+final EnvironmentSettings settings =
+        EnvironmentSettings.newInstance().inBatchMode()
+        .withConfiguration(configuration)
+        .build();
+
+final TableEnvironment tableEnv = TableEnvironment.create(settings);
+```
+
+In SQL Gateway, it is recommended to configure the settings in a yaml file so that all sessions can automatically
+use the pre-created Catalog. Usually, you need to configure the kind of Catalog Store and other
+required parameters for the Catalog Store.
+```yaml
+table.catalog-store.kind: file
+table.catalog-store.file.path: /path/to/catalog/store/
+```
+
+### Catalog Store Type
+Flink has two built-in Catalog Stores, namely GenericInMemoryCatalogStore and FileCatalogStore.
+Users can also customize their own Catalog Store.
+
+#### GenericInMemoryCatalogStore
+GenericInMemoryCatalogStore is an implementation of CatalogStore that saves configuration information in memory.
+All catalog configurations are only available within the session's lifecycle, and the stored catalog configurations will be
+automatically cleared after session reconstruction.
+
+<table class="table table-bordered">
+    <thead>
+      <tr>
+        <th class="text-left" style="width: 25%">Option</th>
+        <th class="text-center" style="width: 45%">Description</th>
+      </tr>
+    </thead>
+    <tbody>
+    <tr>
+      <td><h5>kind</h5></td>
+      <td>Specify the Catalog Store type to be used, which should be 'generic_in_memory'</td>
+    </tr>
+    </tbody>
+</table>
+
+#### FileCatalogStore
+FileCatalogStore can save the user's Catalog configuration to a file. Currently, it only supports
+local files. To use FileCatalogStore, you need to specify the directory where the Catalog configuration

Review Comment:
   Currently FLINK-32660 has been merged and catalog store supports external file systems, I think we should update the doc



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] flinkbot commented on pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "flinkbot (via GitHub)" <gi...@apache.org>.
flinkbot commented on PR #23110:
URL: https://github.com/apache/flink/pull/23110#issuecomment-1659592898

   <!--
   Meta data
   {
     "version" : 1,
     "metaDataEntries" : [ {
       "hash" : "506f6a776447d4313025ade982c75e2988744296",
       "status" : "UNKNOWN",
       "url" : "TBD",
       "triggerID" : "506f6a776447d4313025ade982c75e2988744296",
       "triggerType" : "PUSH"
     } ]
   }-->
   ## CI report:
   
   * 506f6a776447d4313025ade982c75e2988744296 UNKNOWN
   
   <details>
   <summary>Bot commands</summary>
     The @flinkbot bot supports the following commands:
   
    - `@flinkbot run azure` re-run the last Azure build
   </details>


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] FangYongs commented on pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "FangYongs (via GitHub)" <gi...@apache.org>.
FangYongs commented on PR #23110:
URL: https://github.com/apache/flink/pull/23110#issuecomment-1683245372

   Thanks @hackergin , LGTM


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] FangYongs commented on a diff in pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "FangYongs (via GitHub)" <gi...@apache.org>.
FangYongs commented on code in PR #23110:
URL: https://github.com/apache/flink/pull/23110#discussion_r1291146721


##########
docs/content/docs/dev/table/catalogs.md:
##########
@@ -738,3 +738,192 @@ Flink SQL> show tables;
 ```
 {{< /tab >}}
 {{< /tabs >}}
+
+## Catalog Store
+
+Catalog Store is used to store the configuration of catalogs. When using Catalog Store, the configurations
+of catalogs created in the session will be persisted in the corresponding external system of Catalog Store.

Review Comment:
   What's `session` here? Besides sql-gateway, there's no session in flink. The session here is a little strange



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] FangYongs commented on pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "FangYongs (via GitHub)" <gi...@apache.org>.
FangYongs commented on PR #23110:
URL: https://github.com/apache/flink/pull/23110#issuecomment-1682499072

   @hackergin Just one minor comment


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] FangYongs merged pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "FangYongs (via GitHub)" <gi...@apache.org>.
FangYongs merged PR #23110:
URL: https://github.com/apache/flink/pull/23110


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] hackergin commented on pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "hackergin (via GitHub)" <gi...@apache.org>.
hackergin commented on PR #23110:
URL: https://github.com/apache/flink/pull/23110#issuecomment-1683221982

   @FangYongs Thanks for reviewing the pr. 


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] FangYongs commented on a diff in pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "FangYongs (via GitHub)" <gi...@apache.org>.
FangYongs commented on code in PR #23110:
URL: https://github.com/apache/flink/pull/23110#discussion_r1291148862


##########
docs/content/docs/dev/table/catalogs.md:
##########
@@ -738,3 +738,192 @@ Flink SQL> show tables;
 ```
 {{< /tab >}}
 {{< /tabs >}}
+
+## Catalog Store
+
+Catalog Store is used to store the configuration of catalogs. When using Catalog Store, the configurations
+of catalogs created in the session will be persisted in the corresponding external system of Catalog Store.
+Even if the session is reconstructed, previously created catalogs can still be retrieved from Catalog Store.
+
+### Configure Catalog Store
+Users can configure the Catalog Store in different ways, one is to use the Table API, and another is to use YAML configuration.
+
+{{< tabs "9bb8994c-7c07-4c49-f5b8-f4ae3548ead4" >}}
+{{< tab "Java/Scala" >}}
+```java
+// Register a catalog store using catalog store instance.
+
+// Initialize a catalog Store
+CatalogStore catalogStore = new FileCatalogStore("file://path/to/catalog/store/");
+
+// set up the catalog store
+final EnvironmentSettings settings =
+        EnvironmentSettings.newInstance().inBatchMode()
+        .withCatalogStore(catalogStore)
+        .build();
+
+final TableEnvironment tableEnv = TableEnvironment.create(settings);
+
+// Register a catalog store using configuration.
+        
+// Set up configuration

Review Comment:
   Can we put them into different code blocks? It's a bit strange to put them together



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [flink] hackergin commented on pull request #23110: [FLINK-32653][docs] Add doc for catalog store

Posted by "hackergin (via GitHub)" <gi...@apache.org>.
hackergin commented on PR #23110:
URL: https://github.com/apache/flink/pull/23110#issuecomment-1676893606

   @FangYongs Thanks for your review, I update the code. 


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org