Trino Knowledge Patch

Trino Knowledge Patch

Use this skill when a task involves Trino SQL, upgrades, configuration, connectors, clients, or plugin development. Start with the quick references below, then open the topic file that matches the task.

Reference index

How to apply this patch

1. Determine the deployed Trino version and the versions of clients and plugins.
2. For upgrades, read the upgrade reference before changing configuration.
3. For SQL behavior, check both syntax and correctness notes; several changes alter results rather than merely enabling new syntax.
4. For lakehouse catalogs, separate shared native-file-system settings from connector-specific settings.
5. For custom plugins, compile against the target SPI and migrate removed APIs; deprecated compatibility paths are not sufficient for current releases.
6. Prefer the repository's manifests, configuration, code, and tests if they show behavior more specific than this general guidance.

Breaking changes first

Avoid release 473

Do not deploy release 473. Large GROUP BY or DISTINCT operations with more than 33 million unique groups can return incorrect results. Release 474 fixes that defect, but 474 can overcount memory and raise EXCEEDED_LOCAL_MEMORY_LIMIT; release 475 fixes the memory accounting.

Use the required Java runtime

Build and run current Trino with JDK 25. JDBC and CLI need Java 11 or newer. When BigQuery or Snowflake is installed, include:

--sun-misc-unsafe-memory-access=allow

When Ignite is installed, also include:

--add-opens=java.base/java.util=ALL-UNNAMED

Remove retired components

• Kinesis, Kudu, Phoenix, and Vertica connectors have been removed.
• The glue-v1 metastore type and deprecated Databricks Unity Catalog integrations have been removed.
• RPM packages are not distributed.
• The HTTP server event-listener plugin is not bundled with the server or image.
• Every catalog must be installed on every node.

Migrate native object storage

Delta Lake, Hive, Iceberg, and Lakehouse catalogs must use native clients for Azure Storage, GCS, IBM Cloud Object Storage, S3, and S3-compatible storage. fs.hadoop.enabled applies only to HDFS. Alluxio exchange and file-system support is gone, although its file-system cache remains supported.

For S3, make authentication explicit:

s3.auth-type=WEB_IDENTITY

Use ANONYMOUS for public buckets and IAM_ROLE whenever s3.iam-role is set. Replace s3.use-web-identity-token-credentials-provider; it is removed.

For GCS, use gcs.auth-type, not removed gcs.use-access-token. Application default credentials use:

gcs.auth-type=APPLICATION_DEFAULT

Remove defunct core settings

Delete the following before or during migration:

• optimize_hash_generation and optimizer.optimize-hash-generation
• prefer_streaming_operators
• task.statistics-cpu-timer-enabled
• enable-large-dynamic-filters and enable_large_dynamic_filters
• dynamic-filtering.small* and dynamic-filtering.large-broadcast*
• deprecated.http-server.authentication.oauth2.groups-field

Also rename HTTP client prefixes workerInfo and memoryManager to worker-info and memory-manager.

Correctness triage

When investigating suspicious results, first check the fixes involving:

• Delta deletion vectors, vacuum, replacement DDL, indexed-Parquet deletes, and failed-write cleanup
• Iceberg change tables, equality deletes, concurrent MERGE, partition evolution, and optimization of invalid NOT NULL data
• spilled grouping, row types, row-pattern FIRST, window DISTINCT, and IS NOT DISTINCT FROM
• high-precision JSON, number values, decimal casts, floating underflow, and rows wider than 64 fields
• spatial joins, geometry tiling, and the Esri-to-JTS geometry migration
• old-PyArrow Parquet, mismatched decimal metadata, and Hive SerDe timestamps

Read the full correctness matrix before attributing these symptoms to data corruption.

SQL quick reference

Per-query properties use WITH SESSION:

WITH SESSION query_max_execution_time = '2m'
SELECT * FROM system.runtime.queries;

Columns can be positioned where the connector supports it:

ALTER TABLE customers
ADD COLUMN middle_name varchar AFTER first_name;

Name-aligned sets and automatic grouping are available:

SELECT orderkey, totalprice FROM current_orders
UNION CORRESPONDING
SELECT orderkey, totalprice FROM archived_orders;

SELECT region, status, count(*)
FROM orders
GROUP BY AUTO;

Recent relational and expression syntax includes PIVOT, NEAREST joins, MATCH, UNIQUE, OVERLAPS, AT LOCAL, named function arguments, method-style functions, predicate CASE arms, and named row fields.

JSON supports dotted and subscript access with typed methods:

SELECT j.customer.name, j.items[0].price.decimal(18,2), j.*
FROM orders;

number interoperates with boolean, JSON, Python UDFs, and Iceberg materialized views. Character coercion now flows from char to trimmed varchar semantics; use the legacy coercion setting only as a temporary bridge.

Iceberg quick reference

• Prefer table-level rollback_to_snapshot; the system procedure is deprecated.
• Use optimize_manifests; it works on tables without snapshots.
• Iceberg v3 supports writes, deletes, maintenance, column defaults, row lineage, nanosecond timestamps, spatial types, and experimental variants.
• $files bounds are typed rows, so update numeric subscripts and JSON casts.
• REST catalogs support IAM/SigV4, OAuth exchange, BigLake, vended credentials, custom headers, prefixed paths, and Application Default Google credentials.
• OPTIMIZE now fails safely when invalid nulls occur in NOT NULL columns.

Operations quick reference

• The redesigned Web UI is at /ui; the former UI is at /ui/legacy and needs web-ui.legacy.enabled=true.
• log.console-format=JSON enables structured console logging.
• tracing.exporter.protocol=http/protobuf selects HTTP protobuf trace export.
• retry-policy.allowed restricts user-selectable retry policies.
• query.max-write-physical-size caps physical writes.
• ANNOUNCE discovery can automatically provision internal TLS.
• OAuth domain filtering uses http-server.authentication.oauth2.domain-hint.
• Persistent JDBC external-auth tokens use externalAuthenticationTokenCache=SYSTEM.

Plugin migration quick reference

Current plugin code must account for these removals and replacements:

• ConnectorPageSource.getNextPage() to getNextSourcePage() and SourcePage
• TypeSignatureParameter family to TypeParameter
• Type.getObject and Type.appendTo
• connector-scoped event listeners and several event-listener statistics
• old connector page/sink/table-function provider methods
• old dynamic-filter parameters to columns plus DynamicFilterSnapshot
• boolean null arrays to bit-packed block validity

Java functions can expose static and instance method syntax with @StaticMethod and @InstanceMethod, and name arguments with @Name. Connector expression pushdown supports COALESCE and lambdas.