Fungsi Azure Cosmos DB for PostgreSQL

Artikel
08/15/2024

BERLAKU UNTUK: Azure Cosmos DB for PostgreSQL (didukung oleh ekstensi database Citus ke PostgreSQL)

Bagian ini berisi informasi referensi untuk fungsi yang ditentukan pengguna yang disediakan oleh Azure Cosmos DB for PostgreSQL. Fungsi-fungsi ini membantu dalam menyediakan fungsionalitas terdistribusi ke Azure Cosmos DB for PostgreSQL.

Catatan

kluster yang menjalankan versi Lama Mesin Citus mungkin tidak menawarkan semua fungsi yang tercantum di halaman ini.

Tabel dan Shard DDL

citus_schema_distribute

Mengonversi skema reguler yang ada menjadi skema terdistribusi. Skema terdistribusi secara otomatis diasosiasikan dengan grup kolokasi individual. Tabel yang dibuat dalam skema tersebut dikonversi ke tabel terdistribusi yang dikolokasi tanpa kunci shard. Proses mendistribusikan skema secara otomatis menetapkan dan memindahkannya ke node yang ada di kluster.

Argumen

skema: Nama skema, yang perlu didistribusikan.

Nilai hasil

T/A

Contoh

SELECT citus_schema_distribute('tenant_a');
SELECT citus_schema_distribute('tenant_b');
SELECT citus_schema_distribute('tenant_c');

Untuk contoh selengkapnya, lihat cara mendesain untuk layanan mikro.

citus_schema_undistribute

Mengonversi skema terdistribusi yang ada kembali menjadi skema biasa. Proses ini menghasilkan tabel dan data yang dipindahkan dari simpul saat ini kembali ke simpul koordinator di kluster.

Argumen

skema: Nama skema, yang perlu didistribusikan.

Nilai hasil

T/A

Contoh

SELECT citus_schema_undistribute('tenant_a');
SELECT citus_schema_undistribute('tenant_b');
SELECT citus_schema_undistribute('tenant_c');

Untuk contoh selengkapnya, lihat cara mendesain untuk layanan mikro.

create_distributed_table

Fungsi create_distributed_table() digunakan untuk menentukan tabel terdistribusi dan membuat shardnya jika tabel didistribusikan hash. Fungsi ini mengambil nama tabel, kolom distribusi, dan metode distribusi opsional serta menyisipkan metadata yang sesuai untuk menandai tabel sebagai didistribusikan. Fungsi ini secara default berubah ke distribusi 'hash' jika tidak ada metode distribusi yang ditentukan. Jika tabel didistribusikan hash, fungsi ini juga membuat shard pekerja berdasarkan jumlah shard dan nilai konfigurasi faktor replikasi shard. Jika berisi baris apa pun, tabel secara otomatis didistribusikan ke node pekerja.

Fungsi ini menggantikan penggunaan master_create_distributed_table() diikuti dengan master_create_worker_shards().

Argumen

table_name: Nama tabel yang perlu didistribusikan.

distribution_column: Kolom tempat tabel akan didistribusikan.

distribution_type: (Opsional) Metode yang sesuai dengan tabel yang akan didistribusikan. Nilai yang diizinkan adalah append atau hash, dengan nilai default 'hash'.

colocate_with: (Opsional) menyertakan tabel saat ini dalam grup kolokasi dari tabel lain. Secara default tabel dikolokasi saat didistribusikan oleh kolom dengan jenis yang sama, memiliki jumlah pecahan yang sama, dan memiliki faktor replikasi yang sama. Nilai yang mungkin untuk colocate_with adalah default, noneuntuk memulai grup kolokasi baru, atau nama tabel lain untuk dikolokasi dengan tabel tersebut. (Lihat kolokasi tabel.)

Perlu diingat bahwa nilai default dari colocate_with melakukan kolokasi implisit. Kolokasi dapat menjadi hal yang baik saat tabel terhubung atau akan digabungkan. Akan tetapi, saat dua tabel tidak terhubung tetapi kebetulan menggunakan jenis data yang sama untuk kolom distribusi, kolokasi yang tidak disengaja dapat mengurangi performa selama penyeimbangan ulang shard. Shard tabel akan dipindahkan bersama-sama secara tidak semestinya dalam "kaskade".

Jika tabel terdistribusi baru tidak terkait dengan tabel lain, sebaiknya tentukan colocate_with => 'none'.

shard_count: (Opsional) jumlah pecahan yang akan dibuat untuk tabel terdistribusi baru. Saat menentukan shard_count , Anda tidak dapat menentukan nilai selain tidak colocate_with ada. Untuk mengubah jumlah shard tabel atau grup kolokasi yang ada, gunakan fungsi alter_distributed_table .

Nilai yang mungkin untuk shard_count adalah antara 1 dan 64000. Untuk panduan tentang memilih nilai optimal, lihat Jumlah Shard.

Nilai hasil

T/A

Contoh

Contoh ini menginformasikan database bahwa tabel github_events harus didistribusikan oleh hash pada kolom repo_id.

SELECT create_distributed_table('github_events', 'repo_id');

