Gnok Catalog
Gnok Catalog is the metadata service for your Gnok account. Authorized external clients can use it as an Apache Iceberg REST catalog that manages all table metadata for the lakehouse — catalogs, namespaces, tables, views, materialized views, snapshots, and refs. It is the same catalog the Gnok query engine reads from, and because it implements the standard Iceberg REST Catalog API, compatible engines such as Spark, Trino, Flink, PyIceberg, and DuckDB can connect when authorized and configured and read or write the same tables.
Because table metadata lives in one shared REST catalog, a table written by the Gnok engine is immediately visible to Spark or Trino (and vice versa) with no copy, export, or sync step.
What it does
- Serves Iceberg table metadata over HTTP at
/v1following the Iceberg REST spec — namespace and table listing, table load/commit, views, multi-table transactions, and table rename/register. - Vends scoped storage credentials. Rather than distributing long-lived cloud keys to every engine, Gnok Catalog hands each client short-lived, location-scoped credentials (S3 STS, GCS impersonation, Azure SAS) on demand. See Authentication & credential vending.
- Authenticates clients with OAuth2 (client-credentials and token-exchange grants) and scope-based authorization.
How clients connect
A client points its Iceberg REST catalog at the service's /v1 base URL, names the catalog it wants (sent as the warehouse setting, which the server returns as the REST prefix), and authenticates with an OAuth2 credential or bearer token. To read and write data files, the client also requests vended credentials via the X-Iceberg-Access-Delegation header.
See Connecting external engines for Spark, Trino, PyIceberg, and DuckDB configuration templates. External engine access isn't self-service for new organizations yet; email support@gnok.io for your Catalog URL and engine credentials.
Capabilities
Gnok Catalog advertises the following capabilities from its /v1/config endpoint:
| Capability | Meaning |
|---|---|
tables | Standard Iceberg table operations (list, load, create, commit, drop). |
views | Iceberg view support. |
multi-table-commit | Atomic commits spanning multiple tables (POST /v1/transactions/commit). |
register-table | Register an existing metadata file as a table. |
vended-credentials | Scoped storage credentials returned on table load. |
batch-vended-credentials | Credential vending for many tables in one request. |
remote-signing | Presigned-URL request signing (/sign). |
oauth2 | OAuth2 token endpoint at /v1/oauth/tokens. |
table-metrics | Accepts client-reported scan metrics. |
Key facts
| Service | Gnok Catalog |
| Protocol | HTTPS REST, Iceberg REST Catalog spec |
| API base path | /v1 |
| Endpoint | HTTPS catalog URL provided by Gnok support |
| Object stores for table data | S3, GCS, Azure ADLS |
| Auth | OAuth2 (bearer tokens), scope-based authorization |
Gnok Catalog is the Iceberg REST catalog that Iceberg clients talk to for table metadata. It is distinct from the Gnok engine's own SQL/HTTP query API (see HTTP API). External engines that want to run SQL through Gnok use the engine endpoints; engines that want to read the tables themselves connect to Gnok Catalog.
Next steps
- Connecting external engines — Spark, Trino, PyIceberg, DuckDB.
- Authentication & credential vending — OAuth2 flow, scopes, and how scoped storage credentials work.
- REST API reference — the endpoint surface.