適用于 PostgreSQL 的 Azure Cosmos DB 函式

適用于： 適用于 PostgreSQL 的 Azure Cosmos DB （由 Citus 資料庫延伸模組 支援 PostgreSQL）

本節包含適用于 PostgreSQL 的 Azure Cosmos DB 所提供的使用者定義函式參考資訊。 這些函式有助於將分散式功能提供給適用于 PostgreSQL 的 Azure Cosmos DB。

注意

執行舊版 Citus 引擎的叢集可能無法提供此頁面上所列的所有函式。

資料表和分區 DDL

citus_schema_distribute

將現有的一般架構轉換成分散式架構。 分散式架構會自動與個別共置群組產生關聯。 在這些架構中建立的資料表會轉換成沒有分區索引鍵的共置分散式資料表。 散發架構的程式會自動指派，並將其移至叢集中的現有節點。

引數

schemaname： 需要散發的架構名稱。

傳回值

N/A

範例

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

如需更多範例，請參閱微服務 的作法 設計。

citus_schema_undistribute

將現有的分散式架構轉換回一般架構。 此程式會導致資料表和資料從目前的節點移回叢集中的協調器節點。

引數

schemaname： 需要散發的架構名稱。

傳回值

N/A

範例

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

如需更多範例，請參閱微服務 的作法 設計。

create_distributed_table

create_distributed_table（） 函式是用來定義分散式資料表，如果它是雜湊分散式資料表，則會建立其分區。 此函式會採用資料表名稱、散發資料行和選擇性散發方法，並插入適當的中繼資料，將資料表標示為分散式。 如果未指定散發方法，函式預設為 'hash' 散發。 如果資料表是雜湊散發的，函式也會根據分區計數和分區複寫因數組態值來建立背景工作分區。 如果資料表包含任何資料列，它們會自動散發到背景工作節點。

此函式會取代 master_create_distributed_table（） 的使用方式，後面接著master_create_worker_shards（）。

引數

table_name： 需要散發的資料表名稱。

distribution_column： 要散發資料表的資料行。

distribution_type： （選擇性） 要根據資料表散發的方法。 允許的值是附加或雜湊，預設值為 'hash'。

colocate_with： （選擇性）在另一個資料表的共置群組中包含目前的資料表。 根據預設，當資料表是由相同類型的資料行散發、具有相同分區計數，且具有相同的複寫因數時，就會共置資料表。 的可能值為 colocate_withdefault ， none 以啟動新的共置群組，或要與該資料表共置的另一個資料表名稱。 （請參閱 資料表共置 。）

請記住，的 colocate_with 預設值會進行隱含共置。 當資料表相關或將聯結時，共置 可能是件好事。 不過，當兩個數據表不相關，但碰巧針對其散發資料行使用相同的資料類型時，不小心共置資料表可能會降低分區重新平衡 期間的 效能。 資料表分區會在「串聯」中不必要地一起移動。

如果新的分散式資料表與其他資料表無關，最好指定 colocate_with => 'none' 。

shard_count： （選擇性）要為新的分散式資料表建立的分區數目。 指定 shard_count 時，您無法指定非任何的值 colocate_with 。 若要變更現有資料表或共置群組的分區計數，請使用 alter_distributed_table 函式。

的可能值為 shard_count 1 到 64000。 如需選擇最佳值的指引，請參閱 分區計數 。

傳回值

N/A

範例

本範例會通知資料庫，github_events資料表應該透過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

此函式具有與create_distributed_function 相同的介面和用途 ，但不會在資料表散發期間封鎖寫入。

不過， create_distributed_table_concurrently 有一些限制：

• 您無法在交易區塊中使用 函式，這表示您一次只能散發一個資料表。 （不過，您可以在 時間分割資料表上使用 函式。
• 當資料表由外鍵參考，或參考另一個本機資料表時，您無法使用 create_distributed_table_concurrently 。 不過，參考資料表的外鍵可以運作，而且您可以在資料表散發完成之後，建立其他分散式資料表的外鍵。
• 如果您的資料表上沒有主鍵或複本身分識別，則更新和刪除命令會在資料表散發期間失敗，因為邏輯複寫的限制。

truncate_local_data_after_distributing_table

在散發資料表之後截斷所有本機資料列，並防止條件約束因為本機記錄過期而失敗。 截斷會串連至具有指定資料表外鍵的資料表。 如果參考資料表本身不是散發的，則除非是，否則會禁止截斷，以保護參考完整性：

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

