Skip to content

Ingesta de datos de Cloud: editor SQL

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

El editor SQL de Ingesta de datos de Cloud te permite crear sincronizaciones escribiendo consultas SQL directamente contra tu almacén de datos. Esto elimina la necesidad de crear o mantener una tabla CDI dedicada, que antes era obligatoria en el Paso 1.1 de 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
  • Manejar 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 almacén de datos: Snowflake, Redshift, BigQuery, Databricks y Fabric.
  • Solo se admiten consultas de solo lectura de una sola sentencia.

Crear una nueva sincronización con el editor SQL

Sigue estos pasos para crear primero un origen y luego una sincronización con el editor SQL. Si ya configuraste un origen para CDI, puedes ir directamente al paso 3.

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

Antes de crear tu origen de Snowflake en CDI, asegúrate de que el usuario de Snowflake que usa Braze tenga acceso a los datos que quieres consultar y un almacén para ejecutar 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

Otorga 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 otorgar acceso a múltiples tablas o tablas futuras, según tu caso de uso. Por ejemplo, para otorgar acceso a todas las tablas futuras en 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 otorga acceso al rol de Braze

Crea un almacén para que Braze ejecute consultas:

1
2

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

Paso 1.4: Crea un usuario de Snowflake

Crea un usuario para Braze y asigna el rol:

1
2

CREATE USER BRAZE_INGESTION_USER;
GRANT ROLE BRAZE_INGESTION_ROLE TO USER BRAZE_INGESTION_USER;

Usarás este usuario cuando configures tu origen de Snowflake en Braze.

Paso 2: Crea un nuevo origen en el panel de Braze

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

Paso 2.1: Añade un origen de Snowflake

  1. En el panel de Braze, ve a Configuración de datos > Ingesta de datos de Cloud > Fuentes.
  2. Selecciona Add data source.
  3. Selecciona Snowflake.

Paso 2.2: Introduce los detalles de conexión

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

Paso 2.3: Completa la configuración de la clave RSA

Después de introducir tus credenciales y configuración, selecciona Save credentials y genera una clave RSA. Luego vuelve a Snowflake para completar la configuración. Añade la clave pública que se muestra en el dashboard al usuario que creaste para que Braze se conecte a Snowflake.

Para más información, consulta Autenticación por par de claves de Snowflake. Si quieres rotar las claves en algún momento, Braze puede generar un nuevo par de claves y proporcionar la nueva clave pública.

1

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

De vuelta en Braze, selecciona Test connection para verificar el acceso al origen y luego crea el origen.

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

  1. Ve a Configuración de datos > Ingesta de datos de Cloud > Syncs.
  2. Selecciona Create data sync.
  3. Elige cualquier sincronización en Data Type.
  4. Haz referencia al origen 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 orígenes para examinar las tablas y vistas disponibles para sincronizar, o el generador de SQL con IA para obtener la ayuda de Braze Operator en tu consulta SQL.

Paso 4: Previsualiza y valida tu consulta

Selecciona Preview and validate para ejecutar tu consulta.

La vista previa:

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

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

Tipo de datos de sincronización Columnas obligatorias
Atributos - Un identificador de usuario, uno de external_id, braze_id, alias_name y alias_label, correo electrónico o número de teléfono.
- UPDATED_AT.
- Al menos una columna adicional (atributo) para sincronizar.
Eliminar usuarios - Un identificador de usuario, uno de external_id, braze_id, alias_name y alias_label, correo electrónico o número de teléfono.
- UPDATED_AT.
Canvas Triggers - Un identificador de usuario, uno de external_id, braze_id, alias_name y alias_label, correo electrónico o número de teléfono.
- UPDATED_AT.
Eventos personalizados - Un identificador de usuario, uno de external_id, braze_id, alias_name y alias_label, correo electrónico o número de teléfono.
- UPDATED_AT.
- NAME para representar el nombre del evento.
- TIME para representar la hora del evento. Si no está disponible, CDI usa UPDATED_AT como sustituto.
Eventos de compra - Un identificador de usuario, uno de external_id, braze_id, alias_name y alias_label, correo electrónico o número de teléfono.
- UPDATED_AT.
- PRODUCT_ID.
- CURRENCY.
- PRICE.
- TIME para representar la hora del evento de compra. Si no está disponible, CDI usa UPDATED_AT como sustituto.
Catálogo - ID para representar el identificador del elemento del catálogo.
- UPDATED_AT.
- Al menos una columna adicional (campo de catálogo) para sincronizar.
Cuentas - ID para representar el identificador de la cuenta.
- NAME para representar el nombre de la cuenta.
- UPDATED_AT.
- Al menos una columna adicional (campo de cuenta) para sincronizar.

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

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

Cuando la validación sea exitosa, continúa a Next: Notifications y crea tu 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 (legado)

El editor SQL es compatible con tablas CDI legadas donde hay una columna PAYLOAD presente.

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

Al editar una sincronización existente:

  • Cualquier cambio en SQL requiere revalidación
  • No puedes guardar cambios no válidos
  • Los cambios válidos surten efecto después de guardar

Si ya hay una ejecución de sincronización en curso, tus cambios surten efecto en la siguiente ejecución.

Solución de problemas

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

Vista previa no disponible

Cuando ves “Vista previa no disponible”, uno de los siguientes tipos de error subyacentes puede estar causándolo.

Tipo de error Pasos para resolver
“No preview available” Lee el banner de error para obtener pistas.
“Unable to connect to the source” Verifica el nombre de usuario configurado, el localizador de cuenta y la configuración de autenticación por par de claves RSA.
Verifica que el almacén esté en ejecución.
Confirma el acceso a la red.
“SQL syntax error” Revisa tu sintaxis SQL.
“Object does not exist or not authorized” Asegúrate de que el rol tenga acceso SELECT a la tabla.
Confirma los permisos de base de datos y esquema.
Verifica errores tipográficos en el nombre de la tabla.

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.
New Stuff!