Referencia del conector basado en consultas

Esta página contiene documentación de referencia para conectores basados en consultas en Lakeflow Connect, incluidos parámetros de configuración, requisitos de columna de cursor, sintaxis de seguimiento de eliminación y condiciones de error.

Configuración de canalización

Se admiten los parámetros siguientes para los conectores basados en consultas. Establezca estos valores en el bloque de la ingestion_definition configuración de la canalización.

Parámetro	Tipo	Obligatorio	Descripción
connection_name	cuerda / cadena	Necesario para la ingesta de conexiones externas	Nombre de la conexión que almacena las credenciales de autenticación para la base de datos de origen. Si ingest_from_uc_foreign_catalog es true, no especifique connection_name.
ingest_from_uc_foreign_catalog	boolean	Necesario para la ingesta de catálogos externos	Establézcalo en true para ingerir desde un catálogo externo respaldado por Lakehouse Federation. Si truees , no especifique connection_name.
source_catalog	cuerda / cadena	Sí	Catálogo en el sistema de origen (o el nombre del catálogo externo si ingest_from_uc_foreign_catalog es true).
source_schema	cuerda / cadena	Sí	Esquema del sistema de origen desde el que se va a ingerir.
source_table	cuerda / cadena	Necesario para objetos de nivel de tabla	Tabla del esquema de origen que se va a ingerir.
cursor_column	cuerda / cadena	Necesario para la ingesta de conexiones externas	Nombre de la columna de cursor que se va a usar para el seguimiento incremental. Debe ser una sola columna que aumenta de forma monotónica. Consulte Requisitos de columna de cursor.
cursor_columns	lista de cadenas	Necesario para la ingesta de catálogos externos	Lista que contiene el nombre de la columna de cursor. Solo se admite una columna.
primary_keys	lista de cadenas	Necesario a menos que el modo de seguimiento del historial (SCD) sea APPEND_ONLY (ingesta de catálogos externos)	Columnas de clave principal usadas para identificar las filas de las operaciones de combinación. Obligatorio para SCD_TYPE_1 los modos y SCD_TYPE_2 .
deletion_condition	cuerda / cadena	No	Expresión SQL que se evalúa true como para las filas que representan eliminaciones parciales. Solo se puede configurar mediante la API. Consulte Condición de eliminación.
hard_deletion_sync_min_interval_in_seconds	entero	No	Intervalo mínimo en segundos entre los exámenes de instantáneas de clave principal para detectar eliminaciones duras. Si no se establece, el seguimiento de eliminación máxima está deshabilitado. Este parámetro no se admite cuando scd_type es SCD_TYPE_2. Solo se puede configurar mediante la API (Beta). Consulte Seguimiento de eliminación dura.
scd_type	cuerda / cadena	No	Modo de seguimiento del historial (SCD) de la tabla de destino. Valores admitidos: SCD_TYPE_1 (valor predeterminado), SCD_TYPE_2, APPEND_ONLY.
destination_catalog	cuerda / cadena	Sí	Catálogo en el que se va a escribir la tabla de destino.
destination_schema	cuerda / cadena	Sí	Esquema en el que se va a escribir la tabla de destino.
destination_table	cuerda / cadena	No	Nombre de la tabla de destino. El valor predeterminado es el nombre de la tabla de origen si no se especifica. Consulte Nombre de una tabla de destino.

Requisitos de columna de cursor

La columna de cursor realiza un seguimiento del progreso incremental entre las ejecuciones de canalización. El conector almacena el valor máximo del cursor después de cada ejecución correcta y lo usa como filtro de límite inferior en la siguiente ejecución.

Requisitos:

• Debe especificar una sola columna de cursor. No se pueden especificar varias columnas como cursor compuesto. Si especifica más de uno, se produce un error en la canalización con INVALID_CURSOR_COLUMNS.
• La columna de cursor debe aumentar de forma monotónica. Los valores nunca deben disminuir. Las filas con valores de cursor en o por debajo de la marca alta almacenada no se reingen en ejecuciones posteriores.
• No se ingieren filas con una columna de cursor NULL.

Tipos de columna admitidos:

• Tipos de fecha o marca de tiempo (recomendado)
• Tipos numéricos (entero, entero largo, decimal y doble)
• Tipos binarios (codificados como números binarios)
• Tipos de cadena

Condición de eliminación

El deletion_condition parámetro permite que los conectores basados en consultas detecten eliminaciones parciales. Esta característica solo se puede configurar mediante la API.

El valor es una expresión SQL que se evalúa como true para las filas que se deben tratar como eliminadas en la tabla de destino. El conector evalúa esta expresión durante cada ejecución de canalización.

Syntax:

"deletion_condition": "<sql-expression>"

Ejemplos:

"deletion_condition": "deleted_at IS NOT NULL"

"deletion_condition": "is_deleted = 1"

"deletion_condition": "status = 'DELETED'"

Cuando una fila coincide con deletion_condition, el conector quita la fila correspondiente de la tabla de destino (para SCD_TYPE_1) o la marca como eliminada (para SCD_TYPE_2).

Seguimiento de eliminación dura

El hard_deletion_sync_min_interval_in_seconds parámetro permite que los conectores basados en consultas detecten eliminaciones duras, filas que se han quitado físicamente de la tabla de origen. Esta característica está en beta y solo se puede configurar mediante la API.

El seguimiento de eliminación dura funciona tomando periódicamente una instantánea de las claves principales presentes en la tabla de origen y comparándolas con la tabla de destino. Las filas presentes en el destino, pero ausentes de la instantánea de origen se tratan como eliminadas.

El valor establece el intervalo mínimo en segundos entre exámenes de instantáneas. Este valor actúa como límite inferior: si la canalización se ejecuta con menos frecuencia que este intervalo, la sincronización de eliminación dura se alinea con la frecuencia de ingesta real en lugar de ejecutarse con más frecuencia. La actualización de este parámetro no desencadena una instantánea completa.

Nota:

El seguimiento de eliminación de forma dura requiere primary_keys configurarse en la tabla. No se admite cuando scd_type es SCD_TYPE_2.

Syntax:

"hard_deletion_sync_min_interval_in_seconds": <integer>

Ejemplo:

"hard_deletion_sync_min_interval_in_seconds": 86400

En este ejemplo se desencadena un examen de eliminación dura no más de una vez cada 24 horas (86400 segundos).

Condiciones del error

El error más común es INVALID_CURSOR_COLUMNS. Esto ocurre cuando la columna de cursor no está configurada correctamente. Consulte Columnas de cursor no válidas para ver los pasos de solución de problemas.