-- alternatively, to be more explicit:
SELECT create_distributed_table('github_events', 'repo_id',
                                colocate_with => 'github_repo');

create_distributed_table_concurrently

Fungsi ini memiliki antarmuka dan tujuan yang sama dengan create_distributed_function, tetapi tidak memblokir penulisan selama distribusi tabel.

Namun, create_distributed_table_concurrently memiliki beberapa batasan:

Anda tidak dapat menggunakan fungsi dalam blok transaksi, yang berarti Anda hanya dapat mendistribusikan satu tabel pada satu waktu. (Anda dapat menggunakan fungsi pada tabel yang dipartisi waktu.)
Anda tidak dapat menggunakan create_distributed_table_concurrently saat tabel dirujuk oleh kunci asing, atau mereferensikan tabel lokal lainnya. Namun, kunci asing untuk mereferensikan tabel berfungsi, dan Anda dapat membuat kunci asing ke tabel terdistribusi lainnya setelah distribusi tabel selesai.
Jika Anda tidak memiliki kunci utama atau identitas replika pada tabel Anda, perintah pembaruan dan penghapusan akan gagal selama distribusi tabel karena keterbatasan replikasi logis.

truncate_local_data_after_distributing_table

Potong semua baris lokal setelah mendistribusikan tabel, dan cegah batasan gagal karena catatan lokal yang sudah usang. Pemotongan mengalir ke tabel yang memiliki kunci asing ke tabel yang ditentukan. Jika tabel pengarah tidak terdistribusi dengan sendirinya, maka pemotongan dilarang hingga tabel tersebut, untuk melindungi integritas referensial:

ERROR:  cannot truncate a table referenced in a foreign key constraint by a local table

Memotong data tabel node koordinator lokal aman untuk tabel terdistribusi karena barisnya, jika ada, disalin ke node pekerja selama distribusi.

Argumen

table_name: Nama tabel terdistribusi yang rekanan lokalnya pada node koordinator harus dipotong.

Nilai hasil

T/A

Contoh

-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');

create_reference_table

Fungsi create_reference_table() digunakan untuk mendefinisikan referensi kecil atau tabel dimensi. Fungsi ini mengambil nama tabel, dan membuat tabel terdistribusi hanya dengan satu shard, direplikasi ke setiap simpul pekerja.

Argumen

table_name: Nama dimensi kecil atau tabel referensi yang perlu didistribusikan.

Nilai hasil

T/A

Contoh

Contoh ini menginformasikan database bahwa tabel negara harus ditentukan sebagai tabel referensi

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Menambahkan tabel Postgres lokal ke dalam metadata Citus. Kasus penggunaan utama untuk fungsi ini adalah membuat tabel lokal pada koordinator dapat diakses dari node apa pun di kluster. Data yang terkait dengan tabel lokal tetap berada di koordinator - hanya skema dan metadatanya yang dikirim ke pekerja.

Menambahkan tabel lokal ke metadata akan dikenakan sedikit biaya. Saat Anda menambahkan tabel, Citus harus melacaknya di tabel partisi. Tabel lokal yang ditambahkan ke metadata mewarisi batasan yang sama dengan tabel referensi.

Saat Anda tidak mendistribusikan tabel, Citus menghapus tabel lokal yang dihasilkan dari metadata, yang menghilangkan batasan tersebut pada tabel tersebut.

Argumen

table_name: Nama tabel pada koordinator yang akan ditambahkan ke metadata Citus.

cascade_via_foreign_keys: (Opsional) Ketika argumen ini diatur ke "true," citus_add_local_table_to_metadata menambahkan tabel lain yang berada dalam hubungan kunci asing dengan tabel yang diberikan ke dalam metadata secara otomatis. Berhati-hatilah dengan parameter ini, karena berpotensi memengaruhi banyak tabel.

Nilai hasil

T/A

Contoh

Contoh ini menginformasikan database bahwa tabel bangsa harus didefinisikan sebagai tabel koordinator-lokal, dapat diakses dari simpul apa pun:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

Fungsi alter_distributed_table() dapat digunakan untuk mengubah kolom distribusi, jumlah shard, atau properti kolokasi tabel terdistribusi.

Argumen

table_name: Nama tabel yang akan diubah.

distribution_column: (Opsional) Nama kolom distribusi baru.

shard_count: (Opsional) Jumlah shard baru.

colocate_with: (Opsional) Tabel yang akan dikolokasi oleh tabel terdistribusi saat ini. Nilai yang mungkin adalah default, none untuk memulai grup kolokasi baru, atau nama tabel lain yang dapat dikolokasi. (Lihat kolokasi tabel.)

cascade_to_colocated: (Opsional) Saat argumen ini diatur ke "true", perubahan shard_count dan colocate_with juga akan diterapkan ke semua tabel yang sebelumnya dikolokasi dengan tabel, dan kolokasi akan dipertahankan. Jika "salah", kolokasi saat ini tabel ini akan rusak.

Nilai hasil

T/A

Contoh

-- change distribution column
SELECT alter_distributed_table('github_events', distribution_column:='event_id');

