你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure Cosmos DB for PostgreSQL 函数

项目
08/15/2024

适用对象：PostgreSQL 的 Azure Cosmos DB （由 PostgreSQL 的 Citus 数据库扩展提供支持）

本部分包含有关 Azure Cosmos DB for PostgreSQL 提供的用户定义函数的参考信息。这些函数有助于向 Azure Cosmos DB for PostgreSQL 提供分布式功能。

注意

运行旧版 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() 函数用于定义分布式表，并且如果它是哈希分布式表，还用于创建它的分片。此函数采用表名称、分布列和可选的分发方法，并插入适当的元数据以将表标记为分布式。如果未指定分布方法，则函数默认为“哈希”分布。如果表是哈希分布式，则该函数还基于分片计数和分片复制因子配置值创建工作器分片。如果表包含任何行，会将这些行自动分布到工作器节点。

此函数取代了master_create_distributed_table() 后跟 master_create_worker_shards() 的用法。

参数

table_name：需要分布的表名称。

distribution_column：表分布到的列。

distribution_type：（可选）表分布的依据方法。允许值为“追加”或“哈希”，默认值为“哈希”。

colocate_with：（可选）将当前表包含在另一个表的并置组中。默认情况下，当表是由同一类型的列分布、具有相同的分片计数，并且具有相同的复制因子时，将并置这些表。 colocate_with 的可能值为 default、启动新并置组的 none，或与该表并置的另一个表的名称。（参见表并置。）

请记住，colocate_with 的默认值进行隐式并置。在表之间相关或将互相联接时，并置可能是很好的做法。但是，如果两个表不相关，但它们的分布列使用相同的数据类型，则意外并置这些表会在分片再平衡期间降低性能。表分片将以“级联”方式不必要地一起移动。

如果新的分布式表与其他表不相关，最好指定 colocate_with => 'none'。

shard_count：（可选）要为新分布式表创建的分片数。指定 shard_count 时，不能为 colocate_with 指定除 none 以外的值。若要更改现有表或共置组的分片计数，请使用 alter_distributed_table 函数。

shard_count 的可能值介于 1 到 64000 之间。有关如何选择最佳值的指南，请参阅分片计数。

返回值

不适用

示例

此示例通知数据库：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：应截断其协调器节点上的本地对应项的分布式表的名称。

返回值

不适用

示例

-- 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：需要分布的小型维度表或引用表的名称。

返回值

不适用

示例

此示例通知数据库：国家表应定义为引用表

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 会自动将与给定表具有外键关系的其他表添加到元数据中。请谨慎使用此参数，因为它可能会影响多个表。

返回值

不适用

示例

此示例通知数据库：国家表应定义为可从任何节点访问的协调器本地表：

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() 函数用于更新分布式表的并置。此函数也可用于中断分布式表的并置。如果分布列为同一类型，则 Azure Cosmos DB for PostgreSQL 将隐式并置两个表，如果这些表是相关的并且将执行一些联接，则这会很有用。如果并置了表 A 和 B，且表 A 获得重新平衡，则表 B 也将进行重新平衡。如果表 B 没有副本标识，则重新平衡将会失败。因此，在这种情况下，此函数可用于中断隐式并置。

此函数不会在物理上移动任何数据。

参数

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 或 create_reference_table 的操作。取消分发会将所有数据从分片移回协调器节点上的本地表（假设数据可以容纳），然后删除分片。

Azure Cosmos DB for PostgreSQL 不会取消分发具有外键或被外键引用的表，除非 cascade_via_foreign_keys 参数设置为 true。如果此参数为 false（或省略），则必须在取消分发之前手动删除有问题的外键约束。

参数

table_name：要取消分发的已分发表或引用表的名称。

cascade_via_foreign_keys：（可选）当此参数设置为“true”时，undistribute_table 还会取消分发所有通过外键与 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() 函数更改表的访问方法（例如堆或纵栏）。

参数

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 类型在一列上进行分区。

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) 删除上限范围小于或等于 old_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 类型在一列上进行分区。

older_than：(timestamptz) 更改上限范围小于或等于 old_than 的分区。

new_access_method：(name)“堆”用于基于行的存储，或“纵栏”用于纵栏存储。

返回值

不适用

示例

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：分布列的值。

返回值

分片 ID Azure Cosmos DB for PostgreSQL 与给定表的分布列值关联。

示例

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：数据库服务器正在侦听的目标工作器节点上的端口。

返回值

不适用

示例

下面的示例将修复分片 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：要移动的分片的 ID。

source_node_name：存在正常分片放置的节点的 DNS 名称（“源”节点）。

source_node_port：数据库服务器正在侦听的源工作器节点上的端口。

target_node_name：存在无效分片放置的节点的 DNS 名称（“目标”节点）。

target_node_port：数据库服务器正在侦听的目标工作器节点上的端口。

shard_transfer_mode：（可选）指定复制方法，是使用 PostgreSQL 逻辑复制还是使用跨工作器 COPY 命令。可能的值包括：

auto：如果可以进行逻辑复制，则需要副本标识，否则使用旧行为（例如，对于分片修复，使用 PostgreSQL 9.6）。这是默认值。

force_logical：使用逻辑复制，即使该表没有副本标识。在复制过程中对表的任何并发更新/删除语句都将失败。

block_writes：对缺少主键或副本标识的表使用 COPY 命令（阻止写入）。

返回值

不适用

示例

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 - threshold) * 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 中将 shouldhaveshards 设为 false 的分片从工作器节点移出；不移动其他分片。

rebalance_strategy：（可选）pg_dist_rebalance_strategy 中策略的名称。如果省略此参数，则函数将选择默认策略，如表中所示。

返回值

不适用

示例

下面的示例将在默认阈值内尝试再平衡 github_events 表的分片。

SELECT rebalance_table_shards('github_events');

此示例将尝试再平衡 github_events 表，而不移动 ID 为 1 和 2 的分片。

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

get_rebalance_table_shards_plan

输出 rebalance_table_shards 的计划分片移动，而不执行该移动。虽然不太可能，但使用相同参数的 rebalance_table_shards 调用会输出一个计划，get_rebalance_table_shards_plan 输出的计划与以上这个计划稍有不同。它们不会同时执行，因此群集（例如，磁盘空间）可能会因调用而异。

参数

与 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() 阈值参数的允许最小值。默认值为 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 的排列项：

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

后续步骤

本文中的许多函数可修改系统元数据表
服务器参数可定义一些函数的行为