All Products
Search
Document Center

Hologres:Parameter GUC

Last Updated:Aug 25, 2026

Hologres mendukung parameter Grand Unified Configuration (GUC) untuk mengontrol perilaku kueri, manajemen koneksi, performa, dan keamanan pada tingkat sesi atau database.

Batasan

Parameter GUC tidak berlaku untuk tabel sistem.

Referensi parameter GUC

Parameter dikelompokkan berdasarkan fungsinya. Kolom Level menunjukkan di mana setiap parameter dapat dikonfigurasi: Session (berlaku segera untuk koneksi saat ini) atau Database (berlaku setelah terhubung ulang).

Auto-analyze

Parameter berikut mengontrol fitur auto-analyze, yang secara otomatis mengumpulkan statistik agar rencana kueri tetap akurat.

Parameter

Description

Default

Level

hg_enable_start_auto_analyze_worker

Mengaktifkan atau menonaktifkan auto-analyze.

on (Hologres V1.1+)

Session / Database

hg_auto_check_table_changes_interval

Interval di mana Hologres memeriksa perubahan pada tabel internal dan memicu auto-analyze.

10min

Session / Database

hg_auto_check_foreign_table_changes_interval

Interval di mana Hologres memeriksa perubahan pada tabel eksternal dan memicu auto-analyze.

4h

Session / Database

hg_auto_analyze_max_sample_row_count

Jumlah maksimum baris yang diambil sampelnya per eksekusi auto-analyze.

16777216

Session / Database

hg_fixed_api_modify_max_delay_interval

Tundaan maksimum sebelum auto-analyze mendeteksi perubahan yang dilakukan melalui fixed API.

3day

Session / Database

Kueri tabel eksternal MaxCompute

Parameter berikut mengoptimalkan cara Hologres melakukan kueri terhadap tabel eksternal MaxCompute. Untuk panduan penyetelan, lihat Optimalkan performa kueri untuk tabel eksternal MaxCompute.

Parameter

Description

Default

Valid values

Level

hg_foreign_table_max_partition_limit

Jumlah maksimum partisi yang diakses per kueri. Nilai 0 berarti tanpa batas.

512 (sebelum V3.0.7); 0 (V3.0.7+)

01024

Session / Database

hg_experimental_query_batch_size

Jumlah baris yang diambil per batch saat memindai tabel MaxCompute.

8192

Session / Database

hg_foreign_table_split_size

Ukuran pemisahan data (dalam MB) untuk pembacaan paralel. Hindari menetapkan nilai yang terlalu besar.

64

Session / Database

hg_foreign_table_executor_max_dop

Tingkat paralelisme (DOP) maksimum untuk eksekusi kueri.

Jumlah core CPU (maks 128)

Session / Database

hg_foreign_table_executor_dml_max_dop

DOP maksimum untuk operasi DML pada tabel eksternal.

32

Session / Database

hg_enable_access_odps_orc_via_holo

Mengaktifkan pembacaan file ORC MaxCompute melalui pembaca native Hologres.

on (Hologres V1.1+)

Session / Database

Cache hasil

Parameter

Description

Default

Level

hg_experimental_enable_result_cache

Mengaktifkan caching hasil untuk kueri identik. Nonaktifkan hanya jika hasil cache yang kedaluwarsa menyebabkan masalah.

on

Session / Database

Optimasi kueri tabel internal

Parameter berikut mengoptimalkan pengoptimal kueri untuk tabel internal. Untuk detailnya, lihat Optimalkan performa kueri.

Parameter

Description

Default

Level

optimizer_join_order

Mengontrol cara pengoptimal mencari urutan join optimal. Atur ke query untuk menggunakan urutan yang ditentukan dalam kueri.

exhaustive

Session

optimizer_force_multistage_agg

Memaksa agregasi multi-tahap. Aktifkan untuk kueri dengan GROUP BY ber-kardinalitas tinggi yang menunjukkan performa buruk.

off

Session

Keamanan dan enkripsi

Parameter

Description

Default

Level

hg_anon_enable

