You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "MonkeyCanCode (via GitHub)" <gi...@apache.org> on 2026/09/22 05:23:44 UTC
[PR] CLI: Add register support for tables/views commands [polaris]
MonkeyCanCode opened a new pull request, #5577:
URL: https://github.com/apache/polaris/pull/5577
<!--
๐ Describe what changes you're proposing, especially breaking or user-facing changes.
๐ See https://github.com/apache/polaris/blob/main/CONTRIBUTING.md for more.
-->
Per [ML](https://lists.apache.org/thread/m6tpr9oozrpx0fko3qbl0y5qm3mvdv8k), this PR adds `register` support for both `tables` and `views` commands. Same support will be add in setup in a follow up PR.
Sample output:
## Setup
```
use quickstart_catalog;
create namespace dev_namespace;
create namespace dev_namespace.sub_namespace;
create table dev_namespace.sub_namespace.dev_table2 (id int, value int);
create table dev_namespace.sub_namespace.dev_table3 (id int, value int);
create view dev_namespace.sub_namespace.test_view2 as select * from dev_namespace.sub_namespace.dev_table2;
...
spark-sql ()> show create table dev_namespace.sub_namespace.dev_table3;
CREATE TABLE quickstart_catalog.dev_namespace.sub_namespace.dev_table3 (
id INT,
value INT)
USING iceberg
LOCATION 'file:///tmp/polaris/dev_namespace/sub_namespace/dev_table3'
TBLPROPERTIES (
'created-at' = '2026-09-22T05:07:07.961412Z',
'current-snapshot-id' = 'none',
'format' = 'iceberg/parquet',
'format-version' = '2',
'write.parquet.compression-codec' = 'zstd')
Time taken: 0.434 seconds, Fetched 1 row(s)
spark-sql ()> show create table dev_namespace.sub_namespace.test_view2;
CREATE VIEW quickstart_catalog.dev_namespace.sub_namespace.test_view2 (
id,
value)
TBLPROPERTIES (
'format-version' = '1',
'location' = 'file:///tmp/polaris/dev_namespace/sub_namespace/test_view2',
'provider' = 'iceberg')
AS
select * from dev_namespace.sub_namespace.dev_table2
Time taken: 0.488 seconds, Fetched 1 row(s)
```
## Registers for tables
```
# De-register first
(.venv) โ polaris git:(cli_register_support) polaris --profile dev tables delete dev_table3 --catalog quickstart_catalog --namespace dev_namespace.sub_namespace
De-registering table dev_namespace.sub_namespace.dev_table3...
De-registering table dev_namespace.sub_namespace.dev_table3 completed
# Register
(.venv) โ polaris git:(cli_register_support) polaris --profile dev tables register my_table --catalog quickstart_catalog --namespace dev_namespace.sub_namespace --metadata-location file:///tmp/polaris/dev_namespace/sub_namespace/dev_table3/metadata/00000-096e61df-3cfa-4402-a496-2c13cf10264b.metadata.json
Registering table dev_namespace.sub_namespace.my_table...
Registering table dev_namespace.sub_namespace.my_table completed
# Register again (would fail)
(.venv) โ polaris git:(cli_register_support) polaris --profile dev tables register my_table --catalog quickstart_catalog --namespace dev_namespace.sub_namespace --metadata-location file:///tmp/polaris/dev_namespace/sub_namespace/dev_table3/metadata/00000-096e61df-3cfa-4402-a496-2c13cf10264b.metadata.json
Registering table dev_namespace.sub_namespace.my_table...
Exception when communicating with the Polaris server. AlreadyExistsException: Table already exists: dev_namespace.sub_namespace.my_table
# Register with overwrite
(.venv) โ polaris git:(cli_register_support) polaris --profile dev tables register my_table --catalog quickstart_catalog --namespace dev_namespace.sub_namespace --metadata-location file:///tmp/polaris/dev_namespace/sub_namespace/dev_table3/metadata/00000-096e61df-3cfa-4402-a496-2c13cf10264b.metadata.json --overwrite
Registering table dev_namespace.sub_namespace.my_table...
Registering table dev_namespace.sub_namespace.my_table completed
# Validation
spark-sql ()> show create table dev_namespace.sub_namespace.my_table;
CREATE TABLE quickstart_catalog.dev_namespace.sub_namespace.my_table (
id INT,
value INT)
USING iceberg
LOCATION 'file:///tmp/polaris/dev_namespace/sub_namespace/dev_table3'
TBLPROPERTIES (
'created-at' = '2026-09-22T05:07:07.961412Z',
'current-snapshot-id' = 'none',
'format' = 'iceberg/parquet',
'format-version' = '2',
'write.parquet.compression-codec' = 'zstd')
Time taken: 0.354 seconds, Fetched 1 row(s)
```
## Register for views
```
# Register
(.venv) โ polaris git:(cli_register_support) โ polaris --profile dev views register my_view --catalog quickstart_catalog --namespace dev_namespace.sub_namespace --metadata-location file:///tmp/polaris/dev_namespace/sub_namespace/test_view2/metadata/00000-384fb111-bda6-497c-ae55-a237df766adb.gz.metadata.json
Registering view dev_namespace.sub_namespace.my_view...
Registering view dev_namespace.sub_namespace.my_view completed
# Validation
spark-sql ()> show create table dev_namespace.sub_namespace.my_view;
CREATE VIEW quickstart_catalog.dev_namespace.sub_namespace.my_view (
id,
value)
TBLPROPERTIES (
'format-version' = '1',
'location' = 'file:///tmp/polaris/dev_namespace/sub_namespace/test_view2',
'provider' = 'iceberg')
AS
select * from dev_namespace.sub_namespace.dev_table2
```
## Checklist
- [x] ๐ก๏ธ Don't disclose security issues! (contact security@apache.org)
- [x] ๐ Clearly explained why the changes are needed, or linked related issues: Fixes #
- [x] ๐งช Added/updated tests with good coverage, or manually tested (and explained how)
- [x] ๐ก Added comments for complex logic
- [x] ๐งพ Updated `CHANGELOG.md` (if needed)
- [x] ๐ Updated documentation in `site/content/in-dev/unreleased` (if needed)
--
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] CLI: Add register support for tables/views commands [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5577:
URL: https://github.com/apache/polaris/pull/5577#discussion_r4108905023
##########
client/python/apache_polaris/cli/command/utils.py:
##########
@@ -150,6 +151,22 @@ def handle_api_exception(entity_label: str, e: Exception) -> None:
print(f" [x] {entity_label:<30} Error: {e}", file=sys.stderr)
+def validate_metadata_location(location: Optional[str]) -> str:
+ """
+ Validate and normalize a --metadata-location argument.
+
+ Returns the location with surrounding whitespace stripped, or raises
+ CliError on failure.
+ """
+ location = location.strip() if location else location
+ if not location:
+ raise CliError("Missing required argument: --metadata-location")
+ parsed = urlparse(location)
Review Comment:
Many valid S3 locations are not valid URIs ๐คท
Cf. https://github.com/projectnessie/nessie/issues/8328
That said, it is probably fine to fail those super special locations at the CLI level. In any case, if you want to support them, it can be done in a separate 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@polaris.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] CLI: Add register support for tables/views commands [polaris]
Posted by "MonkeyCanCode (via GitHub)" <gi...@apache.org>.
MonkeyCanCode commented on PR #5577:
URL: https://github.com/apache/polaris/pull/5577#issuecomment-5883825657
Thanks for review @dimas-b and @flyingImer . Merged this PR now. I will create a new one for setup integration later this week.
--
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] CLI: Add register support for tables/views commands [polaris]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #5577:
URL: https://github.com/apache/polaris/pull/5577#discussion_r4068682297
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -1732,6 +1732,7 @@ The `tables` command is used to manage Iceberg tables within a Polaris Catalog.
2. get
3. summarize
4. delete
+4. register
Review Comment:
This list now numbers both `delete` and `register` as 4, so the new subcommand is presented with an incorrect ordinal. Please number `register` as 5.
This issue also appears on line 1866 of the same file.
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -1826,6 +1827,32 @@ Command Options:
polaris tables delete my_table --catalog my_catalog --namespace ns1
```
+#### register
+
+The `register` subcommand is used to register a table to catalog by its metadata location
+
+```
+usage: polaris tables register [-h] [options] TABLE_NAME
+
+positional arguments:
+ TABLE_NAME table
+
+options:
+ -h, --help show this help message and exit
+
+Command Options:
+ --catalog CATALOG The name of a catalog
+ --namespace NAMESPACE A period-delimited namespace
+ --metadata-location METADATA_LOCATION The absolute location of the Iceberg metadata file
+ --overwrite Overwrite an existing table at the same identifier if the table is already registered
+```
+
+##### Examples
+
+```
+polaris tables register my_table --catalog my_catalog --namesapce ns1 --metadata-location s3://bucket/path/00001-(uuid).metadata.json
Review Comment:
The example uses the misspelled `--namesapce` option, so copying it causes argparse to reject the command. Please correct it to `--namespace`.
This issue also appears on line 1983 of the same 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] CLI: Add register support for tables/views commands [polaris]
Posted by "jbonofre (via GitHub)" <gi...@apache.org>.
jbonofre commented on code in PR #5577:
URL: https://github.com/apache/polaris/pull/5577#discussion_r4071371885
##########
client/python/apache_polaris/cli/command/utils.py:
##########
@@ -150,6 +151,16 @@ def handle_api_exception(entity_label: str, e: Exception) -> None:
print(f" [x] {entity_label:<30} Error: {e}", file=sys.stderr)
+def validate_metadata_location(location: Optional[str]) -> None:
+ """
+ Validate a --metadata-location argument. Raises CliError on failure.
+ """
+ if not location or not location.strip():
Review Comment:
`location.strip()` is only used to test for emptiness, the stripped value is never reassigned, so surrounding whitespace reaches the server. Separately, `urlparse().scheme` alone clearly doesn't guard against Windows-style path (`urlparse("C:\\data\\x.json").scheme == "c"`), so a bare drive-letter path slips past this check.
```suggestion
location = location.strip() if location else location
if not location:
raise CliError("Missing required argument: --metadata-location")
parsed = urlparse(location)
if not parsed.scheme or len(parsed.scheme) == 1:
raise CliError(f"--metadata-location must include a scheme; got {location}")
```
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -1930,6 +1958,31 @@ Command Options:
polaris views delete my_view --catalog my_catalog --namespace ns1
```
+#### register
+
+The `register` subcommand is used to register an view to catalog by its metadata location
Review Comment:
nit:
```suggestion
The `register` subcommand is used to register a view to catalog by its metadata location
```
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -1836,6 +1863,7 @@ The `views` command is used to manage Iceberg views within a Polaris Catalog.
2. get
3. summarize
4. delete
+4. register
Review Comment:
nit:
```suggestion
5. register
```
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -1930,6 +1958,31 @@ Command Options:
polaris views delete my_view --catalog my_catalog --namespace ns1
```
+#### register
+
+The `register` subcommand is used to register an view to catalog by its metadata location
+
+```
+usage: polaris views register [-h] [options] VIEW_NAME
+
+positional arguments:
+ VIEW_NAME view
+
+options:
+ -h, --help show this help message and exit
+
+Command Options:
+ --catalog CATALOG The name of a catalog
+ --namespace NAMESPACE A period-delimited namespace
+ --metadata-location METADATA_LOCATION The absolute location of the Iceberg metadata file
+```
+
+##### Examples
+
+```
+polaris views register my_view --catalog my_catalog --namesapce ns1 --metadata-location s3://bucket/path/00001-(uuid).metadata.json
Review Comment:
nit:
```suggestion
polaris views register my_view --catalog my_catalog --namespace ns1 --metadata-location s3://bucket/path/00001-(uuid).metadata.json
```
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -1826,6 +1827,32 @@ Command Options:
polaris tables delete my_table --catalog my_catalog --namespace ns1
```
+#### register
+
+The `register` subcommand is used to register a table to catalog by its metadata location
+
+```
+usage: polaris tables register [-h] [options] TABLE_NAME
+
+positional arguments:
+ TABLE_NAME table
+
+options:
+ -h, --help show this help message and exit
+
+Command Options:
+ --catalog CATALOG The name of a catalog
+ --namespace NAMESPACE A period-delimited namespace
+ --metadata-location METADATA_LOCATION The absolute location of the Iceberg metadata file
+ --overwrite Overwrite an existing table at the same identifier if the table is already registered
+```
+
+##### Examples
+
+```
+polaris tables register my_table --catalog my_catalog --namesapce ns1 --metadata-location s3://bucket/path/00001-(uuid).metadata.json
Review Comment:
Typo fix ๐
##########
site/content/in-dev/unreleased/command-line-interface.md:
##########
@@ -1732,6 +1732,7 @@ The `tables` command is used to manage Iceberg tables within a Polaris Catalog.
2. get
3. summarize
4. delete
+4. register
Review Comment:
Duplicate number ๐
--
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] CLI: Add register support for tables/views commands [polaris]
Posted by "MonkeyCanCode (via GitHub)" <gi...@apache.org>.
MonkeyCanCode commented on code in PR #5577:
URL: https://github.com/apache/polaris/pull/5577#discussion_r4113995944
##########
client/python/apache_polaris/cli/command/utils.py:
##########
@@ -150,6 +151,22 @@ def handle_api_exception(entity_label: str, e: Exception) -> None:
print(f" [x] {entity_label:<30} Error: {e}", file=sys.stderr)
+def validate_metadata_location(location: Optional[str]) -> str:
+ """
+ Validate and normalize a --metadata-location argument.
+
+ Returns the location with surrounding whitespace stripped, or raises
+ CliError on failure.
+ """
+ location = location.strip() if location else location
+ if not location:
+ raise CliError("Missing required argument: --metadata-location")
+ parsed = urlparse(location)
Review Comment:
Thanks for the info @dimas-b . In this case, should we drop the check?
--
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] CLI: Add register support for tables/views commands [polaris]
Posted by "MonkeyCanCode (via GitHub)" <gi...@apache.org>.
MonkeyCanCode commented on code in PR #5577:
URL: https://github.com/apache/polaris/pull/5577#discussion_r4118474816
##########
client/python/apache_polaris/cli/command/utils.py:
##########
@@ -150,6 +151,22 @@ def handle_api_exception(entity_label: str, e: Exception) -> None:
print(f" [x] {entity_label:<30} Error: {e}", file=sys.stderr)
+def validate_metadata_location(location: Optional[str]) -> str:
+ """
+ Validate and normalize a --metadata-location argument.
+
+ Returns the location with surrounding whitespace stripped, or raises
+ CliError on failure.
+ """
+ location = location.strip() if location else location
+ if not location:
+ raise CliError("Missing required argument: --metadata-location")
+ parsed = urlparse(location)
Review Comment:
i think that is good to drop for now.
I will check above references in case if they are still valid later next weekend. Thanks for the reference @dimas-b
--
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] CLI: Add register support for tables/views commands [polaris]
Posted by "MonkeyCanCode (via GitHub)" <gi...@apache.org>.
MonkeyCanCode merged PR #5577:
URL: https://github.com/apache/polaris/pull/5577
--
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] CLI: Add register support for tables/views commands [polaris]
Posted by "MonkeyCanCode (via GitHub)" <gi...@apache.org>.
MonkeyCanCode commented on PR #5577:
URL: https://github.com/apache/polaris/pull/5577#issuecomment-5826131443
@jbonofre mind take another look?
--
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] CLI: Add register support for tables/views commands [polaris]
Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5577:
URL: https://github.com/apache/polaris/pull/5577#discussion_r4117199521
##########
client/python/apache_polaris/cli/command/utils.py:
##########
@@ -150,6 +151,22 @@ def handle_api_exception(entity_label: str, e: Exception) -> None:
print(f" [x] {entity_label:<30} Error: {e}", file=sys.stderr)
+def validate_metadata_location(location: Optional[str]) -> str:
+ """
+ Validate and normalize a --metadata-location argument.
+
+ Returns the location with surrounding whitespace stripped, or raises
+ CliError on failure.
+ """
+ location = location.strip() if location else location
+ if not location:
+ raise CliError("Missing required argument: --metadata-location")
+ parsed = urlparse(location)
Review Comment:
If we drop the check in CLI, we simply rely on the server to enforce correct syntax, which if fine from my POV.
If we fail odd URI in the CLI, we users an early warning of potential issues.
I'm fine either way :slightly_smiling_face: ... but I'm leaning towards dropping the check in the CLI. This will be the most flexible approach.
That said, we should probably improve the server-side handling too :sweat_smile: cf. #1545 #552.
--
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