测试版从 PostgreSQL 或 MySQL 访问您的 HubSpot 数据

使用 PostgreSQL 和 MySQL 的“数据导出”功能，将选定的 HubSpot CRM 数据导出到您拥有的数据库中的表中。每次同步运行都会写入所选数据的完整快照，并替换之前的快照。同步完成后，您可以使用 SQL 或您偏好的 BI 和分析工具查询这些表，从而将 HubSpot 数据与其他业务数据相结合。

请注意：如果您是超级管理员，请将您的账户加入Data Studio 测试版，才能使用此功能。

了解限制与注意事项

在开始使用此功能之前，请确保充分了解需要提前采取的步骤，以及该功能的限制和使用该功能可能带来的后果。

• 每次同步都会用最新的快照替换目标表。HubSpot 不会保留之前的快照。
• 每个 HubSpot 账户中，每个对象、事件类型或关联对均可包含在一次定期 PostgreSQL 同步和一次定期 MySQL 同步中。这些同步彼此独立，也与其他 Data Out 提供商独立。
• 目前尚不支持敏感数据。可将敏感属性从导出中排除。
• 目前尚不支持对象特定表，例如OBJECTS_CONTACTS。
• 在 PostgreSQL 中，表名和列名区分大小写；在 MySQL 中，表名和列名可能区分大小写。编写查询前请仔细检查查询语法。

了解可导出的数据

您可以将以下数据从 HubSpot 同步到 PostgreSQL 或 MySQL：

• 对象：标准和自定义对象，例如联系人、公司、商机、工单和产品。
• 记录：所选对象的单个记录。
• 属性：记录中的选定属性值和属性历史记录。
• 关联：记录之间的选定关系，包括关联定义。
• 事件：选定的标准 HubSpot 事件和自定义行为事件，包括选定的事件属性。

不同对象的数据会在对象表中合并。读取对象表时，请使用OBJECTTYPEID筛选特定对象。例如，联系人的 ID 为0-1。自定义对象在创建时会被分配一个 ID，其格式为2-{unique_id}，例如2-12345。

了解导出格式

在设置过程中，您需要选择：

• 目标数据库。此项仅适用于 PostgreSQL。对于 MySQL，HubSpot 会自动创建数据库。
• 要同步的数据源：对象、事件、关联，或这些数据源的组合。
• 同步计划。

HubSpot 将数据导出为 Parquet 文件，并直接加载到您的数据库表中。PostgreSQL 和 MySQL 不使用客户自有的中转存储桶。HubSpot 会在内部管理中转过程。

在数据库中查找您的数据

HubSpot 会为每个数据源在 HubSpot 管理的模式中创建一个表，该模式以您的目标名称命名。您可以在同步的配置页面上找到确切的模式名称。

• PostgreSQL： <database>.hubspot_data_out_<destination-id>.<table-name>
• MySQL： hubspot_data_out_<destination-id>.<table-name>。在 MySQL 中，模式和数据库是同一概念，且由 HubSpot 自动创建。无需单独选择数据库层级。

例如，在 PostgreSQL 中：

• your_database.hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES
• your_database.hubspot_data_out_456.EVENTS_VISITED_PAGE
• your_database.hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

例如，在 MySQL 中：

• hubspot_data_out_456.OBJECT_WITH_OBJECT_PROPERTIES
• hubspot_data_out_456.EVENTS_VISITED_PAGE
• hubspot_data_out_456.ASSOCIATIONS_CONTACTS_TO_COMPANIES

每次同步都会用最新快照替换该表。HubSpot 不保留之前的快照。如果某张表在同步过程中出现故障，其先前数据将保留原位，直至下次同步成功。

表名和列名

表名和列名来源于导出的数据。PostgreSQL 的标识符长度限制为 63 个字符，MySQL 的标识符长度限制为 64 个字符。HubSpot 会将较长的名称缩短以符合限制。

标识符大小写

标识符的大小写区分重要。HubSpot 会创建所有表和列，其名称均用引号括起，并保留大写形式，与本文中的表名称一致。

• PostgreSQL：请完全按照示例所示，将名称用双引号括起来。PostgreSQL 会将未加引号的名称转换为小写，因此无法匹配。
• MySQL：请使用反引号，并严格遵循所示的大小写格式。表名是否区分大小写取决于您的服务器配置。

PostgreSQL 示例：

SELECT * FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES" WHERE "OBJECTTYPEID" = '0-1';

MySQL 示例：

