Azure Cosmos DB for PostgreSQL の関数
適用対象: 
Azure Cosmos DB for PostgreSQL (PostgreSQL の Citus データベース拡張機能を利用)
このセクションでは、Azure Cosmos DB for PostgreSQL によって提供されるユーザー定義関数の参照情報について説明します。 これらの関数は、Azure Cosmos DB for PostgreSQL に分散機能を提供するのに役立ちます。
Note
以前のバージョンの Citus エンジンを実行しているクラスターでは、このページに記載されているすべての機能が提供されない場合があります。
テーブルおよびシャードの DDL
citus_schema_distribute
既存の標準スキーマを分散スキーマに変換します。 分散スキーマは、個々のコロケーション グループと自動的に関連付けられます。 これらのスキーマで作成されたテーブルは、シャード キーなしで併置された分散テーブルに変換されます。 スキーマを配布するプロセスでは、スキーマが自動的に割り当てられ、クラスター内の既存のノードに移動されます。
引数
schemaname: 分散する必要があるスキーマの名前。
戻り値
該当なし
例
SELECT citus_schema_distribute('tenant_a');
SELECT citus_schema_distribute('tenant_b');
SELECT citus_schema_distribute('tenant_c');
その他の例については、マイクロサービスの設計 方法に関するを参照してください。
citus_schema_undistribute
既存の分散スキーマを通常のスキーマに変換します。 このプロセスにより、テーブルとデータが現在のノードからクラスター内のコーディネーター ノードに移動されます。
引数
schemaname: 分散する必要があるスキーマの名前。
戻り値
該当なし
例
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: (省略可能) テーブルの分散に使用される方法。 許容される値は append または hash で、既定値は 'hash' です。
colocate_with: (省略可能) 現在のテーブルを別のテーブルのコロケーション グループに含めます。 既定では、テーブルが同じ型の列によって分散され、同じシャード数を持ち、レプリケーション係数が同じ場合にそのテーブルは併置されます。 colocate_with に使用できる値は default、新しいコロケーション グループを開始する場合の none、またはそのテーブルと併置する別のテーブルの名前です。 (テーブル コロケーションに関するページを参照してください。)
colocate_with の既定値を使用すると、暗黙的にコロケーションが行われることに注意してください。 コロケーションは、テーブルが関連付けられている場合や結合される場合に便利です。 ただし、2 つのテーブルが互いに関連付けられておらず、ディストリビューション列に同じデータ型を使用する場合、誤って併置するとシャード再調整中のパフォーマンスが低下する可能性があります。 テーブルのシャードが、不必要に、"カスケード" で一緒に移動されます。
新しい分散テーブルが他のテーブルに関連付けられていない場合は、colocate_with => 'none' を指定することをお勧めします。
shard_count: (省略可能) 新しい分散テーブル用に作成するシャードの数。 shard_count を指定するとき、「なし」以外の colocate_with の値は指定できません。 既存のテーブルまたはコロケーション グループのシャード カウントを変更するには、alter_distributed_table 関数を使用します。
shard_count に指定できる値は 1 から 64000 までです。 最適な値を選択するためのガイダンスについては、「シャード数」を参照してください。
戻り値
該当なし
例
この例では、github_events テーブルが、repo_id 列に基づいて hash で分散される必要があることをデータベースに通知しています。
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 にはいくつかの制限があります。
- この関数はトランザクション ブロックでは使用できないため、一度に 1 つのテーブルしか配布できません。 (ただし 、時間パーティションテーブルでは 関数を使用できます)。
- テーブルが外部キーによって参照されている場合や別のローカル テーブルを参照している場合は、
create_distributed_table_concurrentlyを使用できません。 ただし、参照テーブルへの外部キーは機能し、テーブルの配布の完了後に他の分散テーブルへの外部キーを作成できます。 - テーブルに主キーまたはレプリカ ID がない場合、論理レプリケーションの制限により、テーブルの配布中に更新コマンドと削除コマンドが失敗します。
truncate_local_data_after_distributing_table
テーブルの分散後、すべてのローカル行を切り詰め、ローカル レコードが古いことで制約が失敗するのを回避します。 切り詰めは、指定されたテーブルへの外部キーを持つテーブルにカスケードされます。 参照元のテーブル自体が分散されない場合、参照整合性を保護するために、そうなるまで切り詰めは禁止されます。
ERROR: cannot truncate a table referenced in a foreign key constraint by a local table
分散テーブルでは、その行 (存在する場合) が、分散中はワーカー ノードにコピーされるため、ローカル コーディネーター ノードのテーブル データの切り詰めは安全です。
引数
table_name: コーディネーター ノード上の対応するローカル テーブルを切り詰める分散テーブルの名前。
戻り値
該当なし
例
-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');
create_reference_table
create_reference_table() 関数は、小さな参照またはディメンション テーブルを定義するために使用されます。 この関数はテーブル名を受け取り、すべてのワーカー ノードにレプリケートされる 1 つのシャードのみを含む分散テーブルを作成します。
引数
table_name: 分散する必要がある小さなディメンションまたは参照テーブルの名前。
戻り値
該当なし
例
この例では、nation テーブルを参照テーブルとして定義する必要があることをデータベースに通知しています
SELECT create_reference_table('nation');
citus_add_local_table_to_metadata
Citus メタデータにローカル Postgres テーブルを追加します。 この関数の主なユース ケースは、コーディネーター上のローカル テーブルをクラスター内の任意のノードからアクセスできるようにすることです。 ローカル テーブルに関連付けられたデータはコーディネーターにとどまり、そのスキーマとメタデータのみがワーカーに送信されます。
メタデータへのローカル テーブルの追加にはわずかなコストがかかります。 テーブルを追加する場合、Citus はテーブルを partition テーブルで追跡する必要があります。 メタデータに追加されるローカル テーブルは、参照テーブルと同じ制限を継承します。
テーブルの属性を解除すると、Citus は結果のローカル テーブルをメタデータから削除します。これにより、これらのテーブルに対するこのような制限がなくなります。
引数
table_name: Citus メタデータに追加するコーディネーターのテーブルの名前。
cascade_via_foreign_keys: (省略可能) この引数が "true" に設定されている場合、citus_add_local_table_to_metadataは、指定されたテーブルとの外部キー リレーションシップにある他のテーブルをメタデータに自動的に追加します。 多くのテーブルに影響する可能性があるため、このパラメーターは慎重に使用してください。
戻り値
該当なし
例
この例では、どのノードからでもアクセスできるコーディネーター ローカル テーブルとして国家テーブルを定義する必要があることをデータベースに通知します。
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" の場合、このテーブルの現在のコロケーションは解除されます。
戻り値
該当なし
例
-- 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() 関数は、分散テーブルのコロケーションを更新する目的に使用されます。 また、分散テーブルのコロケーションを解除する際にも、この関数が使用されます。 分散列の型が同じである 2 つのテーブルは、Azure Cosmos DB for PostgreSQL によって暗黙的に併置されます。これは、それらのテーブルにリレーションがあり、なんらかの結合が行われる場合に役立ちます。 テーブル A と B が併置されているとき、テーブル A が再調整されると、テーブル B も再調整されます。 テーブル B にレプリカ ID がない場合、再調整は失敗します。 その場合に暗黙的なコロケーションを解除する目的で、この関数を利用できます。
この関数によって、物理的にデータが移動されることはありません。
引数
table_name: 更新するテーブル コロケーションの名前。
colocate_with: このテーブルと併置するテーブル。
テーブルのコロケーションを解除したい場合は、colocate_with => 'none' を指定する必要があります。
戻り値
該当なし
例
この例では、テーブル 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 or create_reference_table の操作を元に戻します。 Undistribute (分散解除) では、シャードのすべてのデータがコーディネーター ノード上の元のローカル テーブルに (データが適合する場合) 移動され、シャードが削除されます。
外部キーを持つテーブルや外部キーによって参照されているテーブルは、cascade_via_foreign_keys 引数を true に設定しない限り、Azure Cosmos DB for PostgreSQL によって分散解除されません。 この引数を false に (または省略した) 場合は、分散を解除する前に、問題となっている外部キー制約を手動で削除する必要があります。
引数
table_name: 分散解除の対象となる分散テーブルまたは参照テーブルの名前。
cascade_via_foreign_keys: (省略可) この引数を "true" に設定すると、外部キーによって table_name と関連付けられているテーブルもすべて分散解除されます。 多くのテーブルに影響する可能性があるため、このパラメーターは慎重に使用してください。
戻り値
該当なし
例
この例では、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
コーディネーター ノードからワーカーに関数を伝達し、分散実行用にマークします。 コーディネーターで分散関数が呼び出されると、Azure Cosmos DB for PostgreSQL は "分散引数" の値を使って、関数を実行するワーカー ノードを選びます。 ワーカーで関数を実行すると並列処理が増加し、待機時間が短くなるようにコードをシャード内のデータに近づけることができます。
分散関数の実行中に、Postgres 検索パスはコーディネーターからワーカーに伝達されません。そのため分散関数コードでは、データベース オブジェクトの名前を完全修飾する必要があります。 また、関数によって出力された通知もユーザーに表示されません。
引数
function_name: 分散される関数の名前。 PostgreSQL では複数の関数が同じ名前を持つことができるため、名前には関数のパラメーターの型をかっこで囲んで指定する必要があります。 たとえば、'foo(int)' は 'foo(int, text)' とは異なります。
distribution_arg_name: (省略可能) 分散に使用される引数の名前。 便宜上 (または関数の引数に名前がない場合) は、'$1' のような位置指定プレースホルダーを使用できます。 このパラメーターが指定されていない場合、function_name で指定された関数が単にワーカーに作成されます。 ワーカー ノードが今後追加される場合、関数もそこに自動的に作成されます。
colocate_with: (省略可能) 分散された関数が分散テーブル (または、より一般的にはコロケーション グループ) に対して読み取りまたは書き込みを行う場合は、colocate_with パラメーターを使用してそのテーブルの名前を指定してください。 その後、関数の各呼び出しは、関連するシャードを含むワーカー ノードで実行されます。
戻り値
該当なし
例
-- 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 です。 圧縮方法で選択したレベルがサポートされていない場合は、代わりに最も近いレベルが選択されます。
戻り値
該当なし
例
SELECT alter_columnar_table_set(
'my_columnar_table',
compression => 'none',
stripe_row_count => 10000);
alter_table_set_access_method
alter_table_set_access_method() 関数は、テーブルのアクセス方法 (heap、columnar など) を変更します。
引数
table_name: アクセス方法を変更するテーブルの名前。
access_method: 新しいアクセス方法の名前。
戻り値
該当なし
例
SELECT alter_table_set_access_method('github_events', 'columnar');
create_time_partitions
create_time_partitions() 関数は、特定の時間範囲を含む特定の間隔のパーティションを作成します。
引数
table_name: (regclass) 新しいパーティションを作成するテーブル。 このテーブルは、date、timestamp、timestamptz のいずれかの型の 1 つの列に基づいてパーティション分割されている必要があります。
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 のいずれかの型の 1 つの列に基づいてパーティション分割されている必要があります。
older_than: (timestamptz) 上限が older_than と等しいかそれよりも小さいパーティションが削除されます。
戻り値
該当なし
例
-- 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 のいずれかの型の 1 つの列に基づいてパーティション分割されている必要があります。
older_than: (timestamptz) 上限が older_than と等しいかそれよりも小さいパーティションが変更されます。
new_access_method: (name) 行ベースのストレージの場合は ‘heap’、カラム型ストレージの場合は ‘columnar’ です。
戻り値
該当なし
例
CALL alter_old_partitions_set_access_method(
'foo', now() - interval '6 months',
'columnar'
);
メタデータ / 構成情報
get_shard_id_for_distribution_column
Azure Cosmos DB for PostgreSQL は、行のディストリビューション列の値とテーブルの分散方法に基づいて、分散テーブルのすべての行をシャードに割り当てます。 ほとんどの場合、この正確なマッピングはデータベース管理者は無視してもかまわない低レベルの細かい内容です。 ただし、手動によるデータベース メンテナンス タスクの場合や、興味を満たすための場合には、行のシャードを決定すると便利です。 get_shard_id_for_distribution_column 関数は、ハッシュ分散、範囲分散、参照の各テーブルに対してこの情報を提供します。 追加分散では機能しません。
引数
table_name: 分散テーブル。
distribution_value: ディストリビューション列の値。
戻り値
Azure Cosmos DB for PostgreSQL によって、指定されたテーブルのディストリビューション列の値に関連付けられるシャード ID。
例
SELECT get_shard_id_for_distribution_column('my_table', 4);
get_shard_id_for_distribution_column
--------------------------------------
540007
(1 row)
column_to_column_name
pg_dist_partition の partkey 列をテキストの列の名前に変換します。 この変換は、分散テーブルのディストリビューション列を特定するのに役立ちます。
詳細については、ディストリビューション列の選択に関するページを参照してください。
引数
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() からは独立して動作します。 すべての統計をリセットするには、両方の関数を呼び出します。
引数
該当なし
戻り値
なし
citus_get_active_worker_nodes
citus_get_active_worker_nodes() 関数は、アクティブなワーカー ホストの名前とポート番号のリストを返します。
引数
該当なし
戻り値
タプルのリスト。各タプルには次の情報が含まれています。
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: 修復するシャードの ID。
source_node_name: 正常なシャードの配置が存在するノードの DNS 名 ("ソース" ノード)。
source_node_port: データベース サーバーがリッスンしているソース ワーカー ノードのポート。
target_node_name: 無効なシャードの配置が存在するノードの DNS 名 ("ターゲット" ノード)。
target_node_port: データベース サーバーがリッスンしているターゲット ワーカー ノードのポート。
戻り値
該当なし
例
次の例では、ポート 5432 の 'bad_host' 上で実行されているデータベース サーバー上に存在する、シャード 12345 の非アクティブなシャード配置を修復します。 修復には、ポート 5432 の 'good_host' 上で実行されているサーバー上に存在する正常なシャード配置のデータが使用されます。
SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);
master_move_shard_placement
この関数を使用すると、指定されたシャード (およびそれに併置されているシャード) が、あるノードから別のノードに移動します。 通常は、データベース管理者によって直接呼び出されるのではなく、シャードの再調整時に間接的に使用されます。
データの移動には、ブロッキングと非ブロッキングの 2 つの方法があります。 ブロッキング アプローチとは、移動中に、シャードに対するすべての変更が一時停止されることを意味します。 2 番目の方法は、シャードへの書き込みのブロックを回避するために Postgres 10 の論理レプリケーションに依存しています。
移動操作が正常に完了すると、ソース ノードのシャードが削除されます。 いずれかの時点で移動が失敗した場合、この関数によってエラーがスローされ、ソース ノードとターゲット ノードは変更されないまま残されます。
引数
shard_id: 移動するシャードの ID。
source_node_name: 正常なシャードの配置が存在するノードの DNS 名 ("ソース" ノード)。
source_node_port: データベース サーバーがリッスンしているソース ワーカー ノードのポート。
target_node_name: 無効なシャードの配置が存在するノードの DNS 名 ("ターゲット" ノード)。
target_node_port: データベース サーバーがリッスンしているターゲット ワーカー ノードのポート。
shard_transfer_mode: (省略可能) レプリケーションの方法として、PostgreSQL 論理レプリケーションを使用するか、ワーカー間の COPY コマンドを使用するかを指定します。 指定できる値は、
auto:論理レプリケーションが可能な場合はレプリカ ID を必要とします。それ以外の場合は、レガシの動作を使用します (例: シャード修復の場合は、PostgreSQL 9.6)。 これが既定値です。force_logical:テーブルにレプリカ ID がない場合でも、論理レプリケーションを使用します。 レプリケーション中は、テーブルに対して UPDATE/DELETE ステートメントを同時に実行することはできません。block_writes:主キーまたはレプリカ ID がないテーブルには、COPY (書き込みをブロックします) を使用します。
戻り値
該当なし
例
SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);
rebalance_table_shards
rebalance_table_shards() 関数は、指定されたテーブルのシャードを移動して、ワーカー間で均等に分散します。 この関数では、クラスターが指定されたしきい値内で分散されるようにするために、必要な移動のリストが最初に計算されます。 次に、シャードの配置をソース ノードから宛先ノードに 1 つずつ移動し、対応するシャード メタデータを更新して移動を反映します。
シャードが "均等に分散" されたかどうかを判断する際には、すべてのシャードにコストが割り当てられます。既定では、各シャードのコスト (値 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
- しきい値) * average_utilization の範囲に収束させようとします。
max_shard_moves: (省略可能) 移動するシャードの最大数。
excluded_shard_list: (省略可能) 再調整操作中に移動しないシャードの識別子。
shard_transfer_mode: (省略可能) レプリケーションの方法として、PostgreSQL 論理レプリケーションを使用するか、ワーカー間の COPY コマンドを使用するかを指定します。 指定できる値は、
auto:論理レプリケーションが可能な場合はレプリカ ID を必要とします。それ以外の場合は、レガシの動作を使用します (例: シャード修復の場合は、PostgreSQL 9.6)。 これが既定値です。force_logical:テーブルにレプリカ ID がない場合でも、論理レプリケーションを使用します。 レプリケーション中は、テーブルに対して UPDATE/DELETE ステートメントを同時に実行することはできません。block_writes:主キーまたはレプリカ ID がないテーブルには、COPY (書き込みをブロックします) を使用します。
drain_only: (省略可能) true の場合、pg_dist_node で shouldhaveshards が false に設定されているワーカー ノードからシャードを移動します。他のシャードは移動しません。
rebalance_strategy: (省略可能) pg_dist_rebalance_strategy 内の戦略の名前。 この引数を省略した場合、関数では、表に示されているように既定の戦略が選択されます。
戻り値
該当なし
例
次の例では、github_events テーブルのシャードを既定のしきい値内に再調整しようとしています。
SELECT rebalance_table_shards('github_events');
こちらの使用例では、ID 1 および 2 のシャードを移動せずに github_events テーブルを再調整しようとしています。
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。 引数の意味については、その関数のドキュメントを参照してください。
戻り値
次の列を含むタプル:
- table_name: シャードが移動するテーブル
- shardid:問題のシャード
- shard_size: バイト単位のサイズ
- sourcename:ソース ノードのホスト名
- sourceport:ソース ノードのポート
- targetname:宛先ノードのホスト名
- targetport:宛先ノードのポート
get_rebalance_progress
シャードの再調整が開始されると、get_rebalance_progress() 関数によって、関連するすべてのシャードの進行状況が一覧表示されます。 rebalance_table_shards() によって計画および実行された移動が監視されます。
引数
該当なし
戻り値
次の列を含むタプル:
- 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() の threshold 引数に許容される最小値を保持するセーフガード列。 既定値は 0 です
戻り値
該当なし
citus_set_default_rebalance_strategy
pg_dist_rebalance_strategy テーブルを更新して、引数で指定された戦略がシャードの再調整時に既定で選択されるように変更します。
引数
name: pg_dist_rebalance_strategy 内の戦略の名前
戻り値
該当なし
例
SELECT citus_set_default_rebalance_strategy('by_disk_size');
citus_remote_connection_stats
citus_remote_connection_stats() 関数は、各リモート ノードへのアクティブな接続の数を示します。
引数
該当なし
例
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: この関数は、新しく作成されたシャードに割り当てられた一意の ID を返します。
例
テナント 135 の lineitems を保持する新しいシャードを作成します。
SELECT isolate_tenant_to_new_shard('lineitem', 135);
┌─────────────────────────────┐
│ isolate_tenant_to_new_shard │
├─────────────────────────────┤
│ 102240 │
└─────────────────────────────┘
次の手順
- この記事の関数の多くは、システム メタデータ テーブルを変更します
- サーバー パラメーターにより、一部の関数の動作をカスタマイズします