對於散發資料表而言，截斷本機協調器節點資料表資料是安全的，因為其資料列 (若有) 在散發期間會複製到背景工作節點。

引數

table_name： 應該截斷協調器節點上本機對應專案的分散式資料表名稱。

傳回值

N/A

範例

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

create_reference_table

create_reference_table（） 函式可用來定義小型參考或維度資料表。 此函式會採用資料表名稱，並建立只有一個分區的分散式資料表，並複寫至每個背景工作節點。

引數

table_name： 需要散發之小型維度或參考資料表的名稱。

傳回值

N/A

範例

此範例會通知資料庫，國家資料表應定義為參考資料表

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

將本機 Postgres 資料表新增至 Citus 中繼資料。 此函式的主要使用案例是讓協調器上的本機資料表可從叢集中的任何節點存取。 與本機資料表相關聯的資料會保留在協調器上，只會將其架構和中繼資料傳送給背景工作角色。

將本機資料表新增至中繼資料時，成本微微。 當您新增資料表時，Citus 必須在分割區資料表 中 追蹤它。 新增至中繼資料的本機資料表會繼承與參考資料表相同的限制。

當您取消散發資料表時，Citus 會從中繼資料中移除產生的本機資料表，從而消除這些資料表的這類限制。

引數

table_name： 協調器上要新增至 Citus 中繼資料的資料表名稱。

cascade_via_foreign_keys ：（選擇性） 當此引數設定為 「true」 時，citus_add_local_table_to_metadata會自動將與指定資料表的外鍵關聯性中的其他資料表新增至中繼資料。 請謹慎使用此參數，因為它可能會影響許多資料表。

傳回值

N/A

範例

此範例會通知資料庫，國家資料表應該定義為協調器本機資料表，可從任何節點存取：

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

alter_distributed_table（） 函式可用來變更分散式資料表的散發資料行、分區計數或共置屬性。

引數

table_name： 將改變的資料表名稱。

distribution_column： [選擇性] 新散發資料行的名稱。

shard_count： （選擇性） 新的分區計數。

colocate_with： （選擇性） 目前分散式資料表將共置的資料表。 可能的值為 default ， none 若要啟動新的共置群組，或要共置之另一個資料表的名稱。 （請參閱 資料表共置 。）

cascade_to_colocated： （選擇性） 當此引數設定為 「true」時， shard_count 也會 colocate_with 將變更套用至先前與資料表共置的所有資料表，並保留共置。 如果是 「false」，則此資料表目前的共置將會中斷。

傳回值

N/A

範例

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

update_distributed_table_colocation（） 函式可用來更新分散式資料表的共置。 此函式也可以用來中斷分散式資料表的共置。 適用于 PostgreSQL 的 Azure Cosmos DB 會在散發資料行相同類型時隱含共置兩個數據表，如果資料表相關，而且會執行一些聯結，這會很有用。 如果資料表 A 和 B 共置，且資料表 A 會重新平衡，則資料表 B 也會重新平衡。 如果資料表 B 沒有複本身分識別，重新平衡將會失敗。 因此，在此案例中，此函式有助於中斷隱含共置。

此函式不會實際移動任何資料。

引數

table_name： 將會更新的資料表共置名稱。

colocate_with： 應該與資料表共置的資料表。

如果您想要中斷資料表的共置，您應該指定 colocate_with => 'none' 。

傳回值

N/A

範例

此範例顯示資料表 A 的共置會更新為數據表 B 的共置。

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

假設資料表 A 和資料表 B 共置（可能隱含），如果您想要中斷共置共置：

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

現在，假設資料表 A、資料表 B、資料表 C 和資料表 D 已共置，而且您想要將資料表 A 和資料表 B 共置在一起，並將資料表 C 和資料表 D 共置在一起：

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

如果您有名為 none 的雜湊分散式資料表，而且想要更新其共置，您可以執行下列動作：

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

undistribute_table

undistribute_table（） 函式會復原create_distributed_table或create_reference_table的動作。 取消散發會將所有資料從分區移回協調器節點上的本機資料表（假設資料可以符合），然後刪除分區。

除非cascade_via_foreign_keys引數設定為 true，否則適用于 PostgreSQL 的 Azure Cosmos DB 不會取消散發具有或由外鍵參考的資料表。 如果這個引數為 false（或省略），則您必須在取消散發之前手動卸載違規的外鍵條件約束。

