You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polaris.apache.org by ad...@apache.org on 2026/06/12 04:06:36 UTC

(polaris) branch main updated: Fix Getting Started guide issues for end-to-end usability (#4627)

This is an automated email from the ASF dual-hosted git repository.

adnanhemani pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git


The following commit(s) were added to refs/heads/main by this push:
     new b9a0539ea2 Fix Getting Started guide issues for end-to-end usability (#4627)
b9a0539ea2 is described below

commit b9a0539ea26d8de5c22cf5b761eb6961a622f91f
Author: Adnan Hemani <ad...@berkeley.edu>
AuthorDate: Thu Jun 11 21:06:32 2026 -0700

    Fix Getting Started guide issues for end-to-end usability (#4627)
    
    - Fix broken anchor in using-polaris/_index.md (ref -> relref, dead
      #defining-a-catalog link -> Creating a Catalog page)
    - Rename Spark catalog from quickstart_catalog to polaris in
      docker-compose and guide SQL (USE polaris;)
    - Add extra_hosts: polaris:host-gateway to spark-sql and trino services
      so containers can reach a host-running Polaris server
    - Add --client-id/--client-secret to polaris setup export and apply
      commands in setup-tools.md
---
 site/content/guides/jdbc/docker-compose.yml        |  4 ++++
 .../unreleased/getting-started/setup-tools.md      |  6 +++---
 .../getting-started/using-polaris/_index.md        | 24 +++++++++++-----------
 3 files changed, 19 insertions(+), 15 deletions(-)

diff --git a/site/content/guides/jdbc/docker-compose.yml b/site/content/guides/jdbc/docker-compose.yml
index 4e43f37657..97e7d446d9 100644
--- a/site/content/guides/jdbc/docker-compose.yml
+++ b/site/content/guides/jdbc/docker-compose.yml
@@ -74,6 +74,8 @@ services:
         condition: service_completed_successfully
     stdin_open: true
     tty: true
+    extra_hosts:
+      - "polaris:host-gateway"
     ports:
       - "4040-4045:4040-4045"
     healthcheck:
@@ -102,6 +104,8 @@ services:
         condition: service_completed_successfully
     stdin_open: true
     tty: true
+    extra_hosts:
+      - "polaris:host-gateway"
     ports:
       - "8080:8080"
     environment:
diff --git a/site/content/in-dev/unreleased/getting-started/setup-tools.md b/site/content/in-dev/unreleased/getting-started/setup-tools.md
index af9b1119ed..c96e8eb050 100644
--- a/site/content/in-dev/unreleased/getting-started/setup-tools.md
+++ b/site/content/in-dev/unreleased/getting-started/setup-tools.md
@@ -37,7 +37,7 @@ This command supports bootstrapping new environments and exporting existing conf
 If you already have an Apache Polaris environment, you can export its current state to a YAML file using the `export` subcommand:
 
 ```bash
-polaris setup export > polaris_bootstrap.yaml
+polaris setup export --client-id ${CLIENT_ID} --client-secret ${CLIENT_SECRET} > polaris_bootstrap.yaml
 ```
 
 This generates a readable YAML file containing principals, principal roles, catalogs, and their associated namespaces and catalog roles.
@@ -87,13 +87,13 @@ catalogs:
 Before making any changes, you can preview what will be executed using the `--dry-run` flag:
 
 ```bash
-polaris setup apply --dry-run site/content/guides/assets/polaris/simple-setup-config.yaml
+polaris setup apply --client-id ${CLIENT_ID} --client-secret ${CLIENT_SECRET} --dry-run site/content/guides/assets/polaris/simple-setup-config.yaml
 ```
 
 Once satisfied, run the command to apply the changes:
 
 ```bash
-polaris setup apply site/content/guides/assets/polaris/simple-setup-config.yaml
+polaris setup apply --client-id ${CLIENT_ID} --client-secret ${CLIENT_SECRET} site/content/guides/assets/polaris/simple-setup-config.yaml
 ```
 
 ## Known Limitations
diff --git a/site/content/in-dev/unreleased/getting-started/using-polaris/_index.md b/site/content/in-dev/unreleased/getting-started/using-polaris/_index.md
index 7586ced0bb..84509a80f8 100644
--- a/site/content/in-dev/unreleased/getting-started/using-polaris/_index.md
+++ b/site/content/in-dev/unreleased/getting-started/using-polaris/_index.md
@@ -37,7 +37,7 @@ export CLIENT_ID=YOUR_CLIENT_ID
 export CLIENT_SECRET=YOUR_CLIENT_SECRET
 ```
 
-Refer to the [Creating a Catalog]({{% ref "../creating-a-catalog" %}}) page for instructions on defining a
+Refer to the [Creating a Catalog]({{% relref "../creating-a-catalog" %}}) page for instructions on defining a
 catalog for your specific storage type. The following examples assume the catalog's name is `quickstart_catalog`.
 
 In Polaris, the [catalog]({{% relref "../../entities#catalog" %}}) is the top-level entity that objects like [tables]({{% relref "../../entities#table" %}}) and [views]({{% relref "../../entities#view" %}}) are organized under.
@@ -50,7 +50,7 @@ Additionally, if Polaris is running somewhere other than `localhost:8181`, you c
 
 ### Creating a Principal and Assigning it Privileges
 
-With a catalog created, we can create a [principal]({{% relref "../../entities#principal" %}}) that has access to manage that catalog. For details on how to configure the Polaris CLI, see [the section above](#defining-a-catalog) or refer to the [docs]({{% relref "../../command-line-interface" %}}).
+With a catalog created, we can create a [principal]({{% relref "../../entities#principal" %}}) that has access to manage that catalog. For details on how to configure the Polaris CLI, see the [Creating a Catalog]({{% relref "../creating-a-catalog" %}}) page or refer to the [docs]({{% relref "../../command-line-interface" %}}).
 
 ```shell
 polaris \
@@ -150,15 +150,15 @@ _Note: the credentials provided here are those for our principal, not the root c
 bin/spark-sql \
 --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \
 --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
---conf spark.sql.catalog.quickstart_catalog.warehouse=quickstart_catalog \
---conf spark.sql.catalog.quickstart_catalog.header.X-Iceberg-Access-Delegation=vended-credentials \
---conf spark.sql.catalog.quickstart_catalog=org.apache.iceberg.spark.SparkCatalog \
---conf spark.sql.catalog.quickstart_catalog.catalog-impl=org.apache.iceberg.rest.RESTCatalog \
---conf spark.sql.catalog.quickstart_catalog.uri=http://localhost:8181/api/catalog \
---conf spark.sql.catalog.quickstart_catalog.credential=${USER_CLIENT_ID}:${USER_CLIENT_SECRET} \
---conf spark.sql.catalog.quickstart_catalog.scope='PRINCIPAL_ROLE:ALL' \
---conf spark.sql.catalog.quickstart_catalog.token-refresh-enabled=true \
---conf spark.sql.catalog.quickstart_catalog.client.region=us-west-2
+--conf spark.sql.catalog.polaris.warehouse=quickstart_catalog \
+--conf spark.sql.catalog.polaris.header.X-Iceberg-Access-Delegation=vended-credentials \
+--conf spark.sql.catalog.polaris=org.apache.iceberg.spark.SparkCatalog \
+--conf spark.sql.catalog.polaris.catalog-impl=org.apache.iceberg.rest.RESTCatalog \
+--conf spark.sql.catalog.polaris.uri=http://localhost:8181/api/catalog \
+--conf spark.sql.catalog.polaris.credential=${USER_CLIENT_ID}:${USER_CLIENT_SECRET} \
+--conf spark.sql.catalog.polaris.scope='PRINCIPAL_ROLE:ALL' \
+--conf spark.sql.catalog.polaris.token-refresh-enabled=true \
+--conf spark.sql.catalog.polaris.client.region=us-west-2
 ```
 
 Similar to the CLI commands above, this configures Spark to use the Polaris running at `localhost:8181`. If your Polaris server is running elsewhere, but sure to update the configuration appropriately.
@@ -185,7 +185,7 @@ docker attach $(docker ps -q --filter name=spark-sql)
 Once the Spark session starts, we can create a namespace and table within the catalog:
 
 ```sql
-USE quickstart_catalog;
+USE polaris;
 CREATE NAMESPACE IF NOT EXISTS quickstart_namespace;
 CREATE NAMESPACE IF NOT EXISTS quickstart_namespace.schema;
 USE NAMESPACE quickstart_namespace.schema;