Mengaktifkan penyamaran data. Konfigurasikan pada tingkat database agar pengaturan berlaku untuk semua sesi.

off

Database (disarankan)

hg_experimental_encryption_options

Mengaktifkan dan mengonfigurasi enkripsi data saat disimpan. Konfigurasikan pada tingkat database.

off

Database (disarankan)

Timeout kueri dan koneksi

Penting

Konfigurasikan idle_session_timeout pada tingkat database. Nilai default 0 menonaktifkan pelepasan otomatis koneksi idle, yang dapat menghabiskan batas koneksi dan menyebabkan kebocoran koneksi.

Parameter

Description

Default

Level

statement_timeout

Membatalkan kueri aktif apa pun yang berjalan lebih lama dari durasi yang ditentukan. Nilai dalam milidetik; 0 menonaktifkan timeout. Untuk detailnya, lihat Manage queries.

8h

Session (disarankan)

idle_in_transaction_session_timeout

Mengakhiri sesi yang idle dalam transaksi terbuka lebih lama dari durasi yang ditentukan. Nilai dalam milidetik; 0 menonaktifkan timeout. Konfigurasikan pada tingkat database untuk mencegah kebocoran transaksi yang mengunci database. Untuk detailnya, lihat Manage queries.

10min

Database (disarankan)

idle_session_timeout

Melepaskan koneksi idle yang tidak aktif lebih lama dari durasi yang ditentukan. Nilai dalam milidetik; 0 menonaktifkan pelepasan otomatis. Untuk detailnya, lihat Manage connections.

0 (dinonaktifkan)

Database (disarankan)

Konversi tipe data

Parameter

Description

Default

Level

hg_experimental_functions_use_pg_implementation

Mengalihkan fungsi konversi tertentu (to_char, to_date, atau to_timestamp) ke implementasi PostgreSQL, yang mendukung rentang tahun 00009999. Implementasi Hologres default mendukung 19252282. Didukung di Hologres V1.1.31+. Untuk detailnya, lihat Fungsi konversi tipe data.

Session / Database

Contoh: Untuk memperluas rentang tahun untuk to_char:

set hg_experimental_functions_use_pg_implementation = 'to_char';

Fungsi agregat

Parameter

Description

Default

Valid values

Level

hg_experimental_approx_count_distinct_precision

Mengontrol presisi (dan penggunaan memori) fungsi APPROX_COUNT_DISTINCT. Nilai yang lebih tinggi mengurangi margin error tetapi meningkatkan penggunaan memori.

17

1220

Session / Database

Zona waktu

Parameter

Description

Default

Level

timezone

Menetapkan zona waktu untuk sesi atau database.

GMT-8:00

Session / Database

Operasi tabel

Parameter

Description

Default

Level

hg_experimental_enable_create_table_like_properties

Jika diaktifkan, CREATE TABLE LIKE menyalin skema tabel dan properti tabel (primary key, indeks). Jika dinonaktifkan, hanya skema yang disalin.

off

Session / Database

hg_experimental_affect_row_multiple_times_keep_first

Menetapkan kebijakan resolusi konflik INSERT ON CONFLICT untuk menyimpan kemunculan pertama ketika batch berisi nilai primary key duplikat.

off

Session / Database

hg_experimental_affect_row_multiple_times_keep_last

Menetapkan kebijakan resolusi konflik INSERT ON CONFLICT untuk menyimpan kemunculan terakhir ketika batch berisi nilai primary key duplikat.

off

Session / Database

Replikasi dan pemantauan

Parameter

Description

Default

Level

hg_experimental_enable_read_replica

Mengaktifkan replikasi tingkat shard.

on

Session / Database

hg_experimental_display_query_id

Menampilkan ID kueri melalui pesan NOTICE pada client, sehingga Anda dapat menemukan kueri di hologres.hg_query_log untuk troubleshooting. Berfungsi dengan HoloWeb, PSQL, JDBC, Python (Psycopg), dan client lainnya. ID kueri dikembalikan sebagai pesan NOTICE, bukan sebagai kolom dalam set hasil. Untuk informasi selengkapnya, lihat Dapatkan ID kueri.

