You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "mlsstart (via GitHub)" <gi...@apache.org> on 2025/02/14 14:46:52 UTC
[PR] Add an example to the entities.md file. [polaris]
mlsstart opened a new pull request, #1004:
URL: https://github.com/apache/polaris/pull/1004
<!--
Possible security vulnerabilities: STOP here and contact security@apache.org instead!
Please update the title of the PR with a meaningful message - do not leave it "empty" or "generated"
Please update this summary field:
The summary should cover these topics, if applicable:
* the motivation for the change
* a description of the status quo, for example the current behavior
* the desired behavior
* etc
PR checklist:
- Do a self-review of your code before opening a pull request
- Make sure that there's good test coverage for the changes included in this PR
- Run tests locally before pushing a PR (./gradlew check)
- Code should have comments where applicable. Particularly hard-to-understand
areas deserve good in-line documentation.
- Include changes and enhancements to the documentation (in site/content/in-dev/unreleased)
- For Work In Progress Pull Requests, please use the Draft PR feature.
Make sure to add the information BELOW this comment.
Everything in this comment will NOT be added to the PR description.
-->
I encountered issues when testing with MinIO, so I switched to using the "file" option for local testing. I noticed that the documentation lacks examples for the "file" option. Now, I'm providing a sample for using the "file" option to help others get started quickly.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the entities.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1957046976
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,28 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For example, to create a catalog with a storage type of FILE:
+
+```shell
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+you can create a catalog like so:
+
+```shell
+./polaris \
+ --client-id ${CLIENT_ID} \
+ --client-secret ${CLIENT_SECRET} \
+ catalogs \
+ create \
+ --storage-type file\
Review Comment:
The modification has been completed. Also, a link pointing to the CLI file has been added in the entities.md file. In the quickstart, the link for other storage methods of creating a catalog leads to entities.md, but there were no actual usage examples in entities.md. Now, when reading the quickstart file, users can obtain the CLI link through the link in entities.md to get the actual usage examples.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the entities.md file. [polaris]
Posted by "eric-maynard (via GitHub)" <gi...@apache.org>.
eric-maynard commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1956537588
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,28 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For example, to create a catalog with a storage type of FILE:
+
+```shell
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+you can create a catalog like so:
+
+```shell
+./polaris \
+ --client-id ${CLIENT_ID} \
+ --client-secret ${CLIENT_SECRET} \
+ catalogs \
+ create \
+ --storage-type file\
Review Comment:
+1, maybe [the CLI doc ](https://github.com/apache/polaris/blob/main/site/content/in-dev/unreleased/command-line-interface.md) would be better?
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the entities.md file. [polaris]
Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1957033278
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,28 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For example, to create a catalog with a storage type of FILE:
+
+```shell
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+you can create a catalog like so:
+
+```shell
+./polaris \
+ --client-id ${CLIENT_ID} \
+ --client-secret ${CLIENT_SECRET} \
+ catalogs \
+ create \
+ --storage-type file\
Review Comment:
+1 to add it to the cli doc @eric-maynard mentioned.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1964979098
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,8 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For usage examples of storage types, see [the CLI docs]({{% github-polaris "docs/command-line-interface.md" %}}).
Review Comment:
Thanks for your valuable suggestion. I've taken your advice and made the necessary changes. Now, the link is set from the entities website page to the CLI website page instead of creating a link from the Polaris Web side to the Polaris GH file.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1958953301
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -145,7 +145,15 @@ polaris catalogs create \
--allowed-location s3://example-bucket/second_location \
--allowed-location s3://other-bucket/third_location \
--role-arn ${ROLE_ARN} \
- my_other_catalog
+ my_other_catalog
+
+polaris catalogs create \
+ --storage-type file \
+ --default-base-location file:///example/tmp \
+ quickstart_catalog
+
+Note: file:///example/tmp refers to the local /example/tmp directory. Please replace this directory with your local storage path.
Review Comment:
You're right. This note is indeed unnecessary. I've already made the modification. I'll pay more attention to such issues in the future to ensure the content is concise and clear.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1964864986
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -159,7 +159,13 @@ polaris catalogs create \
--allowed-location s3://example-bucket/second_location \
--allowed-location s3://other-bucket/third_location \
--role-arn ${ROLE_ARN} \
- my_other_catalog
+ my_other_catalog
Review Comment:
nit: using separate code blocks ("```") might be preferable as these commands are not related to each other.
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,8 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For usage examples of storage types, see [the CLI docs]({{% github-polaris "docs/command-line-interface.md" %}}).
Review Comment:
Will this make a link from the Polaris Web side to the Polaris GH file?.. If so, I do not think it's a good idea. I think this link should be from the entities Web site page to the CLI Web site page.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1964979975
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -159,7 +159,13 @@ polaris catalogs create \
--allowed-location s3://example-bucket/second_location \
--allowed-location s3://other-bucket/third_location \
--role-arn ${ROLE_ARN} \
- my_other_catalog
+ my_other_catalog
Review Comment:
Thanks for the nit! I've already made the modification. Now, the commands are presented in separate code blocks as you suggested.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart closed pull request #1004: Add an example to the command-line-interface.md file.
URL: https://github.com/apache/polaris/pull/1004
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the entities.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1957030966
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,28 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For example, to create a catalog with a storage type of FILE:
+
+```shell
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+you can create a catalog like so:
+
+```shell
+./polaris \
+ --client-id ${CLIENT_ID} \
+ --client-secret ${CLIENT_SECRET} \
+ catalogs \
+ create \
+ --storage-type file\
Review Comment:
Yes, there is an example of creating a catalog with the storage type of s3 in the above link, but there is no example of creating a catalog with the storage type of file. It would be more convenient for beginners if a clear example of creating a catalog with the file storage type was provided. I also made some trial - and - error attempts during my usage, so providing this file storage type example can facilitate more people to use it directly.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the entities.md file. [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1956302562
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,28 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For example, to create a catalog with a storage type of FILE:
+
+```shell
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+you can create a catalog like so:
+
+```shell
+./polaris \
+ --client-id ${CLIENT_ID} \
+ --client-secret ${CLIENT_SECRET} \
+ catalogs \
+ create \
+ --storage-type file\
Review Comment:
This page talks about Polaris entities in general. I'm not sure it is the best place for CLI examples.
Also, an example for catalog creation is already available at https://polaris.apache.org/in-dev/unreleased/quickstart/#defining-a-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: issues-unsubscribe@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "eric-maynard (via GitHub)" <gi...@apache.org>.
eric-maynard commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1966021267
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -159,7 +159,13 @@ polaris catalogs create \
--allowed-location s3://example-bucket/second_location \
--allowed-location s3://other-bucket/third_location \
--role-arn ${ROLE_ARN} \
- my_other_catalog
+ my_other_catalog
Review Comment:
I don't want to drag this PR out, but if you look above there's two examples which are not really "related" either. Why are the first two in one code block, but the third is in its own. All through the rest of the doc, the examples share a single code block.
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -159,7 +159,13 @@ polaris catalogs create \
--allowed-location s3://example-bucket/second_location \
--allowed-location s3://other-bucket/third_location \
--role-arn ${ROLE_ARN} \
- my_other_catalog
+ my_other_catalog
Review Comment:
I don't want to drag this PR out, but if you look above there's two examples which are not really "related" either. Why are the first two in one code block, but the third is in its own? All through the rest of the doc, the examples share a single code block.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1964908015
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,8 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For usage examples of storage types, see [the CLI docs]({{% github-polaris "docs/command-line-interface.md" %}}).
Review Comment:
I understand your concern. Actually, when searching for other types of storage methods to create a catalog from the Quikstar page, it currently points to this page. However, the problem is that this page lacks practical usage examples.
That's why I suggest creating a link to the CLI website page. By doing so, users can directly access the CLI website which is likely to have detailed usage cases and instructions. This way, it will be much more convenient for them to use and understand how to create a catalog with different storage types.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the entities.md file. [polaris]
Posted by "mlsstart (via GitHub)" <gi...@apache.org>.
mlsstart commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1957038850
##########
site/content/in-dev/unreleased/entities.md:
##########
@@ -36,6 +36,28 @@ All catalogs in Polaris are associated with a _storage type_. Valid Storage Type
For details on how to use Storage Types in the REST API, see [the API docs]({{% github-polaris "regtests/client/python/docs/StorageConfigInfo.md" %}}).
+For example, to create a catalog with a storage type of FILE:
+
+```shell
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+you can create a catalog like so:
+
+```shell
+./polaris \
+ --client-id ${CLIENT_ID} \
+ --client-secret ${CLIENT_SECRET} \
+ catalogs \
+ create \
+ --storage-type file\
Review Comment:
Thanks for the suggestion. I'll add it to the CLI documentation as @eric-maynard mentioned. If you have any other ideas, do let me know.
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add an example to the command-line-interface.md file. [polaris]
Posted by "eric-maynard (via GitHub)" <gi...@apache.org>.
eric-maynard commented on code in PR #1004:
URL: https://github.com/apache/polaris/pull/1004#discussion_r1958653670
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -145,7 +145,15 @@ polaris catalogs create \
--allowed-location s3://example-bucket/second_location \
--allowed-location s3://other-bucket/third_location \
--role-arn ${ROLE_ARN} \
- my_other_catalog
+ my_other_catalog
+
+polaris catalogs create \
+ --storage-type file \
+ --default-base-location file:///example/tmp \
+ quickstart_catalog
+
+Note: file:///example/tmp refers to the local /example/tmp directory. Please replace this directory with your local storage path.
Review Comment:
This note seems unnecessary; for example just above we freely use the location `s3://other-bucket/third_location `
--
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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org