You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polaris.apache.org by yu...@apache.org on 2026/06/25 22:04:15 UTC
(polaris) branch main updated: Add guide for Trino (#4849)
This is an automated email from the ASF dual-hosted git repository.
flyrain 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 179e180c9e Add guide for Trino (#4849)
179e180c9e is described below
commit 179e180c9e292ca04557116de179d1701e25d130
Author: Marius Grama <fi...@gmail.com>
AuthorDate: Fri Jun 26 00:04:10 2026 +0200
Add guide for Trino (#4849)
---
site/content/guides/_index.md | 6 +
.../guides/trino/catalog/polaris.properties | 33 +++++
site/content/guides/trino/docker-compose.yml | 144 +++++++++++++++++++++
site/content/guides/trino/index.md | 126 ++++++++++++++++++
4 files changed, 309 insertions(+)
diff --git a/site/content/guides/_index.md b/site/content/guides/_index.md
index a0ee6663b0..03eee79fce 100644
--- a/site/content/guides/_index.md
+++ b/site/content/guides/_index.md
@@ -45,6 +45,12 @@ Each guide has detailed instructions.
- [Spark](spark): An example that uses an in-memory metastore, automatically bootstrapped, with
Apache Spark and a Jupyter notebook.
+- [Flink](flink): An example that uses RustFS for S3-compatible object storage and Apache Flink
+ as the stream processing engine, with Polaris as the Iceberg REST Catalog.
+
+- [Trino](trino): An example that uses RustFS for S3-compatible object storage and Trino
+ as the SQL query engine, with Polaris as the Iceberg REST Catalog.
+
- [Telemetry](telemetry): An example that includes Prometheus and Jaeger to collect metrics and
traces from Apache Polaris. This example automatically creates a `polaris_demo` catalog.
diff --git a/site/content/guides/trino/catalog/polaris.properties b/site/content/guides/trino/catalog/polaris.properties
new file mode 100644
index 0000000000..d5341f601b
--- /dev/null
+++ b/site/content/guides/trino/catalog/polaris.properties
@@ -0,0 +1,33 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+connector.name=iceberg
+iceberg.catalog.type=rest
+iceberg.rest-catalog.uri=http://polaris:8181/api/catalog
+iceberg.rest-catalog.security=OAUTH2
+iceberg.rest-catalog.oauth2.credential=${ENV:CLIENT_ID}:${ENV:CLIENT_SECRET}
+iceberg.rest-catalog.oauth2.scope=PRINCIPAL_ROLE:ALL
+iceberg.rest-catalog.warehouse=quickstart_catalog
+iceberg.rest-catalog.vended-credentials-enabled=true
+# Required to route requests to the correct Polaris realm
+iceberg.rest-catalog.http-headers=Polaris-Realm: POLARIS
+fs.s3.enabled=true
+s3.endpoint=http://rustfs:9000
+s3.path-style-access=true
+s3.region=us-west-2
diff --git a/site/content/guides/trino/docker-compose.yml b/site/content/guides/trino/docker-compose.yml
new file mode 100644
index 0000000000..6faa3d9382
--- /dev/null
+++ b/site/content/guides/trino/docker-compose.yml
@@ -0,0 +1,144 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+services:
+
+ rustfs:
+ image: rustfs/rustfs
+ ports:
+ - "9000:9000" # S3 API port
+ - "9001:9001" # Console port
+ environment:
+ RUSTFS_ACCESS_KEY: rustfsadmin
+ RUSTFS_SECRET_KEY: rustfsadmin
+ RUSTFS_VOLUMES: /data
+ RUSTFS_ADDRESS: ":9000"
+ RUSTFS_CONSOLE_ENABLE: "true"
+ RUSTFS_CONSOLE_ADDRESS: ":9001"
+ healthcheck:
+ test: ["CMD-SHELL", "curl --fail http://127.0.0.1:9000/health && curl --fail http://127.0.0.1:9001/rustfs/console/health"]
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 40s
+
+ setup_bucket:
+ image: amazon/aws-cli:2.35.4
+ depends_on:
+ rustfs:
+ condition: service_healthy
+ environment:
+ AWS_ACCESS_KEY_ID: rustfsadmin
+ AWS_SECRET_ACCESS_KEY: rustfsadmin
+ AWS_ENDPOINT_URL: http://rustfs:9000
+ entrypoint: "/bin/sh"
+ command:
+ - "-c"
+ - >-
+ echo Creating RustFS bucket... &&
+ aws s3 mb s3://bucket123 &&
+ aws s3 ls &&
+ echo Bucket setup complete.
+
+ polaris:
+ image: apache/polaris:latest
+ ports:
+ - "8181:8181"
+ - "5005:5005"
+ depends_on:
+ rustfs:
+ condition: service_healthy
+ setup_bucket:
+ condition: service_completed_successfully
+ environment:
+ JAVA_DEBUG: true
+ JAVA_DEBUG_PORT: "*:5005"
+ AWS_REGION: us-west-2
+ AWS_ACCESS_KEY_ID: rustfsadmin
+ AWS_SECRET_ACCESS_KEY: rustfsadmin
+ POLARIS_BOOTSTRAP_CREDENTIALS: POLARIS,root,s3cr3t
+ polaris.realm-context.realms: POLARIS
+ quarkus.otel.sdk.disabled: "true"
+ healthcheck:
+ test: ["CMD", "curl", "--fail", "http://localhost:8182/q/health"]
+ interval: 2s
+ timeout: 10s
+ retries: 10
+ start_period: 10s
+
+ polaris-setup:
+ image: alpine/curl:8.20.0
+ depends_on:
+ polaris:
+ condition: service_healthy
+ setup_bucket:
+ condition: service_completed_successfully
+ environment:
+ - CLIENT_ID=root
+ - CLIENT_SECRET=s3cr3t
+ volumes:
+ - ../assets/polaris/:/polaris
+ entrypoint: "/bin/sh"
+ command:
+ - "-c"
+ - >-
+ source /polaris/obtain-token.sh &&
+ echo Creating catalog... &&
+ export STORAGE_CONFIG_INFO='{"storageType":"S3",
+ "endpoint":"http://localhost:9000",
+ "endpointInternal":"http://rustfs:9000",
+ "pathStyleAccess":true,
+ "region":"us-west-2"}' &&
+ export STORAGE_LOCATION='s3://bucket123' &&
+ /polaris/create-catalog.sh POLARIS $$TOKEN &&
+ echo Extra grants... &&
+ curl \
+ --fail-with-body \
+ -H "Authorization: Bearer $$TOKEN" \
+ -H 'Content-Type: application/json' \
+ -X PUT \
+ http://polaris:8181/api/management/v1/catalogs/quickstart_catalog/catalog-roles/catalog_admin/grants \
+ -d '{"type":"catalog", "privilege":"CATALOG_MANAGE_CONTENT"}' &&
+ echo Done. &&
+ touch /tmp/polaris-setup-done &&
+ tail -f /dev/null
+ healthcheck:
+ interval: 1s
+ timeout: 10s
+ retries: 240
+ test: ["CMD", "test", "-f", "/tmp/polaris-setup-done"]
+
+ trino:
+ image: trinodb/trino
+ ports:
+ - "8080:8080"
+ depends_on:
+ polaris-setup:
+ condition: service_healthy
+ environment:
+ - CLIENT_ID=root
+ - CLIENT_SECRET=s3cr3t
+ volumes:
+ - ./catalog:/etc/trino/catalog
+ healthcheck:
+ test: ["CMD", "curl", "--fail", "http://localhost:8080/v1/info"]
+ interval: 5s
+ timeout: 10s
+ retries: 20
+ start_period: 30s
diff --git a/site/content/guides/trino/index.md b/site/content/guides/trino/index.md
new file mode 100644
index 0000000000..9a9e10c91b
--- /dev/null
+++ b/site/content/guides/trino/index.md
@@ -0,0 +1,126 @@
+---
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+linkTitle: "Client: Trino"
+title: "Getting Started with Apache Polaris and Trino"
+tags:
+ - trino
+weight: 350
+cascade:
+ type: guides
+menus:
+ main:
+ parent: Guides
+ weight: 350
+---
+
+This getting started guide provides a `docker-compose` file to set up [Trino](https://trino.io/) with Apache Polaris.
+Apache Polaris is configured as an Iceberg REST Catalog, and [RustFS](https://rustfs.com/) provides S3-compatible object storage.
+
+The `docker-compose` file starts the following services:
+* `rustfs` — S3-compatible object storage for Iceberg data files
+* `polaris` — Apache Polaris running with an in-memory metastore
+* `polaris-setup` — bootstraps a catalog, grants, and a namespace in Polaris
+* `trino` — Trino configured with an Iceberg connector pointing at Polaris
+
+## Build the Polaris image
+
+If a Polaris image is not already present locally, build one with the following command:
+
+```shell
+./gradlew \
+ :polaris-server:assemble \
+ :polaris-server:quarkusAppPartsBuild --rerun \
+ -Dquarkus.container-image.build=true
+```
+
+## Run the `docker-compose` file
+
+Start all services from the repo's root directory:
+
+```shell
+docker compose -f site/content/guides/trino/docker-compose.yml up
+```
+
+Wait until the `trino` service is healthy before proceeding. You can check by watching for the log line `HTTP server started` in the Trino container output.
+
+## Connect to the Trino CLI
+
+Open a Trino CLI session inside the running Trino container:
+
+```shell
+docker compose -f site/content/guides/trino/docker-compose.yml exec trino trino
+```
+
+## Run SQL queries
+
+The `polaris-setup` service already created a `quickstart_catalog` backed by RustFS. Create a schema, table, and run some queries:
+
+```sql
+CREATE SCHEMA polaris.demo;
+
+USE polaris.demo;
+
+CREATE TABLE events (
+ event_id BIGINT,
+ event_type VARCHAR,
+ user_id BIGINT,
+ created_at TIMESTAMP(6) WITH TIME ZONE
+)
+WITH (format = 'PARQUET');
+
+INSERT INTO events VALUES
+ (1, 'page_view', 101, TIMESTAMP '2024-10-01 10:00:00 UTC'),
+ (2, 'click', 102, TIMESTAMP '2024-10-01 11:30:00 UTC'),
+ (3, 'purchase', 101, TIMESTAMP '2024-10-02 09:15:00 UTC');
+
+SELECT event_type, count(*) AS cnt
+FROM events
+GROUP BY event_type
+ORDER BY cnt DESC;
+```
+
+## Catalog configuration
+
+The Trino Iceberg catalog is defined in `catalog/polaris.properties` and mounted into the Trino container at `/etc/trino/catalog/`. Key properties:
+
+| Property | Value | Description |
+|---|---|---|
+| `iceberg.catalog.type` | `rest` | Use the Iceberg REST catalog protocol |
+| `iceberg.rest-catalog.uri` | `http://polaris:8181/api/catalog` | Polaris REST catalog endpoint |
+| `iceberg.rest-catalog.warehouse` | `quickstart_catalog` | Polaris catalog name |
+| `iceberg.rest-catalog.security` | `OAUTH2` | OAuth2 client credentials flow |
+| `iceberg.rest-catalog.http-headers` | `Polaris-Realm: POLARIS` | Routes requests to the correct Polaris realm |
+| `iceberg.rest-catalog.vended-credentials-enabled` | `true` | Use credentials vended by Polaris to access object storage, instead of static S3 credentials |
+| `fs.s3.enabled` | `true` | Enable native S3 file system |
+| `s3.endpoint` | `http://rustfs:9000` | RustFS S3-compatible endpoint |
+| `s3.path-style-access` | `true` | Required for RustFS |
+
+## RustFS endpoints
+
+The catalog configuration uses different endpoints for Polaris and Trino versus external clients.
+`endpointInternal` (`http://rustfs:9000`) is used by Polaris when writing Iceberg metadata files.
+`endpoint` (`http://localhost:9000`) is the externally reachable address for clients running outside Docker.
+Trino configures its S3 endpoint directly in `catalog/polaris.properties` using the internal Docker hostname `rustfs`.
+
+## Useful URLs
+
+- Trino Web UI: [http://localhost:8080](http://localhost:8080)
+- Polaris REST API: [http://localhost:8181](http://localhost:8181)
+- RustFS Console: [http://localhost:9001](http://localhost:9001)