-- change shard count of all tables in colocation group
SELECT alter_distributed_table('github_events', shard_count:=6, cascade_to_colocated:=true);

-- change colocation
SELECT alter_distributed_table('github_events', colocate_with:='another_table');

update_distributed_table_colocation

Fungsi update_distributed_table_colocation() digunakan untuk memperbarui kolokasi tabel terdistribusi. Fungsi ini juga dapat digunakan guna memecah kolokasi tabel terdistribusi. Azure Cosmos DB for PostgreSQL akan secara implisit mengumpulkan dua tabel jika kolom distribusi adalah jenis yang sama, ini dapat berguna jika tabel terkait dan akan melakukan beberapa gabungan. Jika tabel A dan B diseimbangkan, dan tabel A akan diseimbangkan kembali, tabel B juga akan diseimbangkan kembali. Jika tabel B tidak memiliki identitas replika, penyeimbangan kembali akan gagal. Oleh karena itu, fungsi ini dapat berguna untuk memecah kolokasi implisit dalam kasus itu.

Fungsi ini tidak memindahkan data apa pun secara fisik.

Argumen

table_name: Nama kolkasi tabel yang akan diperbarui.

colocate_with: Tabel tempat tabel harus dikolokasi.

Jika ingin memecahkan kolokasi tabel, Anda harus menentukan colocate_with => 'none'.

Nilai hasil

T/A

Contoh

Contoh ini menunjukkan bahwa kolokasi tabel A diperbarui sebagai kolokasi tabel B.

SELECT update_distributed_table_colocation('A', colocate_with => 'B');

Asumsikan bahwa tabel A dan tabel B dikolokasi (mungkin secara implisit), jika Anda ingin memecahkan kolokasi:

SELECT update_distributed_table_colocation('A', colocate_with => 'none');

Sekarang, asumsikan bahwa tabel A, tabel B, tabel C dan tabel D dikolokasi dan Anda ingin menggabungkan tabel A dan tabel B bersama-sama, dan tabel C dan tabel D bersama-sama:

SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');

Jika Anda memiliki tabel terdistribusi hash bernama tidak ada dan ingin memperbarui kolokasinya, Anda dapat melakukan:

SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');

undistribute_table

Fungsi undistribute_table() membatalkan tindakan create_distributed_table atau create_reference_table. Tidak mendistribusikan memindahkan semua data dari shard kembali ke tabel lokal pada node koordinator (dengan asumsi data dapat muat), kemudian menghapus shard.

Azure Cosmos DB for PostgreSQL tidak akan membatalkan distribusi tabel yang memiliki--atau direferensikan oleh--kunci asing, kecuali argumen cascade_via_foreign_keys diatur ke true. Jika argumen ini salah (atau dihilangkan), Anda harus secara manual menghapus batasan kunci asing yang mengganggu sebelum tidak mendistribusikan.

Argumen

table_name: Nama tabel terdistribusi atau referensi untuk tidak mendistribusikan.

cascade_via_foreign_keys: (Opsional) Ketika argumen ini diatur ke "true," undistribute_table juga tidak mendistribusikan semua tabel yang terkait dengan table_name melalui kunci asing. Berhati-hatilah dengan parameter ini, karena berpotensi memengaruhi banyak tabel.

Nilai hasil

T/A

Contoh

Contoh ini mendistribusikan tabel github_events dan kemudian tidak mendistribusikannya.

-- first distribute the table
SELECT create_distributed_table('github_events', 'repo_id');

-- undo that and make it local again
SELECT undistribute_table('github_events');

create_distributed_function

Mengisi fungsi dari simpul koordinator ke pekerja, dan menandainya untuk eksekusi terdistribusi. Ketika fungsi terdistribusi dipanggil pada koordinator, Azure Cosmos DB for PostgreSQL menggunakan nilai "argumen distribusi" untuk memilih simpul pekerja untuk menjalankan fungsi. Mengeksekusi fungsi pada pekerja meningkatkan paralelisme, dan dapat membawa kode lebih dekat ke data dalam shard untuk latensi yang lebih rendah.

Jalur pencarian Postgres tidak diisi dari koordinator ke pekerja selama eksekusi fungsi terdistribusi, sehingga kode fungsi terdistribusi harus sepenuhnya memenuhi syarat nama objek database. Pemberitahuan yang dikeluarkan oleh fungsi juga tidak akan ditampilkan kepada pengguna.

Argumen

function_name: Nama fungsi yang akan didistribusikan. Nama harus menyertakan jenis parameter fungsi dalam tanda kurung, karena beberapa fungsi dapat memiliki nama yang sama di PostgreSQL. Misalnya, 'foo(int)' berbeda dari 'foo(int, text)'.

distribution_arg_name: (Opsional) Nama argumen yang digunakan untuk mendistribusikan. Untuk kenyamanan (atau jika argumen fungsi tidak memiliki nama), tempat penampung posisi diizinkan, seperti '$1'. Jika parameter ini tidak ditentukan, fungsi yang disebutkan oleh function_name hanya dibuat pada pekerja. Jika simpul pekerja ditambahkan di masa depan, fungsi akan secara otomatis dibuat di sana juga.