引數

table_name： 未散發的分散式或參考資料表名稱。

cascade_via_foreign_keys： （選擇性） 當這個引數設定為 「true」 時，undistribute_table也會取消散發所有透過外鍵table_name相關的資料表。 請謹慎使用此參數，因為它可能會影響許多資料表。

傳回值

N/A

範例

本範例會散發資料表 github_events ，然後取消散發資料表。

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

將函式從協調器節點傳播至背景工作角色，並將其標示為分散式執行。 在協調器上呼叫分散式函式時，適用于 PostgreSQL 的 Azure Cosmos DB 會使用 「distribution 引數」 的值來挑選背景工作節點來執行函式。 在背景工作角色上執行 函式會增加平行處理原則，並可讓程式碼更接近分區中的資料，以降低延遲。

Postgres 搜尋路徑不會在分散式函式執行期間從協調器傳播到背景工作角色，因此分散式函式程式碼應該完整限定資料庫物件的名稱。 此外，函式發出的通知也不會向使用者顯示。

引數

function_name： 要散發的函式名稱。 名稱必須在括弧中包含函式的參數類型，因為 PostgreSQL 中有多個函式可以有相同的名稱。 例如， 'foo(int)' 與 'foo(int, text)' 不同。

distribution_arg_name： （選擇性） 要散發的引數名稱。 為了方便起見（或如果函式引數沒有名稱），允許位置預留位置，例如 '$1' 。 如果未指定此參數，則只會在背景工作角色上建立名為 function_name 的函式。 如果未來新增背景工作節點，系統也會自動在那裡建立函式。

colocate_with： （選擇性）當分散式函式讀取或寫入分散式資料表時，請務必使用 colocate_with 參數來命名該資料表。 然後，函式的每個調用都會在包含相關分區的背景工作節點上執行。

傳回值

N/A

範例

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

alter_columnar_table_set（） 函式會變更單欄資料表 上的 設定。 在非單欄式資料表上呼叫此函式會產生錯誤。 除了資料表名稱以外的所有引數都是選擇性的。

若要檢視所有單欄資料表的目前選項，請參閱下表：

SELECT * FROM columnar.options;

您可以透過這些 GUC 覆寫新建立之資料表的單欄式設定預設值：

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

引數

table_name： 單欄資料表的名稱。

chunk_row_count： （選擇性） 新插入資料每個區塊的資料列數上限。 現有的資料區塊不會變更，而且可能會有比這個最大值更多的資料列。 預設值為 10000。

stripe_row_count： （選擇性） 新插入資料的每個等量資料列數目上限。 現有的資料等量不會變更，而且資料列數目可能超過此最大值。 預設值為 150000。

compression： （選擇性） [none|pglz|zstd|lz4|lz4hc] 新插入資料的壓縮類型。 現有的資料將不會重新壓縮或解壓縮。 預設值和建議的值為 zstd（如果已編譯支援）。

compression_level： [選擇性] 有效設定是從 1 到 19。 如果壓縮方法不支援選擇的層級，則會改為選取最接近的層級。

傳回值

N/A

範例

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

alter_table_set_access_method

alter_table_set_access_method（） 函式會變更資料表的存取方法（例如堆積或單欄式）。

引數

table_name： 其存取方法將會變更的資料表名稱。

access_method： 新存取方法的名稱。

傳回值

N/A

範例

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

create_time_partitions

create_time_partitions（） 函式會建立指定間隔的資料分割，以涵蓋指定的時間範圍。

引數

table_name： 用來建立新分割區的 regclass 資料表。 資料表必須在一個資料行上分割，類型為 date、timestamp 或 timestamptz。

partition_interval： 設定新分割區範圍時所要使用的時間間隔，例如 '2 hours' 、 或 '1 month' 。

end_at： （timestamptz） 會建立最多此時間的資料分割。 最後一個分割區會包含點end_at，而且不會建立任何稍後的資料分割。

start_from： （timestamptz，選擇性）挑選第一個分割區，使其包含點start_from。 預設值是 now()。

傳回值

如果建立新的分割區需要，則為 True，如果它們都已經存在，則為 false。

範例

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

drop_old_time_partitions（） 函式會移除其間隔落在指定時間戳記之前的所有分割區。 除了使用此函式之外，您也可以考慮 alter_old_partitions_set_access_method 以單欄式儲存體壓縮舊的分割區。

