Hologres:Compact data files

Requisitos previos y limitaciones

• Full compaction requiere Hologres V2.1 o posterior. Para actualizar, consulte Upgrade an instance o solicite una actualización mediante get online support.

• Solo las tablas orientadas a columnas y las tablas híbridas de filas y columnas admiten full compaction.

• En las tablas híbridas de filas y columnas, full compaction se aplica únicamente a la parte de almacenamiento por columnas.

Sintaxis

SELECT hologres.hg_full_compact_table(
  '<schema_name.table_name>'
  [,'max_file_size_mb=<value>']
);

Parámetros

Ejemplos

Ejecute full compaction en public.lineitem:

SELECT hologres.hg_full_compact_table('public.lineitem');

Ejecute full compaction en public.lineitem con un tamaño máximo de archivo de salida de 256 MB:

SELECT hologres.hg_full_compact_table(
  'public.lineitem',
  'max_file_size_mb=256'
);

Requisitos previos y limitaciones

• Estas propiedades de tabla requieren Hologres V4.0 o posterior. En versiones anteriores, configurarlas no tiene ningún efecto. Actualice primero la instancia.

• Estas propiedades se aplican únicamente a las tablas orientadas a columnas y a las tablas híbridas de filas y columnas. En una tabla híbrida de filas y columnas, solo afectan a la parte de almacenamiento por columnas. Configurarlas en una tabla orientada a filas no produce ningún efecto.

• En la mayoría de los casos, auto compaction no requiere intervención manual. Salvo online_config_compaction_semaphore, las propiedades avanzadas interactúan con la configuración de concurrencia de formas difíciles de predecir. Modifíquelas solo para resolver un problema específico, preferiblemente con la guía del soporte técnico, y restablezca los valores predeterminados después.

Establecer, consultar y restablecer propiedades de tabla

Configure las propiedades de compactación a nivel de tabla con SET_TABLE_PROPERTY. Todos los nombres de propiedad llevan el prefijo online_config_ y cada valor se pasa como una cadena. Un valor nuevo se aplica a las tareas de compactación programadas después del cambio; las tareas que ya se están ejecutando no se ven afectadas. No es necesario reiniciar la instancia ni reconstruir la tabla.

-- Syntax
CALL SET_TABLE_PROPERTY('<schema_name>.<table_name>', 'online_config_<property_name>', '<value>');

-- Pause compaction scheduling on public.orders
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '0');

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', 'reset');

SELECT property_key, property_value
FROM hologres.hg_table_properties
WHERE table_namespace = '<schema_name>'
  AND table_name = '<table_name>'
  AND property_key LIKE 'online_config_%';

Control de la concurrencia de compactación

La primera propiedad que debe ajustar es online_config_compaction_semaphore. Esta limita las tareas de compactación simultáneas por tablet, no por tabla, ya que el tablet es la unidad sobre la que se programa la compactación. Una tabla tiene uno o más tablets en cada fragmento; en una tabla híbrida de filas y columnas, las partes de almacenamiento por filas y por columnas son tablets independientes. Por lo tanto, el límite teórico para toda la tabla es aproximadamente tablet_count × property_value, aunque el límite de concurrencia a nivel de worker y los recursos disponibles suelen reducirlo.

Qué ocurre realmente al establecer el valor en 0

• Ya no se programan nuevas tareas de compactación para la tabla.

• Las tareas que ya se están ejecutando no se cancelan, sino que finalizan normalmente.

• Las tareas que ya se seleccionaron para esta tabla y esperan su ejecución conservan sus espacios de concurrencia a nivel de worker. Por lo tanto, si establece muchas tablas en 0 al mismo tiempo, la compactación de otras tablas se queda sin recursos.

• Cuando incrementa el valor por encima de 0, las tareas en cola se reanudan. Sin embargo, no se garantiza que un backlog que nunca se programó se procese por sí solo, sobre todo si la tabla no recibe nuevas escrituras. Ejecute VACUUM una vez para forzar el procesamiento del backlog. Para conocer qué hace y qué no hace VACUUM, consulte Examples.

Para restaurar la concurrencia y combinar el backlog:

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '2');
VACUUM public.orders;

Tablas particionadas lógicas

