Skip to content

Align table handles and error codes with Trino conventions - #358

Merged
nineinchnick merged 4 commits into
mainfrom
trino-conventions
Oct 24, 2026
Merged

nineinchnick merged 4 commits into
mainfrom
trino-conventions

Conversation

@nineinchnick

Copy link
Copy Markdown
Owner

These are differences from Trino conventions that reviewers would ask about when the connector is contributed upstream (#205).

  • Table handles were only equal when they were the same instance. Column handles and upstream table handles, like ExampleTableHandle and PrometheusTableHandle, compare by value, so table handles now do too.
  • sortItem, rowFilter, and specHash were already counted in the retained size, but the SortItem object itself wasn't. The engine uses this size to account for the memory of queued splits. The new test checks that every field adds to the size, so fields added later aren't left out.
  • Every split looked up each projected column by comparing its name with the names of all table columns, ignoring case. Projected columns are handles of the same table columns, so a map from handles to row positions finds them without scanning.
  • Problems found after parsing, while mapping the spec to tables and resolving its servers, were thrown as IllegalArgumentException. Trino reports that as GENERIC_INTERNAL_ERROR, as if the connector had a bug. Spec problems now use OPENAPI_INVALID_SPEC (Load the spec on every node reliably and detect mismatches #342). Server problems that are fixed by setting base-uri or authentication.allow-insecure-http use INVALID_CATALOG_PROPERTY, like the authentication problems already do. The error code offset 0x0700_0000 doesn't change here. An upstream contribution would get a new offset from the range of upstream connectors.

Left for later:

  • Deciding which custom HTTP layers to keep for an upstream contribution (DecompressingHttpClient, the disk HTTP cache, RetryPolicy).
  • Moving to the io.trino.plugin.openapi package, the trino-root parent, and removing the release configuration. This only makes sense in the upstream PR.

Part of #300

Without equals and hashCode, two handles describing the same table, filters,
and limit were only equal if they were the same instance, so handles
deserialized on another node, or created again by the engine, were never
equal to the original. Column handles and handles of upstream connectors
compare every field, and table handles should follow the same contract.
The engine uses the retained size of handles to account for the memory
of queued splits, but the size of a pushed down sort item only included
its column name. The test checks that every field adds to the size, so
fields added later are not left out.
Every split looked up each projected column by comparing its name with
the names of all table columns, ignoring case, and built the table
metadata only to read those names. Rows have values of all table
columns in the order the spec defines them, and projected columns are
handles of those same columns, so a map from handles to positions finds
them without scanning, and without depending on how names are cased.
Problems found while mapping the parsed spec to tables, and while
resolving its servers, were thrown as IllegalArgumentException, which
Trino reports as GENERIC_INTERNAL_ERROR, as if the connector had a bug.
Other connectors report invalid external metadata with their own error
code, so problems in the spec use OPENAPI_INVALID_SPEC, like the parser
errors already do. Server problems that are fixed by setting base-uri or
authentication.allow-insecure-http are catalog configuration problems,
so they use INVALID_CATALOG_PROPERTY, like the authentication problems.

Pagination, sorting, and range filter options still validate their own
arguments, and the spec wraps their errors, because they are only
created from the spec.
@nineinchnick
nineinchnick merged commit efce60c into main Oct 24, 2026
1 check passed
@nineinchnick
nineinchnick deleted the trino-conventions branch October 24, 2026 16:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant