GUC parameters provided by Hologres and how to use the GUC parameters. - Hologres

Hologres admite parámetros de Grand Unified Configuration (GUC) para controlar el comportamiento de las consultas, la gestión de conexiones, el rendimiento y la seguridad a nivel de sesión o de base de datos.

Límites

Los parámetros GUC no se aplican a las tablas del sistema.

Referencia de parámetros GUC

Los parámetros se agrupan por función. La columna Nivel indica dónde se puede configurar cada parámetro: Sesión (surte efecto de inmediato para la conexión actual) o Base de datos (surte efecto después de volver a conectarse).

Auto-analyze

Estos parámetros controlan la función auto-analyze, que recopila estadísticas automáticamente para mantener la precisión de los planes de consulta.

Parameter	Description	Default	Level
`hg_enable_start_auto_analyze_worker`	Habilita o deshabilita auto-analyze.	`on` (Hologres V1.1+)	Sesión / Base de datos
`hg_auto_check_table_changes_interval`	Intervalo en el que Hologres comprueba cambios en las tablas internas y activa auto-analyze.	`10min`	Sesión / Base de datos
`hg_auto_check_foreign_table_changes_interval`	Intervalo en el que Hologres comprueba cambios en las tablas externas y activa auto-analyze.	`4h`	Sesión / Base de datos
`hg_auto_analyze_max_sample_row_count`	Número máximo de filas muestreadas por cada ejecución de auto-analyze.	`16777216`	Sesión / Base de datos
`hg_fixed_api_modify_max_delay_interval`	Retraso máximo antes de que auto-analyze detecte los cambios realizados mediante API fijas.	`3day`	Sesión / Base de datos

Consulta de tablas externas de MaxCompute

Estos parámetros ajustan la forma en que Hologres consulta las tablas externas de MaxCompute. Para obtener orientación sobre ajustes, consulte Optimize query performance for MaxCompute foreign tables.

Parameter	Description	Default	Valid values	Level
`hg_foreign_table_max_partition_limit`	Número máximo de particiones consultadas por consulta. Un valor de `0` significa sin límite.	`512` (antes de V3.0.7); `0` (V3.0.7+)	`0`–`1024`	Sesión / Base de datos
`hg_experimental_query_batch_size`	Número de filas obtenidas por lote al escanear una tabla de MaxCompute.	`8192`	—	Sesión / Base de datos
`hg_foreign_table_split_size`	Tamaño de división de datos (en MB) para lecturas paralelas. Evite establecer un valor excesivamente grande.	`64`	—	Sesión / Base de datos
`hg_foreign_table_executor_max_dop`	Grado máximo de paralelismo (DOP) para la ejecución de consultas.	Número de núcleos de CPU (máximo `128`)	—	Sesión / Base de datos
`hg_foreign_table_executor_dml_max_dop`	DOP máximo para operaciones DML en tablas externas.	`32`	—	Sesión / Base de datos
`hg_enable_access_odps_orc_via_holo`	Habilita la lectura de archivos ORC de MaxCompute mediante el lector nativo de Hologres.	`on` (Hologres V1.1+)	—	Sesión / Base de datos

Caché de resultados

Parameter	Description	Default	Level
`hg_experimental_enable_result_cache`	Habilita el almacenamiento en caché de resultados para consultas idénticas. Deshabilítelo solo cuando los resultados obsoletos de la caché causen problemas.	`on`	Sesión / Base de datos

Optimización de consultas de tablas internas

Estos parámetros ajustan el optimizador de consultas para tablas internas. Para más detalles, consulte Optimize query performance.

Parameter	Description	Default	Level
`optimizer_join_order`	Controla cómo busca el optimizador el orden óptimo de uniones. Establézcalo en `query` para usar el orden especificado en la consulta.	`exhaustive`	Sesión
`optimizer_force_multistage_agg`	Fuerza la agregación en varias etapas. Habilítelo para consultas con `GROUP BY` de alta cardinalidad que presenten un rendimiento deficiente.	`off`	Sesión

Seguridad y cifrado

Parameter	Description	Default	Level
`hg_anon_enable`	Habilita data masking. Configúrelo a nivel de base de datos para que la configuración se aplique a todas las sesiones.	`off`	Base de datos (recomendado)
`hg_experimental_encryption_options`	Habilita y configura data encryption at rest. Configúrelo a nivel de base de datos.	`off`	Base de datos (recomendado)

Tiempos de espera de consulta y conexión

Importante

Configure idle_session_timeout a nivel de base de datos. El valor predeterminado de 0 deshabilita la liberación automática de conexiones inactivas, lo cual puede agotar el límite de conexiones y provocar fugas de conexiones.

Parameter	Description	Default	Level
`statement_timeout`	Cancela cualquier consulta activa que se ejecute durante más tiempo que la duración especificada. El valor está en milisegundos; `0` deshabilita el tiempo de espera. Para más detalles, consulte Manage queries.	`8h`	Sesión (recomendado)
`idle_in_transaction_session_timeout`	Finaliza las sesiones que permanecen inactivas dentro de una transacción abierta durante más tiempo que la duración especificada. El valor está en milisegundos; `0` deshabilita el tiempo de espera. Configúrelo a nivel de base de datos para evitar que las fugas de transacciones bloqueen la base de datos. Para más detalles, consulte Manage queries.	`10min`	Base de datos (recomendado)
`idle_session_timeout`	Libera las conexiones inactivas que han estado sin actividad durante más tiempo que la duración especificada. El valor está en milisegundos; `0` deshabilita la liberación automática. Para más detalles, consulte Manage connections.	`0` (deshabilitado)	Base de datos (recomendado)

Conversión de tipos de datos

Parameter	Description	Default	Level
`hg_experimental_functions_use_pg_implementation`	Cambia la función de conversión especificada (`to_char`, `to_date` o `to_timestamp`) a la implementación de PostgreSQL, que admite el rango de años `0000`–`9999`. La implementación predeterminada de Hologres admite `1925`–`2282`. Compatible con Hologres V1.1.31+. Para más detalles, consulte Data type conversion function.	—	Sesión / Base de datos

Ejemplo: Para ampliar el rango de años para to_char:

set hg_experimental_functions_use_pg_implementation = 'to_char';

Funciones de agregación

Parameter	Description	Default	Valid values	Level
`hg_experimental_approx_count_distinct_precision`	Controla la precisión (y el uso de memoria) de la función APPROX_COUNT_DISTINCT. Los valores más altos reducen el margen de error pero aumentan el uso de memoria.	`17`	`12`–`20`	Sesión / Base de datos

Zona horaria

Parameter	Description	Default	Level
`timezone`	Establece la zona horaria para la sesión o la base de datos.	`GMT-8:00`	Sesión / Base de datos

Operaciones de tabla

Parameter	Description	Default	Level
`hg_experimental_enable_create_table_like_properties`	Cuando está habilitado, CREATE TABLE LIKE copia tanto el esquema de la tabla como sus propiedades (clave primaria, índice). Cuando está deshabilitado, solo se copia el esquema.	`off`	Sesión / Base de datos
`hg_experimental_affect_row_multiple_times_keep_first`	Establece la directiva de resolución de conflictos de INSERT ON CONFLICT para conservar la primera aparición cuando un lote contiene valores duplicados de clave primaria.	`off`	Sesión / Base de datos
`hg_experimental_affect_row_multiple_times_keep_last`	Establece la directiva de resolución INSERT ON CONFLICT para conservar la última aparición cuando un lote contiene valores duplicados de clave primaria.	`off`	Sesión / Base de datos

Replicación y monitoreo

Parameter	Description	Default	Level
`hg_experimental_enable_read_replica`	Habilita shard-level replication.	`on`	Sesión / Base de datos
`hg_experimental_display_query_id`	Muestra el ID de consulta mediante un mensaje NOTICE en el cliente, para que pueda localizar una consulta en `hologres.hg_query_log` con fines de solución de problemas. Funciona con HoloWeb, PSQL, JDBC, Python (Psycopg) y otros clientes. El ID de consulta se devuelve como un mensaje NOTICE en lugar de una columna en el conjunto de resultados. Para más información, consulte Obtain the query ID.	`off`	Sesión / Base de datos

Consultar el valor actual de un parámetro GUC

Ejecute SHOW para consultar el valor actual o predeterminado de un parámetro:

-- Check whether auto-analyze is enabled
SHOW hg_enable_start_auto_analyze_worker;

-- Check the MaxCompute partition limit
SHOW hg_foreign_table_max_partition_limit;

-- Check whether query ID display is enabled
SHOW hg_experimental_display_query_id;

Configurar parámetros GUC

Configure los parámetros GUC a nivel de sesión o de base de datos según el alcance del parámetro y su caso de uso. No todos los parámetros necesitan establecerse a nivel de base de datos.

Nivel de sesión

La instrucción SET configura un parámetro solo para la conexión actual. La configuración se descarta cuando se cierra la conexión. Utilice la configuración a nivel de sesión cuando el comportamiento deba aplicarse a una consulta o carga de trabajo específica, y no de manera global.