colocate_with: (Opsional) Saat fungsi terdistribusi membaca atau menulis ke tabel terdistribusi (atau, lebih umum, grup kolokasi), pastikan untuk memberi nama tabel tersebut menggunakan parameter colocate_with. Kemudian setiap pemanggilan fungsi akan berjalan pada simpul pekerja yang berisi shard yang relevan.

Nilai hasil

T/A

Contoh

-- an example function which updates a hypothetical
-- event_responses table which itself is distributed by event_id
CREATE OR REPLACE FUNCTION
  register_for_event(p_event_id int, p_user_id int)
RETURNS void LANGUAGE plpgsql AS $fn$
BEGIN
  INSERT INTO event_responses VALUES ($1, $2, 'yes')
  ON CONFLICT (event_id, user_id)
  DO UPDATE SET response = EXCLUDED.response;
END;
$fn$;

-- distribute the function to workers, using the p_event_id argument
-- to determine which shard each invocation affects, and explicitly
-- colocating with event_responses which the function updates
SELECT create_distributed_function(
  'register_for_event(int, int)', 'p_event_id',
  colocate_with := 'event_responses'
);

alter_columnar_table_set

Fungsi alter_columnar_table_set() mengubah pengaturan pada tabel kolom. Memanggil fungsi ini pada tabel non-kolom memberikan kesalahan. Semua argumen kecuali nama tabel bersifat opsional.

Untuk melihat opsi saat ini untuk semua tabel kolom, lihat tabel ini:

SELECT * FROM columnar.options;

Nilai default untuk pengaturan kolom untuk tabel yang baru dibuat dapat diganti dengan GUC ini:

columnar.compression
columnar.compression_level
columnar.stripe_row_count
columnar.chunk_row_count

Argumen

table_name: Nama tabel kolom.

chunk_row_count: (Opsional) Jumlah maksimum baris per gugus untuk data yang baru disisipkan. Potongan data yang ada tidak akan diubah dan mungkin memiliki lebih banyak baris daripada nilai maksimum ini. Nilai default adalah 10000.

stripe_row_count: (Opsional) Jumlah maksimum baris per garis untuk data yang baru disisipkan. Garis data yang ada tidak akan diubah dan mungkin memiliki lebih banyak baris daripada nilai maksimum ini. Nilai default adalah 150000.

compression: (Opsional) [none|pglz|zstd|lz4|lz4hc] Jenis kompresi untuk data yang baru disisipkan. Data yang ada tidak akan dikompresi ulang atau didekompresi. Nilai default dan yang disarankan adalah zstd (jika dukungan telah dikompilasi).

compression_level: (Opsional) Pengaturan yang valid adalah dari 1 hingga 19. Jika metode kompresi tidak mendukung tingkat yang dipilih, tingkat terdekat akan dipilih sebagai gantinya.

Nilai hasil

T/A

Contoh

SELECT alter_columnar_table_set(
  'my_columnar_table',
  compression => 'none',
  stripe_row_count => 10000);

alter_table_set_access_method

Fungsi alter_table_set_access_method() mengubah metode akses tabel (misalnya, heap atau columnar).

Argumen

table_name: Nama tabel yang metode aksesnya akan berubah.

access_method: Nama metode akses baru.

Nilai hasil

T/A

Contoh

SELECT alter_table_set_access_method('github_events', 'columnar');

create_time_partitions

Fungsi create_time_partitions() membuat partisi interval tertentu untuk mencakup rentang waktu tertentu.

Argumen

table_name: (regclass) tabel untuk membuat partisi baru. Tabel harus dipartisi pada satu kolom, jenis tanggal, stempel waktu, atau timestamptz.

partition_interval: interval waktu, seperti '2 hours', atau '1 month', untuk digunakan saat mengatur rentang pada partisi baru.

end_at: (timestamptz) membuat partisi hingga saat ini. Partisi terakhir akan berisi titik end_at, dan tidak ada partisi nanti yang akan dibuat.

start_from: (timestamptz, opsional) pilih partisi pertama sehingga berisi titik start_from. Nilai defaultnya adalah now().

Nilai hasil

Benar jika perlu membuat partisi baru, salah jika semuanya sudah ada.

Contoh

-- create a year's worth of monthly partitions
-- in table foo, starting from the current time

SELECT create_time_partitions(
  table_name         := 'foo',
  partition_interval := '1 month',
  end_at             := now() + '12 months'
);

drop_old_time_partitions

Fungsi drop_old_time_partitions() menghapus semua partisi yang intervalnya jatuh sebelum stempel waktu tertentu. Selain menggunakan fungsi ini, Anda mungkin mempertimbangkan alter_old_partitions_set_access_method guna mengompres partisi lama dengan penyimpanan kolom.

Argumen

table_name: (regclass) tabel guna menghapus partisi. Tabel harus dipartisi pada satu kolom, jenis tanggal, stempel waktu, atau timestamptz.

