Cómo exportar datos de Klaviyo a Databricks

Objetivos del artículo

Descubre cómo configurar Databricks como un destino de sincronización saliente para que Klaviyo escriba continuamente los datos de perfiles, eventos y métricas en tablas Delta en tu propio espacio de trabajo de Databricks. Una vez conectado, tu equipo de datos puede combinar los datos de Klaviyo con el resto de tu lakehouse para análisis, modelado y elaboración de informes.

¿Quieres llevar datos a Klaviyo desde Databricks en su lugar? Consulta Conectar Klaviyo y Databricks.

Antes de empezar

Asegúrate de tener lo siguiente:

• Un espacio de trabajo de Databricks con Unity Catalog habilitado. Los espacios de trabajo solo con metastore de Hive no son compatibles. Si usas metastore de Hive, considera la federación del metastore de Hive.
• Un almacén de datos SQL que admite VARIANT columnas y tablas temporales con alcance de sesión para que Klaviyo pueda escribir datos. Se recomiendan los almacenes de datos SQL sin servidor; los almacenes Classic y Pro pueden tardar varios minutos en iniciarse, lo que puede retrasar las sincronizaciones.
• Permiso para crear esquemas, tablas y permisos en el catálogo que usarás (o ayuda de un administrador de Databricks).
• Permiso para administrar integraciones en Klaviyo.
• Direcciones IP salientes de Klaviyo en la lista de (entes, sitios, etc.) permitidos, si el espacio de trabajo restringe el tráfico entrante con listas de acceso de IP:
  • 184.72.183.187/32
  • 52.206.71.52/32
  • 3.227.146.32/32
  • 44.198.39.11/32
  • 35.172.58.121/32
  • 3.228.37.244/32
  • 54.88.219.8/32
  • 3.214.211.176/32

Paso 1: Crea un esquema para los datos de Klaviyo

En Databricks, los esquemas se encuentran dentro de un catálogo. Crea un esquema dedicado para almacenar las tablas en las que Klaviyo escribe. Los ejemplos de SQL de este artículo usan main como el catálogo y KLAVIYO_EXPORT como el esquema. Si usas nombres diferentes, reemplázalos en todos los ejemplos de SQL e ingresa los mismos nombres en Klaviyo durante el Paso 5.

USE CATALOG main;  -- or your organization's designated catalog
CREATE SCHEMA IF NOT EXISTS KLAVIYO_EXPORT;

Paso 2: Crear las tablas de destino

Ejecuta el siguiente script en el esquema que creaste en el paso 1. Klaviyo escribe en 3 tablas:

• klaviyo_profile: Una fila por perfil, incluidos los campos estándar, la ubicación y las propiedades personalizadas.
• klaviyo_event: Una fila por evento (por ejemplo, Placed Order u Opened Email), vinculada a un perfil y una métrica.
• klaviyo_metric: Una fila por métrica, usada para buscar el nombre de la métrica y la integración de origen para cada evento.

Las propiedades personalizadas del perfil y las propiedades de eventos se almacenan en columnas VARIANT, por lo que puedes consultar JSON anidado directamente sin administrar cientos de columnas individuales.

USE SCHEMA main.KLAVIYO_EXPORT;

