Ingesta de datos en la nube: editor SQL

Esta página explica cómo usar el editor SQL de la ingesta de datos en la nube (CDI) de Braze para crear y validar sincronizaciones con consultas SQL.

El editor SQL de la ingesta de datos en la nube te permite crear sincronizaciones escribiendo consultas SQL directamente en tu almacén de datos. Así ya no necesitas crear ni mantener una tabla CDI dedicada, algo que antes era obligatorio en el Paso 1.1 de las integraciones de almacén de datos.

Usa el editor SQL cuando quieras:

• Sincronizar datos sin modificar las tablas de origen
• Trabajar con datos sin procesar en tu almacén
• Evitar construir una columna PAYLOAD
• Gestionar casos de uso de datos más complejos con SQL

Requisitos previos y limitaciones

El editor SQL tiene las siguientes limitaciones:

• Disponible solo para orígenes de datos de almacén de datos: Snowflake, Redshift, BigQuery, Databricks y Fabric.
• Solo se admiten consultas de una única instrucción y de solo lectura.

Nota

Braze ejecuta únicamente consultas de solo lectura sobre tus datos y no modifica tus tablas subyacentes. Es posible que se creen objetos temporales durante la ejecución de la consulta, pero no se conservan.

Crear una nueva sincronización con el Editor SQL

Sigue estos pasos para crear primero una fuente y, después, una sincronización con el Editor SQL. Si ya configuraste una fuente para CDI, puedes pasar directamente al paso 3.

Nota

Ten en cuenta que estos pasos usan una fuente de Snowflake como ejemplo. El proceso de configuración para otras fuentes de almacén de datos es similar y lo encontrarás en el Paso 2: Crear una nueva fuente en el panel de Braze de la documentación Configurar integraciones de almacén de datos.

Paso 1: Configura tu rol, permisos, almacén y usuario de Snowflake

Antes de crear tu fuente de Snowflake en CDI, asegúrate de que el usuario de Snowflake que utiliza Braze tenga acceso a los datos que quieres consultar y a un almacén para ejecutar las consultas.

Paso 1.1: (Opcional) Crea una base de datos y un esquema

Si es necesario, crea una base de datos y un esquema dedicados para tus datos de CDI:

1
2

CREATE DATABASE BRAZE_CLOUD_PRODUCTION;
CREATE SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION;

Paso 1.2: Configura el rol y los permisos de la base de datos

Concede acceso a las tablas que quieres sincronizar:

1
2
3
4
5

CREATE ROLE BRAZE_INGESTION_ROLE;

GRANT USAGE ON DATABASE BRAZE_CLOUD_PRODUCTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT USAGE ON SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;
GRANT SELECT ON TABLE BRAZE_CLOUD_PRODUCTION.INGESTION.MY_USER_TABLE TO ROLE BRAZE_INGESTION_ROLE;

También puedes conceder acceso a varias tablas o a tablas futuras, según tu caso de uso. Por ejemplo, para conceder acceso a todas las tablas futuras de un esquema:

1

GRANT SELECT ON FUTURE TABLES IN SCHEMA BRAZE_CLOUD_PRODUCTION.INGESTION TO ROLE BRAZE_INGESTION_ROLE;

Paso 1.3: Configura el almacén y concede acceso al rol de Braze

Crea un almacén para que Braze ejecute las consultas:

1
2

CREATE WAREHOUSE BRAZE_INGESTION_WAREHOUSE;
GRANT USAGE ON WAREHOUSE BRAZE_INGESTION_WAREHOUSE TO ROLE BRAZE_INGESTION_ROLE;

Nota

El almacén debe tener activado el indicador de reanudación automática. Si no lo tiene, concede a Braze privilegios adicionales de OPERATE sobre el almacén para que Braze pueda activarlo cuando se ejecute la consulta.

Paso 1.4: Crea un usuario de Snowflake

Braze se autentica en Snowflake mediante Workload Identity Federation o un par de claves RSA. Las credenciales de par de claves RSA existentes siguen funcionando y no necesitas migrarlas. Sigue uno de los dos métodos. Usarás este usuario cuando configures tu fuente de Snowflake en Braze.

• workload identity federation
• key pair

1
2

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Paso 2: Crea una nueva fuente en el panel de Braze

En este paso, crea tu fuente de Snowflake en Braze y valida la conexión.

Paso 2.1: Añade una fuente de Snowflake

1. En el panel de Braze, ve a Configuración de datos > Ingesta de datos en la nube > Fuentes.
2. Selecciona Añadir origen de datos.
3. Selecciona Snowflake.

Paso 2.2: Introduce los datos de conexión

Elige un nombre para tu fuente e introduce tus credenciales y la configuración de Snowflake.

Nota

En el campo Localizador de cuenta de Snowflake, introduce tu identificador de cuenta de Snowflake, que suele tener un formato como xy12345.us-east-1.aws. No es lo mismo que el nombre de una base de datos o de un almacén.

Paso 2.3: Completa la autenticación

Selecciona Workload Identity Federation o Key pair para que coincida con el usuario del paso 1.4.

• workload identity federation
• key pair

1

ALTER USER BRAZE_INGESTION_USER SET RSA_PUBLIC_KEY='MIIBIjANBgkqhkiG9w0BA...';

De vuelta en Braze, selecciona Probar conexión para verificar el acceso a la fuente y, después, crea la fuente.