Sintaxis:

set <GUC_NAME> = <VALUE>;

Ejemplos:

-- Enable auto-analyze for this session
set hg_enable_start_auto_analyze_worker = on;

-- Limit MaxCompute partition hits to 1024 for this session
set hg_foreign_table_max_partition_limit = 1024;

-- Enable query ID display for this session
set hg_experimental_display_query_id = on;

Nivel de base de datos

La instrucción ALTER DATABASE establece un parámetro a nivel de base de datos. El cambio se aplica a toda la base de datos sin necesidad de reiniciar la instancia. Debe cerrar y volver a abrir su conexión actual antes de que el nuevo valor surta efecto; las conexiones abiertas posteriormente heredan el parámetro automáticamente. Al crear una nueva base de datos, configure sus parámetros GUC explícitamente, ya que no se heredan de forma automática.

Sintaxis:

alter database <DB_NAME> set <GUC_NAME> = <VALUE>;

Ejemplos:

-- Enable auto-analyze for all connections to testdb
alter database testdb set hg_enable_start_auto_analyze_worker = on;

-- Limit MaxCompute partition hits to 1024 for all connections to testdb
alter database testdb set hg_foreign_table_max_partition_limit = 1024;

-- Enable data masking for all connections to a database
alter database <DB_NAME> set hg_anon_enable = on;

-- Enable data encryption for all connections to a database
alter database <DB_NAME> set hg_experimental_encryption_options='AES256,623c26ee-xxxx-xxxx-xxxx-91d323cc4855,AliyunHologresEncryptionDefaultRole,187xxxxxxxxxxxxx';

-- Release idle connections after 10 minutes (600,000 ms) of inactivity
alter database <DB_NAME> SET idle_session_timeout = 600000;

Obtener el ID de consulta

El ID de consulta identifica de forma única cada consulta en Hologres y forma parte de la clave primaria del registro de consultas lentas hologres.hg_query_log. Una vez que obtiene el ID de consulta de una instrucción, puede consultar su duración, estado, número de filas leídas y otros detalles de ejecución. Esto convierte al ID de consulta en el punto de entrada principal para la solución de problemas.

De forma predeterminada, Hologres no devuelve el ID de consulta al cliente. Después de habilitar hg_experimental_display_query_id, el servidor devuelve el ID de consulta en un mensaje NOTICE cuando se ejecuta la instrucción.

Descripción del parámetro

Item	Description
Parámetro	`hg_experimental_display_query_id`
Efecto	Imprime el ID de consulta en el cliente mediante un mensaje NOTICE cuando se ejecuta una instrucción.
Valor predeterminado	`off`
Valores válidos	`on` u `off`.
Nivel	Sesión o base de datos.
Formato de devolución	Un mensaje NOTICE con el formato `QueryID: <QUERY_ID>`, por ejemplo `QueryID: 1002002606817130830`.

Tenga en cuenta los siguientes dos mecanismos:

El ID de consulta llega en un mensaje NOTICE, no como una columna en el conjunto de resultados. Leer únicamente los resultados de la consulta (por ejemplo, con fetchall()) no le proporciona el ID de consulta. Debe utilizar el mecanismo NOTICE que proporciona su controlador.
El parámetro se aplica a una sola sesión y se descarta cuando se cierra la conexión, por lo que debe establecerlo nuevamente en cada nueva conexión. Esto es especialmente relevante con pools de conexiones, donde la instrucción debe incluirse en el paso de inicialización de la conexión. Para más información, consulte Connection pools.

Habilitar la visualización del ID de consulta

-- Session level. Run this together with your business SQL.
set hg_experimental_display_query_id = on;

-- Check the current value.
SHOW hg_experimental_display_query_id;

-- Database level. Applies to new connections; reopen existing connections.
alter database <DB_NAME> set hg_experimental_display_query_id = on;

Recuperar el ID de consulta desde un cliente

Java (JDBC)