off

Session / Database

Periksa nilai saat ini dari parameter GUC

Jalankan SHOW untuk memeriksa nilai saat ini atau nilai default suatu parameter:

-- Periksa apakah auto-analyze diaktifkan
SHOW hg_enable_start_auto_analyze_worker;

-- Periksa batas partisi MaxCompute
SHOW hg_foreign_table_max_partition_limit;

-- Periksa apakah tampilan ID kueri diaktifkan
SHOW hg_experimental_display_query_id;

Konfigurasi parameter GUC

Konfigurasikan parameter GUC pada tingkat sesi atau database tergantung pada cakupan parameter dan kasus penggunaan Anda. Tidak semua parameter perlu diatur pada tingkat database.

Tingkat sesi

Pernyataan SET mengonfigurasi parameter hanya untuk koneksi saat ini. Pengaturan dibuang saat koneksi ditutup. Gunakan konfigurasi tingkat sesi ketika perilaku tersebut hanya berlaku untuk kueri atau beban kerja tertentu, bukan secara global.

Sintaks:

set <GUC_NAME> = <VALUE>;

Contoh:

-- Aktifkan auto-analyze untuk sesi ini
set hg_enable_start_auto_analyze_worker = on;

-- Batasi jumlah partisi MaxCompute yang diakses menjadi 1024 untuk sesi ini
set hg_foreign_table_max_partition_limit = 1024;

-- Aktifkan tampilan ID kueri untuk sesi ini
set hg_experimental_display_query_id = on;

Tingkat database

Pernyataan ALTER DATABASE mengatur parameter pada tingkat database. Perubahan berlaku untuk seluruh database tanpa perlu restart instans. Koneksi Anda saat ini harus ditutup dan dibuka kembali agar nilai baru berlaku; koneksi yang dibuka setelah itu akan mewarisi parameter tersebut secara otomatis. Saat membuat database baru, konfigurasikan parameter GUC-nya secara eksplisit — parameter tersebut tidak diwariskan secara otomatis.

Sintaks:

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

Contoh:

-- Aktifkan auto-analyze untuk semua koneksi ke testdb
alter database testdb set hg_enable_start_auto_analyze_worker = on;

-- Batasi jumlah partisi MaxCompute yang diakses menjadi 1024 untuk semua koneksi ke testdb
alter database testdb set hg_foreign_table_max_partition_limit = 1024;

-- Aktifkan penyamaran data untuk semua koneksi ke database
alter database <DB_NAME> set hg_anon_enable = on;

-- Aktifkan enkripsi data untuk semua koneksi ke database
alter database <DB_NAME> set hg_experimental_encryption_options='AES256,623c26ee-xxxx-xxxx-xxxx-91d323cc4855,AliyunHologresEncryptionDefaultRole,187xxxxxxxxxxxxx';

-- Lepaskan koneksi idle setelah 10 menit (600.000 ms) tidak aktif
alter database <DB_NAME> SET idle_session_timeout = 600000;

Dapatkan ID kueri

ID kueri secara unik mengidentifikasi setiap kueri di Hologres dan merupakan bagian dari primary key log kueri lambat hologres.hg_query_log. Setelah Anda memiliki ID kueri dari suatu pernyataan, Anda dapat mencari durasinya, status, jumlah baris yang dibaca, dan detail eksekusi lainnya. Hal ini menjadikan ID kueri sebagai titik masuk utama untuk troubleshooting.

Hologres tidak mengembalikan ID kueri ke klien secara default. Setelah Anda mengaktifkan hg_experimental_display_query_id, server mengembalikan ID kueri dalam pesan NOTICE saat pernyataan dijalankan.

Deskripsi parameter

Item

Description

Parameter

hg_experimental_display_query_id

Effect

Mencetak ID kueri pada client dalam pesan NOTICE saat pernyataan dijalankan.

Nilai default

off

Nilai valid

on atau off.

Level

Session atau database.

Format pengembalian

