JavaScript: from

Get an Iceberg REST Catalog client configured for a specific analytics bucket Use this to perform advanced table and namespace operations within the bucket The returned client provides full access to the Apache Iceberg REST Catalog API with the Supabase { data, error } pattern for consistent error handling on all operations.

Public alpha: This API is part of a public alpha release and may not be available to your account type.

Parameters

• bucketName

  (Required)

  The name of the analytics bucket (warehouse) to connect to

Examples

Get catalog and create table

// First, create an analytics bucket
const { data: bucket, error: bucketError } = await supabase
  .storage
  .analytics
  .createBucket('analytics-data')

// Get the Iceberg catalog for that bucket
const catalog = supabase.storage.analytics.from('analytics-data')

// Create a namespace
const { error: nsError } = await catalog.createNamespace({ namespace: ['default'] })

// Create a table with schema
const { data: tableMetadata, error: tableError } = await catalog.createTable(
  { namespace: ['default'] },
  {
    name: 'events',
    schema: {
      type: 'struct',
      fields: [
        { id: 1, name: 'id', type: 'long', required: true },
        { id: 2, name: 'timestamp', type: 'timestamp', required: true },
        { id: 3, name: 'user_id', type: 'string', required: false }
      ],
      'schema-id': 0,
      'identifier-field-ids': [1]
    },
    'partition-spec': {
      'spec-id': 0,
      fields: []
    },
    'write-order': {
      'order-id': 0,
      fields: []
    },
    properties: {
      'write.format.default': 'parquet'
    }
  }
)

List tables in namespace

const catalog = supabase.storage.analytics.from('analytics-data')

// List all tables in the default namespace
const { data: tables, error: listError } = await catalog.listTables({ namespace: ['default'] })
if (listError) {
  if (listError.isNotFound()) {
    console.log('Namespace not found')
  }
  return
}
console.log(tables) // [{ namespace: ['default'], name: 'events' }]

Working with namespaces

const catalog = supabase.storage.analytics.from('analytics-data')

// List all namespaces
const { data: namespaces } = await catalog.listNamespaces()

// Create namespace with properties
await catalog.createNamespace(
  { namespace: ['production'] },
  { properties: { owner: 'data-team', env: 'prod' } }
)

Cleanup operations

const catalog = supabase.storage.analytics.from('analytics-data')

// Drop table with purge option (removes all data)
const { error: dropError } = await catalog.dropTable(
  { namespace: ['default'], name: 'events' },
  { purge: true }
)

if (dropError?.isNotFound()) {
  console.log('Table does not exist')
}

// Drop namespace (must be empty)
await catalog.dropNamespace({ namespace: ['default'] })