En JDBC, los mensajes NOTICE llegan como una cadena de objetos SQLWarning. Recorra la cadena con statement.getWarnings() después de que se ejecute la instrucción y analice sintácticamente el ID de consulta a partir de ella. El ResultSet no contiene el ID de consulta.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.SQLWarning;
import java.sql.Statement;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class HologresQueryIdDemo {

    // Matches "QueryID: <QUERY_ID>" in a NOTICE message.
    private static final Pattern QUERY_ID_PATTERN = Pattern.compile(
            "query[_ ]?id\\s*(?:is\\b|[=:])?\\s*([0-9a-zA-Z_\\-]{6,})", Pattern.CASE_INSENSITIVE);

    public static void main(String[] args) throws Exception {
        // Use the endpoint that matches your network environment (Internet or VPC).
        // Find it on the instance details page in the console.
        String url = "jdbc:postgresql://<ENDPOINT>:80/<DB_NAME>";
        String user = "<ACCESS_KEY_ID>";
        String password = "<ACCESS_KEY_SECRET>";

        try (Connection conn = DriverManager.getConnection(url, user, password);
             Statement stmt = conn.createStatement()) {

            // Enable query ID display. The parameter is off by default and applies to this session only.
            stmt.execute("set hg_experimental_display_query_id = on;");

            String sql = "select count(*), sum(id) from holo_query_id_demo;";

            // Clear warnings left by the previous statement so that each query ID maps to one SQL statement.
            stmt.clearWarnings();
            boolean hasResultSet = stmt.execute(sql);

            // Read the result set. The query ID is not part of it.
            if (hasResultSet) {
                try (ResultSet rs = stmt.getResultSet()) {
                    while (rs.next()) {
                        System.out.println("rows      : (" + rs.getLong(1) + ", " + rs.getLong(2) + ")");
                    }
                }
            }

            // NOTICE messages arrive as a chain of SQLWarning objects. Walk the chain to parse the query ID.
            String queryId = null;
            List<String> notices = new ArrayList<>();
            for (SQLWarning w = stmt.getWarnings(); w != null; w = w.getNextWarning()) {
                notices.add(w.getMessage());
                Matcher m = QUERY_ID_PATTERN.matcher(w.getMessage());
                if (m.find()) {
                    queryId = m.group(1);
                }
            }

            System.out.println("query_id  : " + queryId);
            System.out.println("notices   : " + notices);
        }
    }
}

Salida de ejemplo:

rows      : (1000, 500500)
query_id  : 1002002606817139331
notices   : [One or more columns in the following table(s) do not have statistics: holo_query_id_demo, QueryID: 1002002606817139331]

Tenga en cuenta lo siguiente:

PreparedStatement funciona de la misma manera. Llame a pstmt.getWarnings() después de que se ejecute la instrucción.
Llame a clearWarnings() antes de cada instrucción. De lo contrario, las advertencias se acumulan en el mismo objeto Statement y ya no podrá distinguir qué ID de consulta pertenece a qué instrucción.
Una cadena NOTICE puede contener mensajes no relacionados, como una advertencia de estadísticas faltantes. Busque la coincidencia con el prefijo QueryID: cuando realice el análisis sintáctico.

Python (Psycopg 3)

Hologres es compatible con PostgreSQL 11. Utilice el controlador Psycopg 3, que se instala con pip install "psycopg[binary]". Registre una función de retorno con conn.add_notice_handler() para recibir mensajes NOTICE. Las filas devueltas por cur.fetchall() no contienen el ID de consulta.

import re
import psycopg

NOTICES = []
QUERY_IDS = []

QUERY_ID_PATTERN = re.compile(
    r"query[_ ]?id\s*(?:is\b|[=:])?\s*([0-9a-zA-Z_\-]{6,})", re.IGNORECASE
)

def notice_handler(diag):
    """Called once for every NOTICE the server sends. Parses the query ID from it."""
    text = diag.message_primary or ""
    NOTICES.append(text)
    match = QUERY_ID_PATTERN.search(text)
    if match:
        QUERY_IDS.append(match.group(1))

conn = psycopg.connect(
    host="<ENDPOINT>",          # Find it on the instance details page in the console.
    port=80,
    dbname="<DB_NAME>",
    user="<ACCESS_KEY_ID>",
    password="<ACCESS_KEY_SECRET>",
)
conn.autocommit = True
conn.add_notice_handler(notice_handler)   # Register the NOTICE callback.

cur = conn.cursor()
# Enable query ID display. The parameter is off by default and applies to this session only.
cur.execute("set hg_experimental_display_query_id = on;")

def run_sql(sql, params=None, fetch=True):
    """Runs a statement and returns (rows, query_id, notices). rows is None when there is no result set."""
    NOTICES.clear()
    QUERY_IDS.clear()
    cur.execute(sql, params)
    rows = None
    if fetch and cur.description is not None:
        rows = cur.fetchall()
    query_id = QUERY_IDS[-1] if QUERY_IDS else None
    return rows, query_id, list(NOTICES)

rows, query_id, notices = run_sql("select count(*) from holo_query_id_demo;")
print("rows:", rows)
print("query_id:", query_id)