引數

table_name： 要移除資料分割的 （regclass） 資料表。 資料表必須在一個資料行上分割，類型為 date、timestamp 或 timestamptz。

older_than： （timestamptz） 卸載其上層範圍小於或等於older_than的資料分割。

傳回值

N/A

範例

-- drop partitions that are over a year old

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

alter_old_partitions_set_access_method

在時間序列使用案例中，資料表通常會依時間分割，而舊的分割區會壓縮成隻讀資料行儲存體。

引數

parent_table_name： 要變更分割區的 （regclass） 資料表。 資料表必須在一個資料行上分割，類型為 date、timestamp 或 timestamptz。

older_than： （timestamptz） 變更其上層範圍小於或等於older_than的資料分割。

new_access_method： （name） 資料列式儲存體的 'heap' 或單欄式儲存體的 'columnar'。

傳回值

N/A

範例

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

中繼資料/組態資訊

get_shard_id_for_distribution_column

適用于 PostgreSQL 的 Azure Cosmos DB 會根據資料列散發資料行的值和資料表的散發方法，將分散式資料表的每個資料列指派給分區。 在大部分情況下，精確的對應是資料庫管理員可以忽略的低階詳細資料。 不過，對於手動資料庫維護工作，或只是為了滿足好奇，判斷資料列的分區很有用。 函 get_shard_id_for_distribution_column 式會提供雜湊分散式、範圍分散式和參考資料表的這項資訊。 它不適用於附加散發。

引數

table_name： 分散式資料表。

distribution_value： 散發資料行的值。

傳回值

適用于 PostgreSQL 的 Azure Cosmos DB 分區識別碼會與指定資料表的散發資料行值產生關聯。

範例

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

將 的資料 partkey 行 pg_dist_partition 轉譯為文字資料行名稱。 此轉譯有助於判斷分散式資料表的散發資料行。

如需更詳細的討論，請參閱 選擇散發資料行 。

引數

table_name： 分散式資料表。

column_var_text： 資料表中的 pg_dist_partition 值 partkey 。

傳回值

散發資料行 table_name 的名稱。

範例

-- 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;

輸出：

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

citus_relation_size

取得指定分散式資料表之所有分區所使用的磁碟空間。 磁碟空間包含「主要分支」的大小，但會排除分區的可見度對應和可用空間對應。

引數

logicalrelid： 分散式資料表的名稱。

傳回值

以位元組為單位的大小為 Bigint。

範例

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

取得指定分散式資料表的所有分區所使用的磁碟空間，不包括索引（但包括 TOAST、可用空間對應和可見度對應）。

引數

logicalrelid： 分散式資料表的名稱。

傳回值

以位元組為單位的大小為 Bigint。

範例

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

取得指定分散式資料表的所有分區所使用的磁碟空間總計，包括所有索引和 TOAST 資料。

引數

logicalrelid： 分散式資料表的名稱。

傳回值

以位元組為單位的大小為 Bigint。

範例

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

從citus_stat_statements 移除所有資料列 。 此函式與 pg_stat_statements_reset() 獨立運作。 若要重設所有統計資料，請呼叫這兩個函式。

引數

N/A

傳回值

無

citus_get_active_worker_nodes

citus_get_active_worker_nodes（） 函式會傳回使用中背景工作角色主機名稱和埠號碼的清單。

引數

N/A

傳回值

每個 Tuple 包含下列資訊的 Tuple 清單：

node_name： 背景工作節點的 DNS 名稱

node_port： 資料庫伺服器接聽的背景工作節點上的埠

範例

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

(3 rows)

叢集管理和修復

master_copy_shard_placement

如果在修改命令或 DDL 作業期間無法更新分區放置，則會將其標示為非使用中。 接著可以呼叫master_copy_shard_placement函式，以使用狀況良好的位置資料來修復非作用中的分區放置。

若要修復分區，函式會先卸載狀況不良的分區放置，然後使用協調器上的架構重新建立它。 建立分區放置之後，函式會從狀況良好的位置複製資料，並更新中繼資料，以將新的分區放置標示為狀況良好。 此函式可確保分區會在修復期間受到保護，免于任何並行修改。

引數

shard_id： 要修復之分區的識別碼。

source_node_name： 狀況良好分區放置所在的節點 DNS 名稱（「source」 節點）。

source_node_port： 資料庫伺服器正在接聽的來源背景工作節點上的埠。

