Conectar Klaviyo y Snowflake

Usamos el término "tabla" para los propósitos de este artículo; pero las vistas, vistas materializadas y tablas son todos objetos Snowflake válidos que se puede importar. A condición de que Klaviyo pueda ejecutar SELECT col1 FROM table_name en el objeto, eres libre de usar lo que prefieras. 

Las palabras clave "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", y "OPTIONAL" de este documento se deben interpretar como se describe en RFC 2119.

Configuración del administrador de Snowflake

En esta sección se describen los pasos que debes seguir en tu entorno Snowflake para que Klaviyo pueda importar tus datos. 

1. Genera una clave privada ejecutando el comando siguiente en tu terminal local:

openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt

2. Genera una clave pública que haga referencia a la clave privada ejecutando el comando siguiente en tu terminal:

openssl rsa -in clave_rsa.p8 -pubout -out clave_rsa.pub

3. Copia el archivo rsa_key.pub y pégalo en el script que aparece abajo para sustituir el valor del marcador de posición 'GENERATE_PUBLIC_KEY' de user_rsa_public_key. El script siguiente funcionará para los usuarios de Mac, o si lo prefieres puedes abrir rsa_key.pub en un IDE y copiar el contenido completo del archivo. 

Comando # de terminal Mac para escribir la clave en tu terminal y copiarla al portapapeles
cat rsa_key.pub | tee /dev/tty | pbcopy

4. Ejecuta el script siguiente en tu entorno de Snowflake en la creación de un usuario de servicio para que lo use Klaviyo. Debes tener privilegios de securityadmin y sysadmin para que puedas completar la configuración indicada abajo. A fin de revisar qué roles tienes, ejecuta SHOW GRANTS TO USER <your_username> y cerciórate de que tienes ambos roles en la lista. Ponte en contacto con un administrador de sistema si necesitas que ajusten tu rol.
   1. Siéntete en libertad de actualizar cualquiera de las variables establecidas al comienzo del script.
   2. En resumen:
      1. Elegirás un almacén existente o crearás uno nuevo
      2. Elegirás una base de datos existente o crearás una nueva para albergar los nuevos esquemas
      3. Crearás dos nuevos esquemas, KLAVIYO_TMP y KLAVIYO_IMPORT_FROM_DWH
      4. Crearás una nueva política de red y lista de permisos de IP de Klaviyo
      5. Crearás un usuario y un rol para Klaviyo
   3. Este script es idempotente (se puede ejecutar con seguridad repetidas veces); pero no sobreescribirá los objetos existentes con nombres conflictivos. 

BEGIN;

-- crea variables para usuario / contraseña / rol / almacén / base de datos. 
-- Cámbialos por lo que prefieras.
SET role_name = 'KLAVIYO_DATA_TRANSFER_ROLE'; -- todas las letras deben ser mayúsculas, ej. 'KLAVIYO_DATA_TRANSFER_ROLE'
SET nombre_usuario = 'KLAVIYO_DATA_TRANSFER_USER'; -- todas las letras deben ser mayúsculas, ej. 'KLAVIYO_DATA_TRANSFER_USER'
SET nombre_almacén = 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'; -- todas las letras deben ser mayúsculas, ej. 'KLAVIYO_DATA_TRANSFER_WAREHOUSE'
SET nombre_base_de_datos = 'KLAVIYO_DATABASE'; -- todas las letras deben ser mayúsculas, ej. 'BASE_DE_DATOS_KLAVIYO'. Si esta base de datos no existe, se creará una nueva.
SET network_policy = 'KLAVIYO_DATA_TRANSFER_NETWORK_POLICY'; -- todas las letras deben ser mayúsculas, ej. 'KLAVIYO_NETWORK_POLICY'
SET network_rule = 'KLAVIYO_DATA_TRANSFER_NETWORK_RULE'; -- todas las letras deben ser mayúsculas, ej. 'KLAVIYO_NETWORK_RULE'
/* sustituye GENERATE_PUBLIC_KEY a continuación por la clave pública generada */

-- NO CAMBIAR
SET nombre_esquema_tmp = $nombre_base_de_datos || '.KLAVIYO_TMP'; -- NO CAMBIAR
SET nombre_esquema_import = $nombre_base_de_datos || '. KLAVIYO_IMPORT_FROM_DWH'; -- NO CAMBIAR
SET nombre_de_red_completa_tmp = $nombre_del_esquema_tmp || '.' || $regla_red; -- NO CAMBIAR
SET_regla_red_completa_import = $nombre_del_esquema_import || '.' || $regla_red; -- NO CAMBIAR


-- cambiar el rol a sysadmin para los pasos de almacén / base de datos
USE ROLE sysadmin;

