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 |
|
|
Mengaktifkan atau menonaktifkan auto-analyze. |
|
Session / Database |
|
|
Interval di mana Hologres memeriksa perubahan pada tabel internal dan memicu auto-analyze. |
|
Session / Database |
|
|
Interval di mana Hologres memeriksa perubahan pada tabel eksternal dan memicu auto-analyze. |
|
Session / Database |
|
|
Jumlah maksimum baris yang diambil sampelnya per eksekusi auto-analyze. |
|
Session / Database |
|
|
Tundaan maksimum sebelum auto-analyze mendeteksi perubahan yang dilakukan melalui fixed API. |
|
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 |
|
|
Jumlah maksimum partisi yang diakses per kueri. Nilai |
|
|
Session / Database |
|
|
Jumlah baris yang diambil per batch saat memindai tabel MaxCompute. |
|
— |
Session / Database |
|
|
Ukuran pemisahan data (dalam MB) untuk pembacaan paralel. Hindari menetapkan nilai yang terlalu besar. |
|
— |
Session / Database |
|
|
Tingkat paralelisme (DOP) maksimum untuk eksekusi kueri. |
Jumlah core CPU (maks |
— |
Session / Database |
|
|
DOP maksimum untuk operasi DML pada tabel eksternal. |
|
— |
Session / Database |
|
|
Mengaktifkan pembacaan file ORC MaxCompute melalui pembaca native Hologres. |
|
— |
Session / Database |
Cache hasil
|
Parameter |
Description |
Default |
Level |
|
|
Mengaktifkan caching hasil untuk kueri identik. Nonaktifkan hanya jika hasil cache yang kedaluwarsa menyebabkan masalah. |
|
Session / Database |
Optimasi kueri tabel internal
Parameter berikut mengoptimalkan pengoptimal kueri untuk tabel internal. Untuk detailnya, lihat Optimalkan performa kueri.
|
Parameter |
Description |
Default |
Level |
|
|
Mengontrol cara pengoptimal mencari urutan join optimal. Atur ke |
|
Session |
|
|
Memaksa agregasi multi-tahap. Aktifkan untuk kueri dengan |
|
Session |
Keamanan dan enkripsi
|
Parameter |
Description |
Default |
Level |
|
|
Mengaktifkan penyamaran data. Konfigurasikan pada tingkat database agar pengaturan berlaku untuk semua sesi. |
|
Database (disarankan) |
|
|
Mengaktifkan dan mengonfigurasi enkripsi data saat disimpan. Konfigurasikan pada tingkat database. |
|
Database (disarankan) |
Timeout kueri dan koneksi
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 |
|
|
Membatalkan kueri aktif apa pun yang berjalan lebih lama dari durasi yang ditentukan. Nilai dalam milidetik; |
|
Session (disarankan) |
|
|
Mengakhiri sesi yang idle dalam transaksi terbuka lebih lama dari durasi yang ditentukan. Nilai dalam milidetik; |
|
Database (disarankan) |
|
|
Melepaskan koneksi idle yang tidak aktif lebih lama dari durasi yang ditentukan. Nilai dalam milidetik; |
|
Database (disarankan) |
Konversi tipe data
|
Parameter |
Description |
Default |
Level |
|
|
Mengalihkan fungsi konversi tertentu ( |
— |
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 |
|
|
Mengontrol presisi (dan penggunaan memori) fungsi APPROX_COUNT_DISTINCT. Nilai yang lebih tinggi mengurangi margin error tetapi meningkatkan penggunaan memori. |
|
|
Session / Database |
Zona waktu
|
Parameter |
Description |
Default |
Level |
|
|
Menetapkan zona waktu untuk sesi atau database. |
|
Session / Database |
Operasi tabel
|
Parameter |
Description |
Default |
Level |
|
|
Jika diaktifkan, CREATE TABLE LIKE menyalin skema tabel dan properti tabel (primary key, indeks). Jika dinonaktifkan, hanya skema yang disalin. |
|
Session / Database |
|
|
Menetapkan kebijakan resolusi konflik INSERT ON CONFLICT untuk menyimpan kemunculan pertama ketika batch berisi nilai primary key duplikat. |
|
Session / Database |
|
|
Menetapkan kebijakan resolusi konflik INSERT ON CONFLICT untuk menyimpan kemunculan terakhir ketika batch berisi nilai primary key duplikat. |
|
Session / Database |
Replikasi dan pemantauan
|
Parameter |
Description |
Default |
Level |
|
|
Mengaktifkan replikasi tingkat shard. |
|
Session / Database |
|
|
Menampilkan ID kueri melalui pesan NOTICE pada client, sehingga Anda dapat menemukan kueri di |
|
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 |
|
|
Effect |
Mencetak ID kueri pada client dalam pesan NOTICE saat pernyataan dijalankan. |
|
Nilai default |
|
|
Nilai valid |
|
|
Level |
Session atau database. |
|
Format pengembalian |
Pesan NOTICE dalam format |
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:
-
PreparedStatementbekerja dengan cara yang sama. Panggilpstmt.getWarnings()setelah pernyataan dijalankan. -
Panggil
clearWarnings()sebelum setiap pernyataan. Jika tidak, peringatan akan menumpuk pada objekStatementyang 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 TABLEdanDROP TABLE, serta kueri sederhana yang tidak mencapai mesin komputasi sepertiselect 1;, tidak mengembalikan ID kueri. Hal ini diharapkan. Pernyataan DML sepertiINSERTdan kueri biasa sepertiSELECTmemang 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:
-
Jalankan
SHOW hg_experimental_display_query_id;untuk memastikan nilainyaon. Jika nilainyaoff, 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. -
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.
-
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.
-
Dengan connection pool, pastikan pernyataan dijalankan pada langkah inisialisasi koneksi agar setiap koneksi fisik menerapkannya.