En una tabla particionada lógica, Hologres aumenta la concurrencia en proporción al número de particiones activas. El límite para una sola unidad de programación es min(online_config_partition_table_compaction_semaphore_max, active_partition_count × online_config_compaction_semaphore), con un tope de 8 de forma predeterminada. active_partition_count se mide en tiempo de ejecución y no es una propiedad configurable.

Riesgos

• No deje el valor en 0 durante mucho tiempo. La cantidad de archivos y las filas eliminadas se siguen acumulando, lo que degrada tanto el rendimiento de las consultas como el uso del almacenamiento. Además, mientras más crezca el backlog, más pesada será la combinación final.

• No establezca el valor en 0 ni lo incremente en muchas tablas al mismo tiempo. Todas las tablas comparten el presupuesto de concurrencia a nivel de worker: una pausa masiva permite que las tareas en cola ocupen ese presupuesto, mientras que un incremento masivo provoca colas globales y un pico de recursos.

• Modifique una tabla y una propiedad a la vez, con el incremento útil más pequeño posible, y observe un ciclo de negocio completo antes del siguiente cambio.

Propiedades avanzadas

A continuación se muestran las propiedades que cambian la forma en que la compactación selecciona los archivos y la frecuencia con la que se activa. Estas interactúan con la configuración de concurrencia, así que modifíquelas solo para resolver un problema diagnosticado, idealmente con la guía del soporte técnico, y restablezca los valores predeterminados después.

Ejemplos

Ejemplo 1: pausar la compactación para una carga masiva

-- 1. Record the current state. An empty result means no override is set.
SELECT property_key, property_value FROM hologres.hg_table_properties
WHERE table_namespace = 'public' AND table_name = 'orders'
  AND property_key = 'online_config_compaction_semaphore';

-- 2. Stop scheduling new compaction tasks.
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '0');

-- 3. Run the bulk load. Watch CPU, I/O, and load throughput while it runs.

-- 4. Restore the property. Choose one of the following based on step 1.
-- 4a. Step 1 returned no rows:
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', 'reset');
-- 4b. Step 1 returned a value. Write that value back:
-- CALL SET_TABLE_PROPERTY('public.orders', 'online_config_compaction_semaphore', '<original_value>');

-- 5. Merge the backlog. Run this during a low-write period.
VACUUM public.orders;

Ejemplo 2: eliminar archivos pequeños residuales

Úselo cuando cada nivel contiene menos archivos que el umbral de activación, pero la tabla acumuló decenas de archivos pequeños que nunca se combinan.

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_ignore_level_compaction', 'true');
VACUUM public.orders;
-- Restore the default once the file count drops. Leaving it on inflates compaction
-- frequency and CPU and I/O usage on continuously written tables.
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_ignore_level_compaction', 'reset');

Ejemplo 3: generar archivos combinados más grandes

Úselo cuando un tablet contiene un gran volumen de datos distribuido en muchos archivos.

CALL SET_TABLE_PROPERTY('public.orders', 'online_config_orc_max_total_size_to_merge_mb', '512');
VACUUM public.orders;
-- Restore the default once the file count drops.
CALL SET_TABLE_PROPERTY('public.orders', 'online_config_orc_max_total_size_to_merge_mb', 'reset');

Comprobar que un cambio surtió efecto

1. Los nombres de las propiedades no se validan. Se acepta cualquier nombre después del prefijo online_config_ y la instrucción se ejecuta correctamente. Un nombre mal escrito no coincide con ninguna configuración, por lo que el cambio no produce ningún efecto de forma silenciosa. Para evitarlo:

   • Copie los nombres de las propiedades de las tablas de este tema en lugar de escribirlos.

   • Confirme la escritura mediante una consulta a hologres.hg_table_properties.

   • Compruebe que el comportamiento cambió realmente al observar la cantidad y el tamaño de los archivos. Que una instrucción se ejecute correctamente no demuestra nada por sí sola.

2. Las tablas particionadas heredan las propiedades solo al crearse. Ejecutar SET_TABLE_PROPERTY en una tabla principal no afecta a las particiones secundarias existentes. La propiedad se escribe únicamente en la tabla principal, la cual no almacena datos, por lo que el comportamiento de compactación de las particiones existentes no cambia. Las particiones secundarias copian las propiedades de la tabla principal una sola vez al crearse (incluidas las particiones generadas automáticamente por el particionamiento dinámico), y los cambios posteriores en la tabla principal no se propagan. Para modificar el comportamiento de compactación en una tabla particionada, ejecute SET_TABLE_PROPERTY en cada partición secundaria objetivo y compruebe cada una de ellas. También establezca la propiedad en la tabla principal si desea que las particiones futuras la hereden.