Pesan NOTICE dalam format QueryID: <QUERY_ID>, contohnya QueryID: 1002002606817130830.

Ingat dua mekanisme berikut:

  • ID kueri tiba dalam pesan NOTICE, bukan sebagai kolom dalam set hasil. Membaca hasil kueri saja (misalnya dengan fetchall()) tidak memberikan ID kueri. Anda harus menggunakan mekanisme NOTICE yang disediakan oleh driver Anda.

  • Parameter berlaku untuk satu sesi dan dibuang saat koneksi ditutup, sehingga Anda harus mengaturnya lagi pada setiap koneksi baru. Hal ini sangat penting pada connection pool, di mana pernyataan tersebut harus ditempatkan pada langkah inisialisasi koneksi. Untuk informasi selengkapnya, lihat Connection pools.

Aktifkan tampilan ID kueri

-- Tingkat sesi. Jalankan bersama SQL bisnis Anda.
set hg_experimental_display_query_id = on;

-- Periksa nilai saat ini.
SHOW hg_experimental_display_query_id;

-- Tingkat database. Berlaku untuk koneksi baru; buka ulang koneksi yang ada.
alter database <DB_NAME> set hg_experimental_display_query_id = on;

Ambil ID kueri dari client

Java (JDBC)

Pada JDBC, pesan NOTICE tiba sebagai rantai objek SQLWarning. Telusuri rantai tersebut dengan statement.getWarnings() setelah pernyataan dijalankan dan analisis ID kueri darinya. ResultSet tidak berisi ID kueri.

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 {

    // Cocokkan "QueryID: <QUERY_ID>" dalam pesan NOTICE.
    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 {
        // Gunakan endpoint yang sesuai dengan lingkungan jaringan Anda (Internet atau VPC).
        // Temukan di halaman detail instans di Konsol.
        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()) {

            // Aktifkan tampilan ID kueri. Parameter ini default-nya off dan hanya berlaku untuk sesi ini.
            stmt.execute("set hg_experimental_display_query_id = on;");

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

            // Bersihkan peringatan dari pernyataan sebelumnya agar setiap ID kueri dipetakan ke satu pernyataan SQL.
            stmt.clearWarnings();
            boolean hasResultSet = stmt.execute(sql);

            // Baca set hasil. ID kueri tidak termasuk di dalamnya.
            if (hasResultSet) {
                try (ResultSet rs = stmt.getResultSet()) {
                    while (rs.next()) {
                        System.out.println("rows      : (" + rs.getLong(1) + ", " + rs.getLong(2) + ")");
                    }
                }
            }

            // Pesan NOTICE tiba sebagai rantai objek SQLWarning. Telusuri rantai untuk menganalisis ID kueri.
            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);
        }
    }
}

Contoh output:

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]

Perhatikan hal berikut:

  • PreparedStatement bekerja dengan cara yang sama. Panggil pstmt.getWarnings() setelah pernyataan dijalankan.

  • Panggil clearWarnings() sebelum setiap pernyataan. Jika tidak, peringatan akan menumpuk pada objek Statement yang sama dan Anda tidak dapat lagi menentukan ID kueri mana yang sesuai dengan pernyataan mana.

  • Rantai NOTICE dapat membawa pesan yang tidak terkait, seperti peringatan statistik yang hilang. Cocokkan dengan awalan QueryID: saat menganalisisnya.

Python (Psycopg 3)

Hologres kompatibel dengan PostgreSQL 11. Gunakan driver Psycopg 3, yang diinstal dengan pip install "psycopg[binary]". Daftarkan callback dengan conn.add_notice_handler() untuk menerima pesan NOTICE. Baris yang dikembalikan oleh cur.fetchall() tidak berisi ID kueri.

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):
    """Dipanggil sekali untuk setiap NOTICE yang dikirim server. Menganalisis ID kueri darinya."""
    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>",          # Temukan di halaman detail instans di Konsol.
    port=80,
    dbname="<DB_NAME>",
    user="<ACCESS_KEY_ID>",
    password="<ACCESS_KEY_SECRET>",
)
conn.autocommit = True
conn.add_notice_handler(notice_handler)   # Daftarkan callback NOTICE.

