HubDB Tables

HubDB is HubSpot’s relational database feature used to power dynamic website content, structured data tables, and CMS-driven pages. JetStack AI supports full import and deployment of HubDB tables, including their column definitions, row data, and cross-table foreign key relationships.

Table Structure

A HubDB table consists of three parts:

Columns

Each column has a type that determines what data it stores:

Column Type	Description
TEXT	Plain text strings
NUMBER	Numeric values
DATE	Date values
DATETIME	Date and time values
SELECT	Single-select from a list of static options
MULTISELECT	Multi-select from a list of static options
BOOLEAN	True/false values
URL	URL strings
CURRENCY	Monetary values
LOCATION	Latitude/longitude pairs
IMAGE	Image file references
VIDEO	Video file references
RICHTEXT	Rich text content
FOREIGN_ID	Foreign key reference to a row in another HubDB table
CRM_OBJECT	Reference to a CRM object type

Rows

Rows contain the actual data. Each row stores values for every column, keyed by column ID. Row IDs are portal-specific and must be remapped during cross-portal deployment.

Foreign Keys

Foreign key columns (FOREIGN_ID type) establish relationships between tables. The column definition includes a foreignTableId that points to the referenced table. Row values in foreign key columns contain row IDs from the referenced table.

Dependencies

HubDB tables can depend on:

• Other HubDB tables — Through foreign key columns. Table A may have a FOREIGN_ID column referencing Table B.
• Pages — Dynamic CMS pages can be powered by HubDB data. The page references the table, not the other way around.

When foreign key relationships exist between tables, all referenced tables must be included in the deployment for the references to be remapped correctly.

Deploy Behavior

Two-Phase Deployment

HubDB foreign keys create a chicken-and-egg problem: Table A references Table B, but both need to exist with valid row IDs before the references can be set. JetStack AI solves this with a two-phase approach:

Phase 1: Create rows WITHOUT foreign key values

1. All tables are created with their column definitions (foreign table IDs remapped to new target table IDs)
2. All rows are inserted into each table, but foreign key column values are left empty
3. Row ID mappings are recorded — for each table, the system tracks which source row ID maps to which newly created target row ID

Phase 2: Batch update rows WITH remapped foreign key values

1. Using the row ID mappings from Phase 1, all foreign key values are now resolved
2. Rows are batch-updated to populate the foreign key columns with the correct target row IDs

This two-phase strategy guarantees that all referenced tables and rows exist before any foreign key values are written.

Column Transformation

During deployment, several column properties are transformed:

• Foreign table ID remapping — The foreignTableId on foreign key columns is updated from the source table ID to the newly created target table ID
• Static option remapping — For SELECT and MULTISELECT columns, option IDs are remapped to match the target column’s option definitions. Option labels are used for matching.
• CRM object type remapping — CRM_OBJECT columns that reference custom object types have their object type IDs remapped to the target portal’s custom object type IDs

Row ID Mapping

Row IDs are portal-specific integers. When rows are created in the target portal, HubSpot assigns new IDs. JetStack AI maintains a mapping table per HubDB table that tracks sourceRowId -> targetRowId. This mapping is essential for Phase 2 foreign key resolution.

Table Publishing

After all rows are populated and foreign key values are set, JetStack AI publishes the table in the target portal only if the source table was in a published state. Draft tables remain as drafts in the target portal.

Large Table Pagination

For tables with many rows, HubSpot paginates the API response. JetStack AI handles pagination automatically during both import (fetching all rows) and deployment (batch creating/updating rows). There is no row count limit on what JetStack AI can process.

Edge Cases

foreignTableId Format Variations

The foreignTableId field appears in multiple formats across different HubSpot API versions and data representations:

Format	Example	Handling
Plain number	12345	Used directly
String	"12345"	Parsed to number
Object with id	{ id: 12345 }	Extracts .id property
Object with tableId	{ tableId: 12345 }	Extracts .tableId property

JetStack AI normalizes all these formats before remapping. Without this normalization, object-format values would serialize as [object Object] in the target table, corrupting the foreign key reference entirely.

Table Publishing Timing

Publishing must happen after Phase 2 completes. If the table is published after Phase 1 but before foreign key values are populated, the published version will have empty foreign key columns.

Troubleshooting

• “Missing foreign table mapping” — A foreign key column references a table that was not included in the deployment. Include all related HubDB tables in the same deployment batch.
• Row ID mismatches between phases — If Phase 1 partially fails (some rows created, others not), Phase 2 may encounter missing row IDs. Check the deploy log for Phase 1 row creation errors. A retry of the full deployment is recommended.
• Foreign key columns show empty after deploy — Phase 2 may have failed silently. Verify that the referenced table was deployed and that row mappings were established in Phase 1.
• [object Object] in foreign key values — The foreignTableId format was not recognized. This indicates a format variation that was not normalized. Report to support with the source table structure.
• Table shows as draft — The source table was in draft state, so the target table was also left as a draft. Publish manually in HubSpot if needed.