-- crear un almacén para el servicio de transferencia de datos
CREATE WAREHOUSE IF NOT EXISTS IDENTIFIER($nombre_almacén)
 tamaño_almacén = xpequeño
 tipo_almacén = estándar
 auto_suspender = 60
 auto_reanudar = verdadero
 inicialmente_suspendido = verdadero;

-- crear la base de datos para el servicio de transferencia de datos
CREATE DATABASE IF NOT EXISTS IDENTIFIER($nombre_base_datos);

-- crear esquemas para el servicio de transferencia de datos
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($nombre_esquema_tmp);
CREAR ESQUEMA SI NO EXISTE IDENTIFICADOR($nombre_esquema_importar);

-- cambiar el rol a securityadmin para los pasos de usuario / rol
USE ROLE securityadmin;

-- crear red  regla y política para la base de datos
GRANT USAGE ON DATABASE IDENTIFIER($nombre_base_datos) TO ROLE securityadmin;
GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($nombre_esquema_tmp) TO ROLE securityadmin;
GRANT USAGE, CREATE NETWORK RULE ON SCHEMA IDENTIFIER($nombre_del_esquema_import) TO ROLE securityadmin;

-- whitelist Klaviyo ip ranges, for KLAVIYO_TMP schema 
CREATE NETWORK RULE IF NOT EXISTS IDENTIFIER($full_network_rule_tmp)
 type = IPV4
 value_list = (
 '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'
 )
 comment = 'Klaviyo Rangos IP a partir de abril de 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
 allowed_network_rule_list = ($full_network_rule_tmp);

-- lista blanca Klaviyo rangos ip, para el esquema KLAVIYO_IMPORT_FROM_DWH 
CREATE NETWORK RULE IF NOT EXISTS IDENTIFIER($full_network_rule_import)
 type = IPV4
 value_list = (
 '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'
 )
 comment = 'Klaviyo IP Ranges as of April 2025';
CREATE NETWORK POLICY IF NOT EXISTS IDENTIFIER($network_policy)
allowed_network_rule_list = ($full_network_rule_import);


-- crear un rol para el servicio de transferencia de datos
CREATE ROLE IF NOT EXISTS IDENTIFIER($nombre_role);
GRANT ROLE IDENTIFIER($nombre_role) TO ROLE sysadmin;

-- crea un usuario para el servicio de transferencia de datos
CREATE USER IF NOT EXISTS IDENTIFIER($nombre_usuario)
 type = SERVICE
 network_policy = $network_policy
 default_role = $nombre_role
 default_warehouse = $nombre_almacén
 rsa_public_key = 'GENERATE_PUBLIC_KEY';
GRANT ROLE IDENTIFIER($nombre_role) TO USER IDENTIFIER($nombre_usuario);
ALTER USER IDENTIFIER($nombre_usuario) SET NETWORK_POLICY = $network_policy;

-- grant service role access to warehouse
GRANT USAGE
 ON WAREHOUSE IDENTIFIER($nombre_almacén)
 TO  ROLE IDENTIFIER($nombre_del_role);

-- concede acceso de servicio a la base de datos
GRANT monitorear, USAGE
 ON DATABASE IDENTIFIER($nombre_de_la_base_de_datos)
 TO ROLE IDENTIFIER($nombre_del_role);

-- Concede privilegios para KLAVIYO_TMP 
GRANT USAGE ON SCHEMA IDENTIFIER($nombre_del_esquema_tmp) TO ROLE IDENTIFIER($nombre_del_role);
GRANT monitorar, USAGE, CREATE TABLE, CREATE VIEW, CREATE SEQUENCE, CREATE FUNCTION, CREATE PROCEDURE
 ON SCHEMA IDENTIFIER($nombre_del_esquema)
 TO ROLE IDENTIFIER($nombre_del_role);
GRANT ALL ON FUTURE TABLES IN SCHEMA IDENTIFIER($nombre_del_esquema) TO ROLE IDENTIFIER($nombre_del_role);

-- Concede privilegios para KLAVIYO_IMPORT_FROM_DWH
GRANT USAGE ON SCHEMA IDENTIFIER($nombre_del_esquema) TO ROLE IDENTIFIER($nombre_del_role);
GRANT SELECT
 ON FUTURAS TABLAS
 EN SCHEMA IDENTIFIER($nombre_esquema_importacion)
 TO ROLE IDENTIFIER($nombre_role);

COMMIT;

Configuración de datos de Snowflake

Arriba creaste dos esquemas nuevos. 

