{"id":12735,"library":"iceberg-js","title":"Apache Iceberg REST Catalog Client","description":"Iceberg.js is a small, framework-agnostic JavaScript and TypeScript client specifically designed for interacting with Apache Iceberg REST Catalogs. It provides a thin HTTP wrapper over the official REST API, making it generic enough to work with any Iceberg REST Catalog implementation without vendor lock-in. The current stable version is `0.8.1`. The project maintains an active release cadence, with multiple minor versions released within short intervals, indicating ongoing development towards a stable 1.0.0. Key differentiators include first-class TypeScript support for strong typing, reliance on the native `fetch` API for universal compatibility (Node.js 20+ and modern browsers), and a focused scope on catalog operations, deliberately excluding data reading or Parquet file support.","status":"active","version":"0.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/supabase/iceberg-js","tags":["javascript","iceberg","apache-iceberg","rest-catalog","data-lake","catalog","typescript"],"install":[{"cmd":"npm install iceberg-js","lang":"bash","label":"npm"},{"cmd":"yarn add iceberg-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add iceberg-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports and is designed for ESM environments. Using CommonJS `require` may lead to runtime errors or incorrect module resolution.","wrong":"const { IcebergRestCatalog } = require('iceberg-js')","symbol":"IcebergRestCatalog","correct":"import { IcebergRestCatalog } from 'iceberg-js'"},{"note":"Importing types like `AuthConfig` should use `import type` for clarity and to ensure they are stripped during compilation, though regular named imports also work in most TypeScript setups.","symbol":"AuthConfig","correct":"import type { AuthConfig } from 'iceberg-js'"},{"note":"This type is used for specifying desired access delegation mechanisms, such as 'vended-credentials' or 'remote-signing'.","symbol":"AccessDelegation","correct":"import type { AccessDelegation } from 'iceberg-js'"}],"quickstart":{"code":"import { IcebergRestCatalog } from 'iceberg-js'\n\nconst catalog = new IcebergRestCatalog({\n  baseUrl: 'https://my-catalog.example.com/iceberg/v1',\n  auth: {\n    type: 'bearer',\n    token: process.env.ICEBERG_TOKEN ?? '', // Provide a fallback for process.env\n  },\n})\n\nasync function setupIceberg() {\n  try {\n    // Create a namespace\n    console.log('Creating namespace...')\n    await catalog.createNamespace({ namespace: ['analytics'] })\n    console.log('Namespace \"analytics\" created.')\n\n    // Create a table\n    console.log('Creating table \"events\"...')\n    await catalog.createTable(\n      { namespace: ['analytics'] },\n      {\n        name: 'events',\n        schema: {\n          type: 'struct',\n          fields: [\n            { id: 1, name: 'id', type: 'long', required: true },\n            { id: 2, name: 'timestamp', type: 'timestamp', required: true },\n            { id: 3, name: 'user_id', type: 'string', required: false },\n          ],\n          'schema-id': 0,\n          'identifier-field-ids': [1],\n        },\n        'partition-spec': {\n          'spec-id': 0,\n          fields: [],\n        },\n        'write-order': {\n          'order-id': 0,\n          fields: [],\n        },\n        properties: {\n          'write.format.default': 'parquet',\n        },\n      }\n    )\n    console.log('Table \"events\" created in \"analytics\" namespace.')\n  } catch (error) {\n    console.error('Error during Iceberg setup:', error)\n  }\n}\n\nsetupIceberg();","lang":"typescript","description":"This quickstart demonstrates how to initialize the IcebergRestCatalog client, create a new namespace, and then define and create a new table within that namespace, including schema and basic properties."},"warnings":[{"fix":"Review calls to catalog methods and their error handling; update parsing logic to conform to the new API response and error shapes.","message":"Version 0.8.0 introduced changes to match the Iceberg Catalog API's return types and error structure more closely. This might require adjustments to existing code that processes responses or handles errors.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Re-evaluate type usage, especially for schema definitions and data types, to ensure compatibility with the updated `IcebergType` definitions.","message":"Version 0.8.1 included an alignment of `IcebergType` with the OpenAPI specification. If your application relies on specific internal type definitions that deviate from the standard, this update might introduce type-related breaking changes.","severity":"breaking","affected_versions":">=0.8.1"},{"fix":"Be aware of this limitation; for data plane operations, you will need to use a separate data processing engine (e.g., Spark, Flink, Trino) that integrates with Iceberg.","message":"This library is 'Catalog-only' and does not provide functionality for reading or writing data files (e.g., Parquet). It strictly interacts with the Iceberg REST Catalog for metadata operations.","severity":"gotcha","affected_versions":"all versions"},{"fix":"Ensure your Node.js development and production environments are running version 20.0.0 or newer.","message":"The library explicitly targets Node.js version 20.0.0 or higher. Running in older Node.js environments may lead to runtime errors, particularly concerning the native `fetch` API.","severity":"gotcha","affected_versions":"all versions"},{"fix":"Thoroughly verify that `baseUrl` points to the correct catalog endpoint, `catalogName` is specified accurately for multi-catalog setups, and the `auth` object contains valid credentials or configuration.","message":"Incorrect configuration of `baseUrl`, `catalogName`, or `auth` options can lead to 4xx HTTP errors (e.g., 401 Unauthorized, 403 Forbidden, 404 Not Found) when interacting with the Iceberg REST Catalog.","severity":"gotcha","affected_versions":"all versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js runtime to version 20.0.0 or higher. Alternatively, provide a custom `fetch` implementation in the `IcebergRestCatalog` constructor options if you cannot upgrade Node.js.","cause":"The Node.js environment is older than version 20.0.0, which does not include the native `fetch` API.","error":"ReferenceError: fetch is not defined"},{"fix":"Use ESM `import { IcebergRestCatalog } from 'iceberg-js'` and ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`).","cause":"Attempting to use CommonJS `require()` syntax to import the `IcebergRestCatalog` class in a CommonJS module. This library is designed for ESM.","error":"TypeError: IcebergRestCatalog is not a constructor"},{"fix":"Verify your `auth` configuration in the `IcebergRestCatalog` constructor. Ensure the token is correct, not expired, and has the necessary permissions on the Iceberg REST Catalog.","cause":"The authentication credentials provided in the `auth` option are missing, invalid, or do not have sufficient permissions to access the catalog.","error":"HTTP 401 Unauthorized / HTTP 403 Forbidden"},{"fix":"Double-check the `baseUrl` in your `IcebergRestCatalog` options. If applicable, ensure `catalogName` is set correctly and matches your server's configuration.","cause":"The `baseUrl` for the Iceberg REST Catalog is incorrect, or if using a `catalogName`, it is misconfigured, leading to an unreachable endpoint.","error":"HTTP 404 Not Found"}],"ecosystem":"npm"}