Skip to content

Create and populate HubDB tables

Last updated: February 29, 2024

Available with any of the following subscriptions, except where noted:

Marketing Hub Enterprise
CMS Hub Professional, Enterprise

HubDB is a relational database that allows you to create tables with flexible schema to store data you can use on your website pages, or query externally via the HubDB API.

Please note: to use HubDB data to create dynamic pages, you need CMS Hub Professional or Enterprise.

Create a table

  • In your HubSpot account, navigate to Marketing > Files and Templates > HubDB
  • In the upper right, click Create table.
  • In the dialog box, enter a Table label and Table name. You cannot change the name of a table after you create it.
  • Click Create.

create-hubdb-table-dialog-box

Add and edit table data

Edit a HubDB tables directly in your HubSpot account or upload a CSV to automatically merge in existing data with your table rows.

Add a custom table column

  • On the HubDB dashboard, click the label of one of your tables.
  • In the upper right, click Actions, then select Add column.
  • In the dialog box, configure your column:
    • Enter a Column label.
    • Enter a Column name. You can use this name to query your data with the HubDB API.
    • Enter a Column description. This description will appear when a user hovers over the info info icon next to the column name. 
    • Enter a Column type.
  • Click Add column.
  • To modify or remove a column, hover over it and click the arrow icon, then select Edit or Remove.

edit-or-remove-hubdb-column

Add table rows

  • On the HubDB dashboard, click an existing table's label.
  • In the upper right, click Actions, then select Add row.
  • A new row will be automatically created beneath any existing rows. Enter a value for each column you've configured for the table.
  • To clone or remove a row, hover over the row's ID and click the downCaratarrow icon, then select Clone or Remove.

Import table data via a CSV

If you have an existing spreadsheet with data that matches your HubDB table schema, you can import it into HubSpot to automatically merge its data with your table.

Please note:

  • To import an image into a HubDB table, add the image's URL to the CSV file. To set dimensions for the image, add the width and height to the end of the URL, offset by commas. For example: http://www.hubspot.com/sample-image.jpg,100,300. 
  • Imported dates must use MM/DD/YYYY formatting. For example, November 6th, 2022 would be 11/06/2022. 

  • On the HubDB dashboard, click the label of one of your tables.
  • In the upper right, click Actions, then select Import.
  • Click the Addor Replace tile:
    • Add: rows from your spreadsheet will be added to your existing data.
    • Replace: rows from your spreadsheet will overwrite and replace any existing data in your table.
  • Click Next.
  • Click Choose file.
  • Browse your computer's hard drive for the CSV to upload and click Open.
  • By default, HubSpot will detect the encoding of the data in your CSV. To manually specify the data encoding:
    • Click Advanced options.
    • Click the Customize data encoding dropdown menu, then select an encoding.
  • Click Next.
  • Specify how you want to map each field from your CSV to the corresponding HubDB table column:
    • Click the HubDB Table Column dropdown menu, then select a column.
    • If you haven't configured an associated column for the CSV field, click Add column. In the dialog box, enter a label, name, and select a type. When you're done, click Add column.
  • Click Import.

map-csv-fields-to-hubdb-columns

  • When your import is complete, click Done.

Manage table settings (CMS Hub Professional and Enterprise only)

If you have a CMS Hub Professional or Enterprise account, you can manage settings for each HubDB table, such as whether the table is publicly accessible via API and whether the data can be used to create dynamic pages.

  • In your HubSpot account, navigate to Marketing > Files and Templates > HubDB.
  • Click the name of a table.
  • In the upper right, click ActionsManage settings

    hubdb-table-manage-settings
  • In the right sidebar, configure the table's settings:
    • Allow public API access: by default, the table's data can only be accessed in HubSpot, through HubL, or with authenticated API calls. Turn this setting on to enable unauthenticated API calls to query the table's data. To query the data, you'll need to include the HubSpot account ID in a portalId query parameter.
    • Enable creation of dynamic pages using row data: turn this setting on to enable the creation of dynamic pages using HubDB data. You can then configure the following additional options:
      • Use the dropdown menus to select which columns will populate dynamic pages with meta description, featured image, and canonical URL data. For new tables, you'll need to create new columns to contain this data.
        • Meta description: must be a text type column.
        • Featured image: must be an image type column.
        • Canonical URL: must be a URL type column.
      • Allow use of child tables: turn this setting on to allow references to other HubDB tables in this table. You can also select the Automatically create listing pages for child tables setting to enable HubSpot to automatically create intermediate listing pages. Learn more about building multilevel dynamic pages using HubDB.

        Please note: a parent table cannot reference a child table that also references the parent table. This will create a loop that results in an error when trying to select the child table within the parent table.

  • Click Save.

Publish tables

When you finish populating your HubDB table with data, you can publish it to use on your website pages and make it accessible to query via the HubSpot API.

  • In the upper right, click Publish.
  • In the dialog box, confirm that you're ready to take your table public, then click Publish.

Export table data

  • On the HubDB dashboard, click the label of one of your tables.
  • In the upper right, click the Actions dropdown menu and select Export, then select a file format. The HubDB data will begin downloading immediately.

Please note: images exported from a HubDB table will be formatted as image URLs. If the image's dimensions have been customized, they will appear at the end of the URL. 

View table dependents

Once a table has been created, you can view where a HubDB table is being used in your content from the HubDB dashboard. In addition, when deleting a HubDB table, HubSpot will warn you if the table is currently being used by any assets.

To view assets that are using a HubDB table, on the HubDB dashboard, click the Actions dropdown menu next to a table, then select Show dependents.

hubdb-view-dependents-cropped

Learn more about HubDB in HubSpot's developer documentation.

Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.