適用於 PostgreSQL 的 Azure Cosmos DB 函式

發行項
08/15/2024

適用於： Azure Cosmos DB for PostgreSQL (由 PostgreSQL 的超大規模 (Citus) 資料庫延伸模組提供)

本節包含適用於 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_with default， 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 │
└─────────────────────────────┘

下一步

本文中的許多函式會修改系統元數據表
伺服器參數自定義某些函式的行為

共用方式為

適用於 PostgreSQL 的 Azure Cosmos DB 函式

數據表和分區 DDL

citus_schema_distribute

引數

傳回值

範例

citus_schema_undistribute

引數

傳回值

範例

create_distributed_table

引數

傳回值

範例

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

引數

傳回值

範例

create_reference_table

引數

傳回值

範例

citus_add_local_table_to_metadata

引數

傳回值

範例

alter_distributed_table

引數

傳回值

範例

update_distributed_table_colocation

引數

傳回值

範例

undistribute_table

引數

傳回值

範例

create_distributed_function

引數

傳回值

範例

alter_columnar_table_set

引數

傳回值

範例

alter_table_set_access_method

引數

傳回值

範例

create_time_partitions

引數

傳回值

範例

drop_old_time_partitions

引數

傳回值

範例

alter_old_partitions_set_access_method

引數

傳回值

範例

元數據/組態資訊

get_shard_id_for_distribution_column

引數

傳回值

範例

column_to_column_name

引數

傳回值

範例

citus_relation_size

引數

傳回值

範例

citus_table_size

引數

傳回值