older_than: (timestamptz) drop partisi yang jangkauan atasnya kurang dari atau sama dengan older_than.

Nilai hasil

T/A

Contoh

-- drop partitions that are over a year old

CALL drop_old_time_partitions('foo', now() - interval '12 months');

alter_old_partitions_set_access_method

Dalam kasus penggunaan deret waktu, tabel sering dipartisi berdasarkan waktu, dan partisi lama dikompresi menjadi penyimpanan kolom baca-saja.

Argumen

parent_table_name: (regclass) tabel guna mengubah partisi. Tabel harus dipartisi pada satu kolom, jenis tanggal, stempel waktu, atau timestamptz.

older_than: (timestamptz) mengubah partisi yang rentang atasnya kurang dari atau sama dengan older_than.

new_access_method: (nama) baik 'heap' untuk penyimpanan berbasis baris, atau 'columnar' untuk penyimpanan kolumnar.

Nilai hasil

T/A

Contoh

CALL alter_old_partitions_set_access_method(
  'foo', now() - interval '6 months',
  'columnar'
);

Informasi Metadata / Konfigurasi

get_shard_id_for_distribution_column

Azure Cosmos DB for PostgreSQL menetapkan setiap baris tabel terdistribusi ke shard berdasarkan nilai kolom distribusi baris dan metode distribusi tabel. Umumnya, pemetaan yang tepat adalah detail tingkat rendah yang dapat diabaikan administrator database. Akan tetapi, ini dapat berguna untuk menentukan shard baris, untuk tugas pemeliharaan database manual atau hanya untuk memenuhi keingintahuan. Fungsi get_shard_id_for_distribution_column ini menyediakan info ini untuk tabel terdistribusi hash, terdistribusi rentang, dan referensi. Ini tidak berfungsi untuk distribusi penambahan.

Argumen

table_name: Tabel yang terdistribusi.

distribution_value: Nilai kolom distribusi.

Nilai hasil

ID shard Azure Cosmos DB for PostgreSQL mengaitkan dengan nilai kolom distribusi untuk tabel yang diberikan.

Contoh

SELECT get_shard_id_for_distribution_column('my_table', 4);

 get_shard_id_for_distribution_column
--------------------------------------
                               540007
(1 row)

column_to_column_name

Menerjemahkan partkey kolom pg_dist_partition ke dalam nama kolom tekstual. Terjemahan berguna untuk menentukan kolom distribusi tabel terdistribusi.

Untuk diskusi yang lebih mendetail, lihat memilih kolom distribusi.

Argumen

table_name: Tabel yang terdistribusi.

columnvartext: Nilai partkey dalam tabel pg_dist_partition.

Nilai hasil

Nama kolom distribusi table_name.

Contoh

-- get distribution column name for products table

SELECT column_to_column_name(logicalrelid, partkey) AS dist_col_name
  FROM pg_dist_partition
 WHERE logicalrelid='products'::regclass;

Output:

┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id    │
└───────────────┘

citus_relation_size

Mendapatkan ruang disk yang digunakan oleh semua shard tabel terdistribusi yang ditentukan. Ruang disk mencakup ukuran “fork utama”, tetapi tidak termasuk peta visibilitas dan peta ruang kosong untuk shard.

Argumen

logicalrelid: nama tabel terdistribusi.

Nilai hasil

Ukuran dalam byte sebagai bigint.

Contoh

SELECT pg_size_pretty(citus_relation_size('github_events'));

pg_size_pretty
--------------
23 MB

citus_table_size

Mendapatkan ruang disk yang digunakan oleh semua shard tabel terdistribusi yang ditentukan, tidak termasuk indeks (tetapi termasuk TOAST, peta ruang kosong, dan peta visibilitas).

Argumen

logicalrelid: nama tabel terdistribusi.

Nilai hasil

Ukuran dalam byte sebagai bigint.

Contoh

SELECT pg_size_pretty(citus_table_size('github_events'));

pg_size_pretty
--------------
37 MB

citus_total_relation_size

Mendapatkan total ruang disk yang digunakan oleh semua shard tabel terdistribusi yang ditentukan, termasuk semua indeks dan data TOAST.

Argumen

logicalrelid: nama tabel terdistribusi.

Nilai hasil

Ukuran dalam byte sebagai bigint.

Contoh

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

pg_size_pretty
--------------
73 MB

citus_stat_statements_reset

Menghapus semua baris dari citus_stat_statements. Fungsi ini bekerja secara independen dari pg_stat_statements_reset(). Untuk mengatur ulang semua statistik, panggil kedua fungsi.

Argumen

T/A

Nilai hasil

Tidak

citus_get_active_worker_nodes

Fungsi citus_get_active_worker_nodes() mengembalikan daftar nama host pekerja aktif dan nomor port.

Argumen

T/A

Nilai hasil

Daftar tuple yang mana setiap tuple berisi informasi berikut:

node_name: nama DNS node pekerja

node_port: Port pada node pekerja sumber tempat server database mendengarkan

Contoh

SELECT * from citus_get_active_worker_nodes();
 node_name | node_port