3. Cierre el ciclo con observación. Consulte hologres.hg_table_file_status para ver la cantidad y el tamaño actuales de los archivos, hologres.hg_partition_file_status para obtener una vista por partición de una tabla particionada lógica y hologres.hg_table_info (generada una vez al día) para revisar las tendencias. Un ajuste exitoso muestra una disminución en la cantidad total de archivos y un aumento en el tamaño promedio. El uso del almacenamiento puede incrementarse brevemente mientras los archivos combinados esperan su limpieza; esto es normal.

   SELECT * FROM hologres.hg_table_file_status('<schema_name>.<table_name>'::regclass);

Requisitos previos y limitaciones

• La compactación remota requiere Hologres V5.0 o posterior.

• Las tablas orientadas a filas, las tablas orientadas a columnas y las tablas híbridas de filas y columnas admiten la compactación remota. Sin embargo, algunas estrategias internas de compactación no se pueden delegar, por lo que esas tareas se siguen ejecutando de forma local.

• La compactación remota abarca únicamente la fase de combinación de archivos. Las lecturas y escrituras de datos se siguen ejecutando en el virtual warehouse principal.

• De forma predeterminada, una tarea de compactación remota con errores no vuelve a la ejecución local, sino que falla directamente y el programador en segundo plano la reintenta automáticamente. Para restaurar el comportamiento de reversión, establezca el parámetro global enable_compaction_offload_fallback en true.

Configuración de compaction_resource

La propiedad de tabla compaction_resource define el virtual warehouse que ejecuta las tareas de compactación de una tabla específica. El cambio surte efecto de inmediato y no es necesario reiniciar la instancia.

Sintaxis

-- Offload compaction for a table to a specific virtual warehouse
CALL SET_TABLE_PROPERTY('<SCHEMA_NAME>.<TABLE_NAME>', 'compaction_resource', '<WAREHOUSE_NAME>');

-- Run compaction on the local virtual warehouse again (default)
CALL SET_TABLE_PROPERTY('<SCHEMA_NAME>.<TABLE_NAME>', 'compaction_resource', 'local');

Ejemplos

-- Offload compaction for public.orders to the virtual warehouse named readonly
CALL SET_TABLE_PROPERTY('public.orders', 'compaction_resource', 'readonly');

-- Query the current setting
SELECT property_key, property_value
FROM hologres.hg_table_properties
WHERE table_namespace = 'public'
  AND table_name = 'orders'
  AND property_key = 'compaction_resource';

Un resultado vacío o un valor local indica que la tabla ejecuta la compactación de forma local.

Consulta del estado de compactación

Llame a hologres.hg_show_compactions() para listar las tareas de compactación en ejecución y completadas, incluidas las que se ejecutaron de forma remota.

-- List all compaction records
SELECT * FROM hologres.hg_show_compactions();

-- List the compaction records that ran remotely
SELECT table_name, status, compaction_reason, execution_location,
       warehouse_name, start_time, end_time, extended_cost, last_error
FROM hologres.hg_show_compactions()
WHERE execution_location = 'warehouse'
ORDER BY start_time DESC;

La función devuelve los siguientes campos.

Ejemplos

El siguiente ejemplo delega la compactación de una tabla a un virtual warehouse remoto y luego activa full compaction de forma manual.

-- 1. Make sure the target virtual warehouse exists. Create it in the Hologres
--    console or through the API. This example uses one named readonly.

-- 2. Configure the table to use remote compaction.
CALL SET_TABLE_PROPERTY('public.lineitem', 'compaction_resource', 'readonly');

-- 3. Trigger full compaction. The merge phase runs on the readonly virtual warehouse.
SELECT hologres.hg_full_compact_table('public.lineitem');

-- 4. Wait for compaction to finish.
SELECT hologres.hg_wait_table_full_compact('public.lineitem');

-- 5. Review the remote compaction records.
SELECT table_name, status, compaction_reason, execution_location,
       warehouse_name, start_time, end_time, extended_cost,
       extended_stats, last_error
FROM hologres.hg_show_compactions()
WHERE table_name = 'lineitem'
  AND execution_location = 'warehouse'
ORDER BY start_time DESC;