target_node_name： 無效分區放置所在的節點 DNS 名稱（「target」 節點）。

target_node_port： 資料庫伺服器正在接聽的目標背景工作角色節點上的埠。

傳回值

N/A

範例

下列範例會修復分區 12345 的非使用中分區位置，該分區位於埠 5432 上執行于 'bad_host' 上的資料庫伺服器上。 若要修復，它會使用埠 5432 上執行之 'good_host' 伺服器上狀況良好分區放置的資料。

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

master_move_shard_placement

此函式會將指定的分區（以及與其共置的分區）從一個節點移至另一個節點。 它通常會在分區重新平衡期間間接使用，而不是由資料庫管理員直接呼叫。

有兩種方式可以移動資料：封鎖或非封鎖。 封鎖方法表示在移動所有修改到分區期間都會暫停。 第二種方式可避免封鎖分區寫入，依賴 Postgres 10 邏輯複寫。

成功移動作業之後，來源節點中的分區就會被刪除。 如果移動在任何時間點失敗，此函式會擲回錯誤，並讓來源和目標節點保持不變。

引數

shard_id： 要移動之分區的識別碼。

source_node_name： 狀況良好分區放置所在的節點 DNS 名稱（「source」 節點）。

source_node_port： 資料庫伺服器正在接聽的來源背景工作節點上的埠。

target_node_name： 無效分區放置所在的節點 DNS 名稱（「target」 節點）。

target_node_port： 資料庫伺服器正在接聽的目標背景工作角色節點上的埠。

shard_transfer_mode： （選擇性） 指定複寫方法，無論是使用 PostgreSQL 邏輯複寫還是跨背景工作角色 COPY 命令。 可能的值是：

• auto：如果邏輯複寫可行，則需要複本身分識別，否則請使用舊版行為（例如針對分區修復、PostgreSQL 9.6）。 這是預設值。
• force_logical：即使資料表沒有複本身分識別，仍使用邏輯複寫。 資料表的任何並行更新/刪除語句在複寫期間都會失敗。
• block_writes：針對缺少主鍵或複本身分識別的資料表使用 COPY（封鎖寫入）。

傳回值

N/A

範例

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

rebalance_table_shards

rebalance_table_shards（） 函式會移動指定資料表的分區，使其平均散發給背景工作角色。 函式會先計算它必須執行的移動清單，以確保叢集在指定的閾值內平衡。 然後，它會將分區位置逐一從來源節點移至目的地節點，並更新對應的分區中繼資料以反映移動。

判斷分區是否「平均分散」時，會為每個分區指派成本。根據預設，每個分區都有相同的成本（值為 1），因此分散以將成本等於跨背景工作角色的成本，與將每個分區的數目相等。 固定成本策略稱為「by_shard_count」，而且是預設的重新平衡策略。

在這些情況下，「by_shard_count」策略是適當的：

• 分區的大小大致相同
• 分區的流量大致相同
• 背景工作節點的大小/類型都相同
• 分區尚未釘選到特定背景工作角色

如果上述任何假設都未保留，則重新平衡「by_shard_count」可能會導致不良計畫。

預設的重新平衡策略為「by_disk_size」。 您一律可以使用 參數來自訂策略 rebalance_strategy 。

建議您在執行rebalance_table_shards之前呼叫 get_rebalance_table_shards_plan ，以查看並確認要執行的動作。

引數

table_name： （選擇性） 需要重新平衡其分區的資料表名稱。 如果為 Null，則重新平衡所有現有的共置群組。