Paso 3: Crea una nueva sincronización y escribe tu consulta SQL

1. Ve a Configuración de datos > Ingesta de datos en la nube > Sincronizaciones.
2. Selecciona Crear sincronización de datos.
3. Elige cualquier sincronización en Tipo de datos.
4. Haz referencia a la fuente del paso 2.
5. Selecciona SQL y escribe una consulta SQL que devuelva datos de usuario de tu almacén. Tu consulta SQL define los datos que se sincronizan con Braze. El resultado de la consulta se convierte en el esquema de tu sincronización.

Puedes usar el Explorador de fuentes para buscar las tablas y vistas disponibles desde las que sincronizar, o el generador de SQL con IA para obtener la ayuda de Braze Operator con tu consulta SQL.

Nota

Solo se admiten consultas de solo lectura, incluidas las cláusulas JOIN. Para más detalles, consulta Restricciones de SQL.

Paso 4: Previsualiza y valida tu consulta

Selecciona Vista previa y validación para ejecutar tu consulta.

La vista previa:

• Muestra los resultados en formato de tabla
• Muestra hasta 100 filas
• Muestra hasta 250 columnas

Para validarse correctamente, tu consulta SQL debe devolver varias columnas obligatorias:

Las columnas adicionales que no son obligatorias se sincronizan como atributos, propiedades de contexto de Canvas, propiedades del evento, campos del catálogo y campos de la cuenta, respectivamente. Consulta Comportamiento de la validación y Solución de problemas para obtener consejos útiles sobre los errores de vista previa y validación y cómo solucionarlos.

Paso 5: Revisa el mapeado de atributos y crea la sincronización

Cuando la validación se complete correctamente, continúa a Siguiente: Notificaciones y crea tu sincronización.

Importante

Una configuración SQL incorrecta puede provocar resultados no deseados, como un consumo excesivo de puntos de datos y riesgos operativos más amplios. Eres responsable de asegurarte de que la lógica de tu consulta sea correcta y debes revisar con atención la vista previa de todos los resultados antes de activar una sincronización.

Restricciones SQL

Usar solo consultas SELECT

Solo se admiten consultas de solo lectura.

Puedes usar:

• SELECT
• WITH (CTEs)
• JOIN

No puedes usar:

• INSERT, UPDATE o DELETE
• CREATE o DROP
• Múltiples sentencias separadas por ;

Usar una sola sentencia

Tu consulta debe ser una sola sentencia ejecutable.

Comportamiento de validación

El editor SQL valida tu consulta antes de permitirte continuar.

Errores SQL

Si tu consulta contiene errores de sintaxis:

• La validación falla
• No aparece vista previa
• Tu almacén devuelve un mensaje de error

Errores de compilación

Si tu consulta hace referencia a tablas, columnas u objetos no válidos o no autorizados:

• La validación falla
• No aparece vista previa
• Tu almacén devuelve un mensaje de error

Errores de conexión

Si Braze no puede conectarse a tu almacén:

• La validación falla
• No aparece vista previa
• Aparece un mensaje de error de conexión

Tiempo de espera de consulta agotado

Si tu consulta tarda demasiado en ejecutarse:

• Braze termina la consulta
• La validación falla
• Aparece un error de tiempo de espera agotado

Errores de esquema de tabla

Si tu consulta compila, la validación aún puede fallar si:

• No se encuentra una columna de identificador
• Falta UPDATED_AT
• Faltan otras columnas obligatorias

En este caso, la vista previa sigue apareciendo para ayudarte a avanzar hacia una validación exitosa. Consulta el Paso 4 en la sección anterior para obtener detalles sobre las columnas obligatorias para cada tipo de datos de sincronización.

Resultados con cero filas

Si tu consulta devuelve cero filas:

• La validación pasa
• Aún puedes crear la sincronización
• No se actualizan usuarios hasta que se devuelvan filas

Compatibilidad con PAYLOAD (heredada)

El Editor SQL admite tablas CDI heredadas en las que hay una columna PAYLOAD.

Si tu consulta incluye:

• Un identificador válido
• UPDATED_AT
• Una columna PAYLOAD
• Columnas adicionales

Entonces:

• Braze sincroniza solo la columna PAYLOAD
• Braze ignora las columnas adicionales

Editar una sincronización SQL

Cuando editas una sincronización existente:

• Cualquier cambio en SQL requiere una nueva validación
• No puedes guardar cambios no válidos
• Los cambios válidos se aplican después de guardarlos

Si ya hay una ejecución de sincronización en curso, tus cambios se aplicarán en la próxima ejecución.

Solución de problemas

Esta sección incluye errores comunes y orientación sobre cómo solucionarlos.

“Vista previa no disponible”

Cuando veas “No preview available” (Vista previa no disponible), la causa puede ser uno de los siguientes tipos de error subyacentes.

“Se requiere una columna de identidad”

Asegúrate de que tu consulta incluya un identificador válido, como external_id.

“Falta la columna UPDATED_AT”

Añade una columna de marca de tiempo para la sincronización incremental.

“Añade más columnas… No hay atributos/campos de catálogo/campos de cuenta para sincronizar”

Añade al menos una columna adicional además del identificador y UPDATED_AT.

“Se agotó el tiempo de espera de ejecución de la consulta”

Optimiza tu consulta o usa un almacén más grande.