SELECT * FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES` WHERE `OBJECTTYPEID` = '0-1';

列类型

列类型遵循导出数据，并与 PostgreSQL 和 MySQL 类型映射如下：

请注意： PROPERTIES表中的OBJECT_WITH_OBJECT_PROPERTIES列以 JSON 格式的字符串形式导出。它在 PostgreSQL 中存储为TEXT，在 MySQL 中存储为LONGTEXT，而非 JSON 列类型。有关查询示例，请参阅常见问题解答。

查看对象表

如果您选择对象数据，HubSpot 将导出以下表。

OBJECT_PROPERTIES

该表中每个属性值对应一行。要读取特定对象，请按OBJECTTYPEID 进行筛选。

OBJECT_WITH_OBJECT_PROPERTIES

该表中每条记录对应一行，所选属性值被归类到单个PROPERTIES列中。要读取特定对象，请按OBJECTTYPEID 进行筛选。

OBJECT_PROPERTIES_HISTORY

该表包含属性变更历史记录。与仅存储当前值的OBJECT_PROPERTIES 不同，该表针对属性的每个历史值都有一行记录。要查看单条记录和属性的完整时间线，请按UPDATEDAT 排序。

查看关联表

如果您选择了关联数据，HubSpot 将导出关联记录和关联定义。

ASSOCIATIONS

该表针对两个记录之间的每个选定关联，各包含一行数据。

ASSOCIATION_DEFINITIONS

此表中，每条选定的关联定义对应一行。

ASSOCIATIONS_<源对象>_TO_<目标对象>

对于选定的关联对，HubSpot 还可以导出特定于该关联对的关联表，例如ASSOCIATIONS_CONTACTS_TO_COMPANIES。这些表包含关联记录以及关联定义的元数据。

查看事件表

如果您选择了事件数据，HubSpot 会按事件类型导出一个表。表名采用EVENTS_<EVENT_NAME> 的格式，例如EVENTS_VISITED_PAGE。

每个事件表包含标准事件列以及针对每个所选事件属性的专属列。

管理同步计划

您可在 HubSpot 的设置过程中配置同步计划。您还可以从 HubSpot 手动触发重新同步。每次同步运行都会生成所选数据的完整快照。为控制数据量，请选择要包含的对象、事件、关联和属性。

请注意：在测试版期间，可能仅提供有限的同步频率选项，例如“一次”、“每 6 小时”、“每 12 小时”、“每日”、“每周”和“每月”。未来版本中可能会添加更多频率选项。

监控同步并处理错误

您可以在 HubSpot 中监控 PostgreSQL 和 MySQL 同步。同步可能处于以下任一状态：

当同步失败时：

• HubSpot 会显示“失败”状态，并提供按表细分的详细信息，说明哪些表成功或失败。
• 只有在 HubSpot 完成所有数据的加载后，表才会被更新，因此您永远不会看到部分加载的表。
• 如果某个表同步失败，其先前数据将保留原样，直至下次同步成功。
• 下次计划的同步将自动重新尝试进行完整同步。
• 您可以在 HubSpot 中随时手动触发重新同步。

在后续运行失败时，之前运行中已同步成功的表不会被修改。

常见问题

如何查询数据？

使用 SQL 查询目标模式中的表。

PostgreSQL

读取所有联系人记录：

SELECT * FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES" WHERE "OBJECTTYPEID" = '0-1';

从PROPERTIESJSON 列中读取特定属性。由于该列以文本形式存储，请先将其转换为 JSON 类型：

SELECT "OBJECTID", json_extract_path_text("PROPERTIES"::json, 'email') AS email FROM your_database.hubspot_data_out_456."OBJECT_WITH_OBJECT_PROPERTIES" WHERE "OBJECTTYPEID" = '0-1';

MySQL

读取所有联系人记录：

SELECT * FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES` WHERE `OBJECTTYPEID` = '0-1';

从PROPERTIESJSON 列中读取特定属性：

SELECT `OBJECTID`, JSON_EXTRACT(`PROPERTIES`, '$.email') AS email FROM `hubspot_data_out_456`.`OBJECT_WITH_OBJECT_PROPERTIES` WHERE `OBJECTTYPEID` = '0-1';

我可以在多次同步中导出同一种数据类型吗？

每个对象、事件类型或关联对，在每个 HubSpot 账户中最多可包含一个定期 PostgreSQL 同步和一个定期 MySQL 同步。这些同步彼此独立，也与其他数据导出提供商相互独立。例如，如果联系人已导出到一个定期 PostgreSQL 目标，则在将第一个同步归档之前，您无法将联系人添加到另一个定期 PostgreSQL 同步中。但您仍可同时将联系人导出到一个定期 MySQL 同步中。

是否支持特定对象的表？

不支持。目前尚不支持对象专用表（例如OBJECTS_CONTACTS）。请使用OBJECT_WITH_OBJECT_PROPERTIES并通过OBJECTTYPEID进行筛选，以获取特定对象的记录。

是否支持敏感数据？

不支持。Data Out 目前尚不支持敏感数据。导出时可将敏感属性排除在外。

HubSpot 会保留之前的快照吗？

不支持。每次同步都会用最新的快照替换目标表，因此不会保留之前的快照。