threshold： （選擇性） 介於 0.0 和 1.0 之間的浮點數，表示節點使用率與平均使用率的最大差異比率。 例如，指定 0.1 會導致分區重新平衡器嘗試平衡所有節點，以保留相同數目的分區±10%。 具體來說，分區重新平衡器會嘗試將所有背景工作節點的使用率聚合至 （1 - 閾值） * average_utilization...(1

• threshold） * average_utilization範圍。

max_shard_moves： （選擇性） 要移動的分區數目上限。

excluded_shard_list： （選擇性） 重新平衡作業期間不應移動之分區的識別碼。

shard_transfer_mode： （選擇性） 指定複寫方法，無論是使用 PostgreSQL 邏輯複寫還是跨背景工作角色 COPY 命令。 可能的值是：

• auto：如果邏輯複寫可行，則需要複本身分識別，否則請使用舊版行為（例如針對分區修復、PostgreSQL 9.6）。 這是預設值。
• force_logical：即使資料表沒有複本身分識別，仍使用邏輯複寫。 資料表的任何並行更新/刪除語句在複寫期間都會失敗。
• block_writes：針對缺少主鍵或複本身分識別的資料表使用 COPY（封鎖寫入）。

drain_only： （選擇性） 若為 true，請將分區從已在 pg_dist_node 中 設定為 false 的背景工作節點 shouldhaveshards 移動;移動其他分區。

rebalance_strategy： （選擇性）pg_dist_rebalance_strategy 中 策略的名稱。 如果省略此引數，函式會選擇預設策略，如表格所示。

傳回值

N/A

範例

下列範例會嘗試在預設閾值內重新平衡github_events資料表的分區。

SELECT rebalance_table_shards('github_events');

此範例使用方式會嘗試重新平衡github_events資料表，而不移動識別碼為 1 和 2 的分區。

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

get_rebalance_table_shards_plan

輸出rebalance_table_shards的計畫分區移動 ，而不執行它們。 雖然不太可能，但get_rebalance_table_shards_plan可以輸出與具有相同引數的rebalance_table_shards呼叫所執行的計畫稍有不同。 它們不會同時執行，因此有關叢集的事實 -- 例如磁碟空間 -- 在呼叫之間可能會有所不同。

引數

與rebalance_table_shards相同的引數：relation、threshold、max_shard_moves、excluded_shard_list和drain_only。 如需引數的意義，請參閱該函式的檔。

傳回值

包含這些資料行的 Tuple：

• table_name ：其分區會移動的資料表
• shardid ：有問題的分區
• shard_size：以位元組為單位的大小
• sourcename ：來源節點的主機名稱
• sourceport ：來源節點的埠
• targetname ：目的地節點的主機名稱
• targetport ：目的地節點的埠

get_rebalance_progress

一旦分區重新平衡開始，函 get_rebalance_progress() 式會列出每個相關分區的進度。 它會監視所規劃和執行的 rebalance_table_shards() 移動。

引數

N/A

傳回值

包含這些資料行的 Tuple：

• sessionid ：重新平衡監視器的 Postgres PID
• table_name ：其分區移動的資料表
• shardid ：有問題的分區
• shard_size：以位元組為單位的大小
• sourcename ：來源節點的主機名稱
• sourceport ：來源節點的埠
• targetname ：目的地節點的主機名稱
• targetport ：目的地節點的埠
• progress ： 0 = 等候移動; 1 = 移動; 2 = 完成

範例

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

將資料列附加至 pg_dist_rebalance_strategy 。

引數

如需這些引數的詳細資訊，請參閱 中的 pg_dist_rebalance_strategy 對應資料行值。

name： 新策略的識別碼

shard_cost_function： 識別用來判斷每個分區「成本」的函式

node_capacity_function： 識別用來測量節點容量的函式

shard_allowed_on_node_function： 識別可決定哪些分區可以放在哪些節點上的函式

default_threshold： 調整節點之間應如何平衡累計分區成本的浮點臨界值

minimum_threshold： （選擇性）保留rebalance_table_shards（） 臨界值引數允許的保護資料行。 其預設值為 0

傳回值

N/A

citus_set_default_rebalance_strategy

更新pg_dist_rebalance_strategy 資料表，將其引數所命名的策略變更為重新平衡分區時選擇的預設。

引數

name： pg_dist_rebalance_strategy中策略的名稱

傳回值

N/A

範例

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

citus_remote_connection_stats（） 函式會顯示每個遠端節點的作用中連線數目。

引數

N/A

範例

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

此函式會建立新的分區，以保存散發資料行中具有特定單一值的資料列。 對於多租使用者使用案例來說，它特別方便，其中大型租使用者可以單獨放在自己的分區上，最後是自己的實體節點。

引數

table_name： 要取得新分區的資料表名稱。

tenant_id： 將指派給新分區之散發資料行的值。

cascade_option： （選擇性） 當設定為 「CASCADE」 時，也會隔離分區與目前資料表共置群組 中的所有資料表 。

傳回值

shard_id： 函式會傳回指派給新建立分區的唯一識別碼。

範例

建立新的分區，以保存租使用者 135 的 lineitems：

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

下一步

• 本文中的許多函式會修改系統 中繼資料表
• 伺服器參數 自訂某些函式的行為