CREATE TABLE klaviyo_profile (
  id                 STRING NOT NULL,
  external_id        STRING,
  email              STRING,
  phone_number       STRING,
  first_name         STRING,
  last_name          STRING,
  title              STRING,
  organization       STRING,
  properties         VARIANT,
  image              STRING,
  created            TIMESTAMP,
  updated            TIMESTAMP,
  location_address1  STRING,
  location_address2  STRING,
  location_city      STRING,
  location_country   STRING,
  location_latitude  STRING,
  location_longitude STRING,
  location_region    STRING,
  location_zip       STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_event (
  id               STRING NOT NULL,
  metric_id        STRING NOT NULL,
  profile_id       STRING,
  event_properties VARIANT,
  datetime         TIMESTAMP,
  uuid             STRING,
  PRIMARY KEY (id)
)
TBLPROPERTIES ('delta.feature.variantType-preview' = 'supported');

CREATE TABLE klaviyo_metric (
  id                   STRING NOT NULL,
  name                 STRING NOT NULL,
  integration_id       STRING,
  integration_name     STRING,
  integration_category STRING,
  created              TIMESTAMP,
  updated              TIMESTAMP,
  PRIMARY KEY (id)
);

Paso 3: Crear un principal de servicio y token de acceso

Klaviyo se autentica en Databricks con un token de acceso personal (PAT). Recomendamos crear una cuenta de servicio dedicada que se use solo para esta integración, en lugar de la cuenta de una persona.

1. Crea un service principal (o un usuario del espacio de trabajo) para Klaviyo.
2. Genera un token de acceso personal:
   • Servicio principal: Pide a un administrador del espacio de trabajo que cree el token inicial con la CLI de Databricks.
   • Usuario del espacio de trabajo: Crea un token en la IU de Databricks.
3. Guarda el token en un lugar seguro. Lo pegarás en Klaviyo en el paso 5.

Si ya creaste un principal de servicio para importar desde Databricks, puedes reutilizarlo. Solo agrega las concesiones de exportación en el paso 4.

Paso 4: Otorgar permisos

Concede al principal de servicio de Klaviyo acceso al catálogo, esquema y almacén de SQL. Reemplaza klaviyo_service_user con el ID de aplicación o nombre de usuario del principal de servicio.

GRANT USE CATALOG ON CATALOG main TO `klaviyo_service_user`;
GRANT USE SCHEMA, SELECT, MODIFY ON SCHEMA main.KLAVIYO_EXPORT TO `klaviyo_service_user`;

También da al principal de servicio el permiso Puede usar en el almacén de datos SQL que piensas usar. En Databricks, ve a SQL Warehouses, selecciona el almacén, haz clic en Permissions y agrega el service principal.

Verificar la configuración (opcional)

Con la misma identidad y token que le darás a Klaviyo, confirma las tablas y los permisos:

SHOW TABLES IN main.KLAVIYO_EXPORT;
SHOW GRANTS ON SCHEMA main.KLAVIYO_EXPORT;

Deberías ver las 3 tablas, y el principal de servicio debería aparecer con USE SCHEMA, SELECT y MODIFY.

Paso 5: Conectar Databricks en Klaviyo

1. En Klaviyo, ve a Avanzado > Administración de datos > Sincronización.
2. Si ya tienes una sincronización, haz clic en Crear sincronización.
3. Selecciona Exportar datos a tu almacén de datos.
4. Elige Databricks y luego haz clic en Conectar a Databricks.
5. Ingresa los detalles de la conexión:

Haz clic en Siguiente para configurar la sincronización.

También puedes encontrar Databricks en el marketplace de apps de Klaviyo. Para hacerlo, ve a Integraciones > Explorar apps y busca Databricks.

Paso 6: Configura la sincronización de datos

Elige lo que Klaviyo envía a Databricks y cuándo se sincroniza.

Objetos de datos

Elige sincronizar perfiles, eventos o ambos. Los datos de métricas se sincronizan junto con los eventos para que puedas consultar el nombre y la fuente de la métrica de cada evento.

Integraciones para excluir

Selecciona cualquier integración cuyos eventos no quieras que se envíen a Databricks. Esto solo aplica a los datos de eventos; no excluye los perfiles.

Sincronización selectiva

Selecciona las métricas cuyos eventos quieres sincronizar, como Pedido realizado. Deja Sincronización selectiva vacío para sincronizar todos los eventos de las integraciones que no hayas excluido. Este campo solo aparece si seleccionas el objeto de datos Eventos.

Cadencia de sincronización

En Cada, elige con qué frecuencia sincronizar los datos nuevos y actualizados: cada 1, 2, 4, 6, 12 o 24 horas. El valor predeterminado es 1 hora. Configura Fecha de inicio, Hora de inicio y zona horaria para el calendario.

Datos históricos

Elige cuántos datos históricos enviar durante la sincronización inicial:

• 30 días
• 90 días
• 1 año
• Cualquier momento

Paso 7: revisa, conecta y monitorea la sincronización

1. Haz clic en Siguiente para abrir Revisión. Verifica los detalles de la conexión, los datos compartidos, las integraciones excluidas, las métricas seleccionadas y el rango de sincronización inicial de datos.
2. Haz clic en Conectar. Klaviyo prueba la conexión y crea la exportación si la prueba se realiza correctamente.

Cuando la configuración se completa correctamente, Klaviyo muestra un mensaje de confirmación y te devuelve a Sincronizando. La exportación está habilitada y puedes supervisar ahí su estado de sincronización.

Si falla la prueba de conexión, revisa los detalles del error. Haz clic en Editar credenciales para corregir los detalles de la conexión y, luego, haz clic en Siguiente en la configuración de datos para volver a Revisar y haz clic en Conectar de nuevo.

Para monitorear la sincronización, ve a Avanzado > Administración de datos > Sincronización y haz clic en Databricks en la fila marcada como Exportar. Usa estas pestañas:

• Histórico: El estado del rellenado inicial.
• Periódico: El estado de las sincronizaciones según la cadencia que selecciones, incluida la vigencia de los datos (qué tan atrasadas están tus tablas de Databricks con respecto a Klaviyo).
• Configuración: ve y edita los detalles de la conexión, la selección de datos, la cadencia de sincronización y el rango histórico. Haz clic en Actualizar información en la sección que cambies para guardar.

Para obtener detalles sobre los estados de sincronización, pausar y reanudar sincronizaciones, y ver registros de errores, consulta Comprende la sincronización con el almacén de datos en Klaviyo.

Consulta los datos de Klaviyo en Databricks

Aquí tienes algunos ejemplos para empezar.

Cuenta eventos por nombre de la métrica en los últimos 7 días:

SELECT m.name AS metric, COUNT(*) AS events
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE e.datetime >= current_timestamp() - INTERVAL 7 DAYS
GROUP BY m.name
ORDER BY events DESC;

Lee una propiedad personalizada del perfil de la columna properties variante:

SELECT id, email, properties:loyalty_tier::STRING AS loyalty_tier
FROM main.KLAVIYO_EXPORT.klaviyo_profile
WHERE properties:loyalty_tier IS NOT NULL;

Obtener el valor del pedido a partir de eventos de Pedido realizado:

SELECT e.profile_id, e.datetime, e.event_properties:`$value`::DOUBLE AS order_value
FROM main.KLAVIYO_EXPORT.klaviyo_event e
JOIN main.KLAVIYO_EXPORT.klaviyo_metric m ON e.metric_id = m.id
WHERE m.name = 'Placed Order';

Guía de solución de problemas

Quitar una exportación de Databricks

Quitar la exportación detiene las sincronizaciones futuras. Los datos que ya se escribieron en las tablas de Databricks no se eliminan.

1. Ve a Integraciones en Klaviyo.
2. Abre el menú junto a la integración de exportación de Databricks y selecciona Eliminar integración.
3. Haz clic en Quitar integración en el cuadro de diálogo de confirmación.

Recursos adicionales

• Conexión de Klaviyo y Databricks (importación)
• Comprende la sincronización del almacén de datos en Klaviyo
• Primeros pasos con Advanced KDP