Iceberg Connections

Iceberg connections point an agent at an Apache Iceberg REST catalog. Agents query Iceberg tables via SQL using the iceberg_query tool.

Every Firetiger deployment auto-provisions a virtual, read-only Iceberg connection that targets the deployment’s own data lake (logs, spans, metrics). You only need to create a new Iceberg connection if you want agents to query an external Iceberg warehouse — for example, a customer’s data lake or a separate analytical platform.

Recommended: Create and manage connections via the web UI at https://ui.cloud.firetiger.com/settings/connections

Connection Parameters

Parameter	Type	Description
`catalog_uri`	string	REST catalog URI (e.g., `https://iceberg-gw.example.com/iceberg/v1`)

Authentication

Set exactly one of the following auth methods:

Basic Auth

HTTP Basic authentication with username and password.

"basic": {
  "username": "user",
  "password": "pass"
}

Bearer Token

Static Bearer token sent as Authorization: Bearer <token>.

"bearer": {
  "token": "<token>"
}

Context Auth

Forwards the caller’s own credentials. Used by the auto-provisioned Firetiger gateway connection so each agent run authenticates as the originating user.

"context": {}

Example Connection

{
  "display_name": "Customer Data Lake",
  "description": "Read-only access to the customer's Iceberg warehouse for analytics queries",
  "connection_details": {
    "iceberg": {
      "catalog_uri": "https://iceberg.example.com/v1",
      "bearer": { "token": "<token>" }
    }
  }
}

Best Practices

Use the auto-provisioned gateway for the deployment’s own data lake — agents already have it as the default profile
Document namespaces and tables in the description field so agents can write effective queries without round-tripping through LIST calls
Prefer read-only credentials at the catalog level when connecting to a customer’s warehouse