• KLAVIYO_TMP será usado exclusivamente por Klaviyo. NO DEBES modificar ninguna tabla creada en este esquema. Klaviyo eliminará estas tablas cuando ya no sean necesarias.
• KLAVIYO_IMPORT_FROM_DWH es donde debes guardar tus tablas finales para que Klaviyo las importe. Cuando realices el proceso de crear la sincronización, aparecerán todas las tablas de este esquema para que puedas elegir entre ellas. Por lo tanto, sólo DEBES guardar las tablas finales que quieras importar, para evitar confusiones durante la configuración. 

Todas las tablas que el plan importe a Klaviyo deben cumplir los criterios siguientes. 

Requisitos de marca de tiempo 

1. Las tablas DEBEN contener un campo de marca de tiempo que indique cuándo se creó o actualizó la fila. Será frecuentemente insert_at o updated_at. Lo establecerás para cada tabla durante el proceso de crear la sincronización.
   1. El campo de marca de tiempo DEBE ser monotónicamente creciente (es decir, siempre debe aumentar o mantenerse igual, y nunca disminuir).
   2. Después de creada la sincronización, NO DEBES establecer el valor de la marca de tiempo de una fila en el pasado, o Klaviyo podría no seleccionar dicha fila.
   3. La zona horaria de este campo en particular no es importante para Klaviyo, siempre que sigas los requisitos indicados arriba
   4. Klaviyo RECOMIENDA que establezcas el campo de marca de tiempo con CURRENT_TIMESTAMP() o una función equivalente. Varias filas pueden tener la misma marca de tiempo. Ve el ejemplo siguiente. 

INSERT INTO table_name AS 

SELECT ... 

    , CURRENT_TIMESTAMP() AS inserted_at

... 

2. Tus marcas de tiempo DEBEN estar en UTC o incluir información sobre la zona horaria. Si falta información sobre la zona horaria, Klaviyo supondrá que es UTC. En el caso de propiedades personalizadas, estas marcas de tiempo permanecen en formato de cadena, lo que te permite interpretarlas en tu zona horaria preferida.

Estructura de la tabla 

3. Las tablas se DEBEN tratar como "solo añadir" (también conocidas como "sólo insertar")
   1. Si en vez de ello prefieres actualizar las filas en su lugar, DEBES actualizar el campo de marca de tiempo, para que Klaviyo pueda identificar el cambio.
4. Las tablas DEBEN estar ordenadas con base en tu columna de marca de tiempo. Snowflake se encargará de su agrupamiento y partición con base en tu orden de inserción. Esto ayudará a optimizar las consultas de importación de Klaviyo, manteniendo bajos los costos de computación en Snowflake

Singularidad y uniformidad del perfil 

5. DEBES cerciorarte de que cada propiedad del perfil se importe de una sola fuente de datos (tabla). Klaviyo impide seleccionar la misma propiedad de diferentes tablas durante la creación de la sincronización, simplificando este requisito.
6. DEBES usar los mismos identificadores de perfil (correo electrónico, número de teléfono, ID externa, etc.) en todas tus tablas de importación, para minimizar el riesgo de que se creen perfiles duplicados.
   1. Klaviyo creará un nuevo perfil si el identificador de perfil que proporcionas no coincide con un perfil ya existente en Klaviyo.
   2. Ejemplo: Table1 (Email, fav_color) + Table2 (Teléfono, cumpleaños)
      1. Esto podría crear 2 perfiles para la misma persona si el perfil no existe actualmente. Si existe un perfil, Klaviyo gestionará internamente la resolución del perfil y las actualizaciones. 
   3. Una forma de evitar este problema es emplear una sola tabla de importación para todos tus perfiles. 

Prevención del bucle circular de importación-exportación 

7. DEBES gestionar cuidadosamente las situaciones en las que se usan las funciones de importación y exportación, para evitar bucles circulares de importación-exportación. Cerciórate de que tu proceso de exportación no retroalimente datos a una tabla de un paso previo a tu tabla de importación, ya que Klaviyo no detecta actualmente tal situación.
   1. Klaviyo todavía no cuenta con la lógica para detectar dicha situación.
   2. Esto sería algo así como:
      1. En cada ciclo de sincronización de exportación, Klaviyo exportará todos tus perfiles
      2. Luego, agregas todos los perfiles exportados a tu tabla de importación mediante una serie de transformaciones.
      3. En cada ciclo de sincronización de importación, Klaviyo leerá todos los perfiles de tu tabla de importación, que en última instancia se reexportarán
   3. Situaciones en las que esto probablemente sea seguro 
      1. Si sólo usas la tabla de exportación para restringir las filas agregadas a tu tabla de importación
      2. Si compruebas que la tabla de exportación no agrega filas a tu tabla de importación.
   4. ¿Cuáles son las consecuencias de un bucle circular de importación-exportación?
      1. Esto causará costos de computación innecesarios para ti y para Klaviyo.