Skip to content

Doc: Add example on using Polaris with PyIceberg #2315

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 13, 2025
Merged

Doc: Add example on using Polaris with PyIceberg #2315

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions site/content/in-dev/unreleased/getting-started/using-polaris.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,6 +285,51 @@ SELECT * FROM iceberg.quickstart_schema.quickstart_table;
org.apache.iceberg.exceptions.ForbiddenException: Forbidden: Principal 'quickstart_user' with activated PrincipalRoles '[]' and activated grants via '[quickstart_catalog_role, quickstart_user_role]' is not authorized for op LOAD_TABLE_WITH_READ_DELEGATION
```

### Connecting with PyIceberg

#### Using Credentials

```python
from pyiceberg.catalog import load_catalog

catalog = load_catalog(
type='rest',
uri='http://localhost:8181/api/catalog',
warehouse='quickstart_catalog',
scope="PRINCIPAL_ROLE:ALL",
credential=f"{CLIENT_ID}:{CLIENT_SECRET}",
)
```

If the `load_catalog` function is used with credentials, then PyIceberg will automatically request an authorization token from the `v1/oauth/tokens` endpoint, and will later use this token to prove its identity to the Polaris Catalog.

#### Using a Token

```python
from pyiceberg.catalog import load_catalog
import requests

# Step 1: Get OAuth token
response = requests.post(
"http://localhost:8181/api/catalog/v1/oauth/tokens",
auth =(CLIENT_ID, CLIENT_SECRET),
data = {
"grant_type": "client_credentials",
"scope": "PRINCIPAL_ROLE:ALL"
})
token = response.json()["access_token"]

# Step 2: Load the catalog using the token
catalog = load_catalog(
type='rest',
uri='http://localhost:8181/api/catalog',
warehouse='quickstart_catalog',
token=token,
)
```

It is possible to use `load_catalog` function by providing an authorization token directly. This method is useful when using an external identity provider (e.g. Google Identity).

Copy link
Contributor

@flyrain flyrain Aug 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest to provide some sample commands of pyIceberg, like list table, list files, etc. Not a blocker though.

Copy link
Contributor

@eric-maynard eric-maynard Aug 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

eh, the other sections for other clients doesn't get into too much detail either -- it could be nice to have, but I think a regtest would be even better to cover a full set of operations in pyiceberg. The docs can stay lightweight

### Connecting Using REST APIs

To access Polaris from the host machine, first request an access token:
Expand Down