Salida de ejemplo. Tanto las instrucciones DML como las consultas devuelven un ID de consulta:

SQL       : insert into holo_query_id_demo select i, 'v' || i from generate_series(1, 1000) i;
query_id  : 1002002606817130830
notices   : ['QueryID: 1002002606817130830']

SQL       : select count(*), sum(id) from holo_query_id_demo;
query_id  : 1002002606817139331
rows      : [(1000, 500500)]
notices   : ['One or more columns in the following table(s) do not have statistics: holo_query_id_demo', 'QueryID: 1002002606817139331']

Pools de conexiones

Dado que el parámetro se aplica a una sola sesión, cada conexión física lo necesita. Con un pool de conexiones, establézcalo en el paso de inicialización de la conexión en lugar de hacerlo antes de cada consulta.

El siguiente ejemplo utiliza psycopg_pool para Python:

# Run pip install psycopg_pool first.
from psycopg_pool import ConnectionPool

def configure(conn):
    conn.autocommit = True
    conn.add_notice_handler(notice_handler)
    conn.execute("set hg_experimental_display_query_id = on;")

pool = ConnectionPool(kwargs=CONN_INFO, configure=configure, min_size=1, max_size=4)

with pool.connection() as conn:
    conn.execute("select 1;").fetchall()

Para Java, utilice el SQL de inicialización de su pool para que cada conexión física tenga el parámetro habilitado. Los siguientes ejemplos utilizan HikariCP y Druid:

// HikariCP: connectionInitSql runs when each physical connection is established.
HikariConfig config = new HikariConfig();
config.setJdbcUrl(url);
config.setUsername(user);
config.setPassword(password);
config.setConnectionInitSql("set hg_experimental_display_query_id = on;");
HikariDataSource dataSource = new HikariDataSource(config);

// Druid: connectionInitSqls accepts multiple initialization statements.
DruidDataSource druid = new DruidDataSource();
druid.setUrl(url);
druid.setUsername(user);
druid.setPassword(password);
druid.setConnectionInitSqls(Collections.singletonList("set hg_experimental_display_query_id = on;"));

Después de tomar prestada una conexión del pool, aún puede recuperar el ID de consulta con statement.getWarnings() después de cada instrucción. Para más información, consulte Java (JDBC).

Buscar detalles de ejecución por ID de consulta

Con el ID de consulta, puede localizar con precisión la duración, el estado, el número de filas leídas y otros detalles de una consulta en el registro de consultas lentas:

select query_id, status, duration, query_start, application_name, command_tag
from hologres.hg_query_log
where query_id = '<QUERY_ID>';

Las escrituras en hologres.hg_query_log tienen un retraso aproximado de un minuto. Es posible que una consulta recién finalizada aún no aparezca, así que vuelva a intentarlo tras una breve espera.

Notas de uso

El parámetro se aplica a una sola sesión y se descarta cuando se cierra la conexión. Ejecute set hg_experimental_display_query_id = on; en cada nueva conexión; de lo contrario, las consultas en esa conexión no devolverán ningún ID de consulta.
No todas las instrucciones devuelven un ID de consulta. Las instrucciones DDL como CREATE TABLE y DROP TABLE, así como las consultas simples que no llegan al motor de cómputo como select 1;, no devuelven ningún ID de consulta. Este comportamiento es esperado. Las instrucciones DML como INSERT y las consultas regulares como SELECT sí devuelven uno.
Una cadena NOTICE puede contener otros mensajes, como una advertencia de estadísticas faltantes. Busque la coincidencia con el prefijo QueryID: para no seleccionar un valor incorrecto.

Solucionar problemas de un ID de consulta faltante

Compruebe lo siguiente en orden:

Ejecute SHOW hg_experimental_display_query_id; para confirmar que el valor es on. Si es off, la conexión actual nunca ejecutó la instrucción; con un pool de conexiones, es posible que se le haya asignado una conexión diferente. Vuelva a establecerlo o revise su lógica de inicialización de conexiones.
Compruebe si llegó algún mensaje NOTICE. Si no llegó ninguno, el servidor no envió nada. Confirme que la versión de su instancia admite el parámetro y que el tipo de instrucción genera un ID de consulta.
Si llegaron mensajes NOTICE pero no se analizó sintácticamente ningún ID de consulta, la redacción no coincide con su regla de análisis. Imprima el mensaje sin procesar y ajuste la regla al formato que devuelve su instancia.
Con un pool de conexiones, confirme que la instrucción se ejecuta en el paso de inicialización de la conexión para que se aplique en cada conexión física.