---
title: External Catalog
description: External Catalog protocol schemas
---

{/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs go in content/docs/guides/. */}

ExternalCatalog — cached remote-schema snapshot for a federated datasource

(ADR-0015 §4.3).

Introspecting a mature warehouse on every boot is expensive, so the

`IExternalDatasourceService.refreshCatalog` persists a snapshot of the

remote tables/columns as an `external_catalog` metadata record. The

boot-validation gate (Gate 2) and Studio's schema browser read from it;

drift is detected by diffing a fresh introspection against the snapshot.

<Callout type="info">
**Source:** `packages/spec/src/data/external-catalog.zod.ts`
</Callout>

## TypeScript Usage

```typescript
import { ExternalCatalog, ExternalColumn, ExternalTable } from '@objectstack/spec/data';
import type { ExternalCatalog, ExternalColumn, ExternalTable } from '@objectstack/spec/data';

// Validate data
const result = ExternalCatalog.parse(data);
```

---

## ExternalCatalog

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Catalog id, conventionally `<datasource>_catalog`. |
| **datasource** | `string` | ✅ | Datasource.name this catalog snapshots. |
| **snapshotAt** | `string` | ✅ | When the snapshot was taken (ISO 8601). |
| **dialect** | `string` | optional | Remote SQL dialect, when known. |
| **tables** | `Object[]` | ✅ | Snapshotted remote tables. |


---

## ExternalColumn

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **name** | `string` | ✅ | Remote column name |
| **sqlType** | `string` | ✅ | Raw remote SQL type (e.g. "numeric(10,2)") |
| **nullable** | `boolean` | ✅ | Whether the remote column is nullable |
| **primaryKey** | `boolean` | ✅ | Part of the remote primary key |
| **suggestedFieldType** | `string` | optional | ObjectStack field type suggested by the type-compat matrix |


---

## ExternalTable

### Properties

| Property | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| **remoteSchema** | `string` | optional | Remote schema/database qualifier |
| **remoteName** | `string` | ✅ | Remote table/view name |
| **columns** | `Object[]` | ✅ | Remote columns |
| **indexes** | `Object[]` | optional | Remote indexes, when introspectable |
| **rowCountEstimate** | `number` | optional | Approximate row count |


---