-----------+-----------
 localhost |      9700
 localhost |      9702
 localhost |      9701

(3 rows)

Manajemen dan perbaikan kluster

master_copy_shard_placement

Jika penempatan shard gagal diperbarui selama perintah modifikasi atau operasi DDL, maka itu akan ditandai sebagai tidak aktif. Fungsi master_copy_shard_placement kemudian dapat dipanggil untuk memperbaiki penempatan pecahan yang tidak aktif menggunakan data dari penempatan yang sehat.

Untuk memperbaiki shard, fungsi terlebih dahulu menjatuhkan penempatan pecahan yang tidak sehat dan membuatnya kembali menggunakan skema pada koordinator. Setelah penempatan shard dibuat, fungsi menyalin data dari penempatan yang tepat dan memperbarui metadata untuk menandai penempatan shard baru sebagai sehat. Fungsi ini memastikan bahwa shard akan dilindungi dari modifikasi bersamaan selama perbaikan.

Argumen

shard_id: ID pecahan yang akan diperbaiki.

source_node_name: Nama DNS node tempat penempatan shard yang sehat berada (node "sumber").

source_node_port: Port pada node pekerja sumber tempat server database mendengarkan.

target_node_name: Nama DNS node tempat penempatan shard yang tidak valid ada (node "target").

target_node_port: Port pada node pekerja target tempat server database mendengarkan.

Nilai hasil

T/A

Contoh

Contoh di bawah ini akan memperbaiki penempatan shard yang tidak aktif dari shard 12345, yang ada di server database yang berjalan di 'bad_host' pada port 5432. Untuk memperbaikinya, ini akan menggunakan data dari penempatan shard sehat yang ada di server yang berjalan pada 'good_host' di port 5432.

SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);

master_move_shard_placement

Fungsi ini memindahkan shard tertentu (dan shard yang dikolokasikan dengannya) dari satu simpul ke simpul lainnya. Biasanya digunakan secara tidak langsung selama penyeimbangan ulang shard daripada dipanggil langsung oleh administrator database.

Ada dua cara untuk memindahkan data: memblokir atau membatalkan blokir. Pendekatan memblokir berarti bahwa selama pemindahan semua modifikasi pada shard dijeda. Cara kedua, yang menghindari pemblokiran menulis shard, bergantung pada replikasi logis Postgres 10.

Setelah operasi pemindahan berhasil, shard di simpul sumber dihapus. Jika pemindahan gagal pada titik mana pun, fungsi ini melemparkan kesalahan dan membuat simpul sumber dan target tidak berubah.

Argumen

shard_id: ID shard yang akan dipindahkan.

source_node_name: Nama DNS node tempat penempatan shard yang sehat berada (node "sumber").

source_node_port: Port pada node pekerja sumber tempat server database mendengarkan.

target_node_name: Nama DNS node tempat penempatan shard yang tidak valid ada (node "target").

target_node_port: Port pada node pekerja target tempat server database mendengarkan.

shard_transfer_mode: (Opsional) Menentukan metode replikasi, apakah akan menggunakan replikasi logis PostgreSQL atau perintah COPY lintas pekerja. Nilai yang mungkin adalah:

auto: Memerlukan identitas replika jika replikasi logis dimungkinkan, jika tidak gunakan perilaku warisan (misalnya, untuk perbaikan shard, PostgreSQL 9.6). Ini adalah nilai default.

force_logical: Gunakan replikasi logis meskipun tabel tidak memiliki identitas replika. Setiap pernyataan pembaruan/penghapusan bersamaan ke tabel akan gagal selama replikasi.

block_writes: Gunakan COPY (pemblokiran menulis) untuk tabel yang tidak memiliki kunci primer atau identitas replika.

Nilai hasil

T/A

Contoh

SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);

rebalance_table_shards

Fungsi rebalance_table_shards() memindahkan shard tabel tertentu untuk membuatnya terdistribusi secara merata di antara pekerja. Fungsi ini pertama-tama menghitung daftar pemindahan yang perlu dilakukan untuk memastikan bahwa kluster seimbang dalam ambang yang diberikan. Kemudian, ini memindahkan penempatan shard satu per satu dari simpul sumber ke simpul tujuan dan memperbarui metadata shard yang sesuai untuk mencerminkan pemindahan tersebut.

Setiap shard diberi biaya saat menentukan apakah shard “didistribusikan secara merata.” Secara default setiap shard memiliki biaya yang sama (nilai 1), jadi mendistribusikan untuk menyamakan biaya di seluruh pekerja sama dengan menyamakan jumlah shard pada masing-masing. Strategi biaya konstan dipanggil "by_shard_count" dan merupakan strategi penyeimbangan ulang default.

Strategi "by_shard_count" sesuai dalam keadaan ini:

Shard kira-kira berukuran sama
Shard mendapatkan jumlah lalu lintas yang kira-kira sama
Simpul pekerja memiliki ukuran/jenis yang sama
Shard belum disematkan ke pekerja tertentu

Jika salah satu asumsi ini tidak bertahan, maka menyeimbangkan kembali "by_shard_count" dapat mengakibatkan rencana yang buruk.