cur = conn.cursor()
# Aktifkan tampilan ID kueri. Parameter ini default-nya off dan hanya berlaku untuk sesi ini.
cur.execute("set hg_experimental_display_query_id = on;")

def run_sql(sql, params=None, fetch=True):
    """Menjalankan pernyataan dan mengembalikan (rows, query_id, notices). rows bernilai None jika tidak ada set hasil."""
    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)

Contoh output. Baik pernyataan DML maupun kueri mengembalikan ID kueri:

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']

Connection pools

Karena parameter berlaku untuk satu sesi, setiap koneksi fisik memerlukannya. Dengan connection pool, atur pada langkah inisialisasi koneksi, bukan sebelum setiap kueri.

Contoh berikut menggunakan psycopg_pool untuk Python:

# Jalankan pip install psycopg_pool terlebih dahulu.
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()

Untuk Java, gunakan SQL inisialisasi pool Anda agar setiap koneksi fisik memiliki parameter yang diaktifkan. Contoh berikut menggunakan HikariCP dan Druid:

// HikariCP: connectionInitSql dijalankan saat setiap koneksi fisik dibuat.
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 menerima beberapa pernyataan inisialisasi.
DruidDataSource druid = new DruidDataSource();
druid.setUrl(url);
druid.setUsername(user);
druid.setPassword(password);
druid.setConnectionInitSqls(Collections.singletonList("set hg_experimental_display_query_id = on;"));

Setelah Anda meminjam koneksi dari pool, Anda tetap mengambil ID kueri dengan statement.getWarnings() setelah setiap pernyataan. Untuk informasi selengkapnya, lihat Java (JDBC).

Cari detail eksekusi berdasarkan ID kueri

Dengan ID kueri, Anda dapat menemukan durasi, status, jumlah baris yang dibaca, dan detail lain dari kueri di log kueri lambat:

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

Penulisan ke hologres.hg_query_log tertunda sekitar satu menit. Kueri yang baru saja selesai mungkin belum muncul, jadi coba lagi setelah menunggu sebentar.

Catatan penggunaan

  • Parameter berlaku untuk satu sesi dan dibuang saat koneksi ditutup. Jalankan set hg_experimental_display_query_id = on; pada setiap koneksi baru, atau kueri pada koneksi tersebut tidak akan mengembalikan ID kueri.

  • Tidak semua pernyataan mengembalikan ID kueri. Pernyataan DDL seperti CREATE TABLE dan DROP TABLE, serta kueri sederhana yang tidak mencapai mesin komputasi seperti select 1;, tidak mengembalikan ID kueri. Hal ini diharapkan. Pernyataan DML seperti INSERT dan kueri biasa seperti SELECT memang mengembalikannya.

  • Rantai NOTICE dapat membawa pesan lain, seperti peringatan statistik yang hilang. Cocokkan dengan awalan QueryID: agar Anda tidak mengambil nilai yang salah.

Atasi ID kueri yang tidak muncul

Periksa hal berikut secara berurutan:

  1. Jalankan SHOW hg_experimental_display_query_id; untuk memastikan nilainya on. Jika nilainya off, koneksi saat ini tidak pernah menjalankan pernyataan tersebut — dengan connection pool Anda mungkin mendapat koneksi yang berbeda. Atur ulang atau tinjau logika inisialisasi koneksi Anda.

  2. Periksa apakah ada pesan NOTICE yang tiba. Jika tidak ada, server tidak mengirim apa pun. Pastikan versi instans Anda mendukung parameter tersebut dan jenis pernyataan menghasilkan ID kueri.

  3. Jika pesan NOTICE tiba tetapi ID kueri tidak dianalisis, format pesannya tidak cocok dengan aturan analisis Anda. Cetak pesan mentah dan sesuaikan aturan dengan format yang dikembalikan oleh instans Anda.

  4. Dengan connection pool, pastikan pernyataan dijalankan pada langkah inisialisasi koneksi agar setiap koneksi fisik menerapkannya.