Strategi penyeimbangan ulang default adalah "by_disk_size". Anda selalu dapat menyesuaikan strategi, menggunakan rebalance_strategy parameter .

Dianjurkan untuk memanggil get_rebalance_table_shards_plan sebelum menjalankan rebalance_table_shards, untuk melihat dan memverifikasi tindakan yang akan dilakukan.

Argumen

table_name: (Opsional) Nama tabel yang shardnya perlu diseimbangkan ulang. Jika NULL, maka seimbangkan ulang semua grup kolokasi yang ada.

threshold: (Opsional) Angka float antara 0,0 dan 1,0 yang menunjukkan rasio perbedaan maksimum pemanfaatan simpul dari pemanfaatan rata-rata. Misalnya, menentukan 0,1 akan menyebabkan penyeimbang ulang shard mencoba menyeimbangkan semua simpul untuk mempertahankan jumlah shard yang sama ± 10%. Secara khusus, penyeimbang ulang shard akan mencoba untuk menyatukan pemanfaatan semua simpul pekerja ke (1 - ambang) * average_utilization ... (1

ambang) * rentang average_utilization.

max_shard_moves: (Opsional) Jumlah maksimum shard yang akan dipindahkan.

excluded_shard_list: (Opsional) Pengidentifikasi shard yang sebaiknya tidak dipindahkan selama operasi penyeimbangan ulang.

shard_transfer_mode: (Opsional) Menentukan metode replikasi, apakah akan menggunakan replikasi logis PostgreSQL atau perintah COPY lintas pekerja. Nilai yang mungkin adalah:

auto: Memerlukan identitas replika jika replikasi logis dimungkinkan, jika tidak gunakan perilaku warisan (misalnya, untuk perbaikan shard, PostgreSQL 9.6). Ini adalah nilai default.

force_logical: Gunakan replikasi logis meskipun tabel tidak memiliki identitas replika. Setiap pernyataan pembaruan/penghapusan bersamaan ke tabel akan gagal selama replikasi.

block_writes: Gunakan COPY (pemblokiran menulis) untuk tabel yang tidak memiliki kunci primer atau identitas replika.

drain_only: (Opsional) Jika benar, memindahkan shard dari simpul pekerja yang telah shouldhaveshardsdiatur ke false di pg_dist_node; tidak memindahkan shard lainnya.

rebalance_strategy: (Opsional) nama strategi dalam pg_dist_rebalance_strategy. Jika argumen ini dihilangkan, fungsi memilih strategi default, seperti yang ditunjukkan dalam tabel.

Nilai hasil

T/A

Contoh

Contoh di bawah ini akan mencoba menyeimbangkan ulang shard tabel github_events dalam ambang default.

SELECT rebalance_table_shards('github_events');

Contoh penggunaan ini akan mencoba menyeimbangkan ulang tabel github_events tanpa memindahkan shard dengan ID 1 dan 2.

SELECT rebalance_table_shards('github_events', excluded_shard_list:='{1,2}');

get_rebalance_table_shards_plan

Menghasilkan pemindahan shard yang direncanakan dari rebalance_table_shards tanpa melakukannya. Meskipun tidak mungkin, get_rebalance_table_shards_plan dapat menghasilkan rencana yang sedikit berbeda dari apa yang dipanggil olehebalance_table_shards dengan apa yang akan dilakukan oleh argumen yang sama. Mereka tidak dijalankan pada saat yang sama, sehingga fakta tentang kluster -- misalnya, ruang disk -- mungkin berbeda antara panggilan.

Argumen

Argumen yang sama dengan rebalance_table_shards: relasi, ambang batas, max_shard_moves, exception_shard_list, dan drain_only. Lihat dokumentasi fungsi tersebut untuk arti argumen.

Nilai hasil

Tupel yang berisi kolom ini:

table_name: Tabel yang shardnya akan dipindahkan
shardid: Shard yang dimaksud
shard_size: Ukuran dalam byte
sourcename: Hostname simpul sumber
sourceport: Port simpul sumber
targetname: Hostname simpul tujuan
targetport: Port simpul tujuan

get_rebalance_progress

Setelah penyeimbangan ulang shard dimulai, fungsi get_rebalance_progress() mencantumkan progres setiap shard yang terlibat. Ini memantau pemindahan yang direncanakan dan dieksekusi oleh rebalance_table_shards().

Argumen

T/A

Nilai hasil

Tupel yang berisi kolom ini:

sessionid: Postgres PID monitor penyeimbangan ulang
table_name: Tabel yang shardnya akan dipindahkan
shardid: Shard yang dimaksud
shard_size: Ukuran dalam byte
sourcename: Hostname simpul sumber
sourceport: Port simpul sumber
targetname: Hostname simpul tujuan
targetport: Port simpul tujuan
progress: 0 = menunggu untuk dipindahkan; 1 = berpindah; 2 = selesai

Contoh

SELECT * FROM get_rebalance_progress();

┌───────────┬────────────┬─────────┬────────────┬───────────────┬────────────┬───────────────┬────────────┬──────────┐
│ sessionid │ table_name │ shardid │ shard_size │  sourcename   │ sourceport │  targetname   │ targetport │ progress │
├───────────┼────────────┼─────────┼────────────┼───────────────┼────────────┼───────────────┼────────────┼──────────┤
│      7083 │ foo        │  102008 │    1204224 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102009 │    1802240 │ n1.foobar.com │       5432 │ n4.foobar.com │       5432 │        0 │
│      7083 │ foo        │  102018 │     614400 │ n2.foobar.com │       5432 │ n4.foobar.com │       5432 │        1 │
│      7083 │ foo        │  102019 │       8192 │ n3.foobar.com │       5432 │ n4.foobar.com │       5432 │        2 │
└───────────┴────────────┴─────────┴────────────┴───────────────┴────────────┴───────────────┴────────────┴──────────┘

citus_add_rebalance_strategy

Menambahkan baris ke pg_dist_rebalance_strategy .

Argumen

Untuk informasi selengkapnya tentang argumen ini, lihat nilai kolom yang sesuai di pg_dist_rebalance_strategy.

name: pengidentifikasi untuk strategi baru

shard_cost_function: mengidentifikasi fungsi yang digunakan untuk menentukan "biaya" setiap shard

node_capacity_function: mengidentifikasi fungsi untuk mengukur kapasitas node

shard_allowed_on_node_function: mengidentifikasi fungsi yang menentukan pecahan mana yang dapat ditempatkan pada simpul mana

default_threshold: ambang titik apung yang menyetel seberapa tepat biaya shard kumulatif harus seimbang antar node

minimum_threshold: (Opsional) kolom pengaman yang menyimpan nilai minimum yang diizinkan untuk argumen ambang rebalance_table_shards(). Nilai default adalah 0

Nilai hasil

T/A

citus_set_default_rebalance_strategy

Memperbarui tabel pg_dist_rebalance_strategy, mengubah strategi yang dinamai dengan argumennya menjadi default yang dipilih saat menyeimbangkan ulang shard.

Argumen

name: nama strategi di pg_dist_rebalance_strategy

Nilai hasil

T/A

Contoh

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

Fungsi citus_remote_connection_stats() menunjukkan jumlah koneksi aktif ke setiap node jarak jauh.

Argumen

T/A

Contoh

SELECT * from citus_remote_connection_stats();

    hostname    | port | database_name | connection_count_to_node
----------------+------+---------------+--------------------------
 citus_worker_1 | 5432 | postgres      |                        3
(1 row)

isolate_tenant_to_new_shard

Fungsi ini membuat shard baru untuk menahan baris dengan nilai tunggal tertentu di kolom distribusi. Ini sangat berguna untuk kasus penggunaan multipenyewa, di mana penyewa besar dapat ditempatkan sendiri pada pecahannya sendiri dan pada akhirnya simpul fisiknya sendiri.

Argumen

table_name: Nama tabel untuk mendapatkan pecahan baru.

tenant_id: Nilai kolom distribusi yang akan ditetapkan ke pecahan baru.

cascade_option: (Opsional) Saat disetel ke "CASCADE," juga mengisolasi pecahan dari semua tabel di grup colocation tabel saat ini.

Nilai hasil

shard_id: Fungsi mengembalikan ID unik yang ditetapkan ke shard yang baru dibuat.

Contoh

Buat shard baru untuk menahan lineitem untuk penyewa 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│                      102240 │
└─────────────────────────────┘

Langkah berikutnya

Banyak fungsi dalam artikel ini memodifikasi tabel metadata sistem
Parameter server mengustomisasi perilaku beberapa fungsi

Bagikan melalui

Fungsi Azure Cosmos DB for PostgreSQL

Tabel dan Shard DDL

citus_schema_distribute

Argumen

Nilai hasil

Contoh

citus_schema_undistribute

Argumen

Nilai hasil

Contoh

create_distributed_table

Argumen

Nilai hasil

Contoh

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argumen

Nilai hasil

Contoh

create_reference_table

Argumen

Nilai hasil

Contoh

citus_add_local_table_to_metadata

Argumen

Nilai hasil

Contoh

alter_distributed_table

Argumen

Nilai hasil

Contoh

update_distributed_table_colocation

Argumen

Nilai hasil

Contoh

undistribute_table

Argumen

Nilai hasil

Contoh

create_distributed_function

Argumen

Nilai hasil

Contoh

alter_columnar_table_set

Argumen

Nilai hasil

Contoh

alter_table_set_access_method

Argumen

Nilai hasil

Contoh

create_time_partitions

Argumen

Nilai hasil

Contoh

drop_old_time_partitions

Argumen

Nilai hasil

Contoh

alter_old_partitions_set_access_method

Argumen

Nilai hasil

Contoh

Informasi Metadata / Konfigurasi

get_shard_id_for_distribution_column

Argumen

Nilai hasil

Contoh

column_to_column_name

Argumen

Nilai hasil

Contoh

citus_relation_size

Argumen

Nilai hasil

Contoh

citus_table_size

Argumen

Nilai hasil