在 Citus 架构中，协调器节点负责接收用户的 SQL 请求，并将其拆解成多个可在各个工作节点分片上并行执行的小查询。这种方式实现了查询在整个集群中的高效分布执行。

不过，不同的 SQL 类型决定了如何拆分及分发查询。在一些复杂的场景下，开发者可能希望手动干预这一过程。为此，Citus 提供了几个函数接口用于直接向工作节点、分片或具体的数据副本发送 SQL 命令。

使用这些手动传播功能时需格外谨慎，因为它们绕过了协调器层面的一致性保障、并发控制等安全机制。若使用不当，可能导致数据不一致甚至系统死锁等问题。这类方法通常只应在常规手段无法满足需求的情况下才考虑采用。

向所有工作节点广播命令

最基本的操作是将某条 SQL 语句广播至集群内的全部工作节点。该操作适用于获取全局配置信息或者统一设置参数。

-- 查看每个工作节点的 work_mem 参数值
SELECT run_command_on_workers($cmd$ SHOW work_mem; $cmd$);

注意：
不应通过此方式在各工作节点上创建数据库对象，否则会影响后续动态扩展工作节点的能力。
此外，本节所介绍的函数仅支持返回单列表、单行结果集的查询语句。

在指定表的所有分片上执行命令

进一步细化控制粒度，我们可以将 SQL 发送到某个分布式表对应的所有分片上。这常用于需要访问底层物理存储元数据的情况，如统计每张分片上的记录数量。

-- 统计一张分布式表总行数（基于每个分片的估算）
SELECT sum(result::bigint) AS estimated_count
FROM run_command_on_shards(
  'my_distributed_table',
  $cmd$
    SELECT reltuples
    FROM pg_class c
    JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace
    WHERE (n.nspname || '.' || relname)::regclass = '%s'::regclass
      AND n.nspname NOT IN ('citus', 'pg_toast', 'pg_catalog')
  $cmd$
);

作用于所有分片副本

最为细致的控制单位是对每一个分片及其所有副本（placement）分别执行命令。这种做法适合那些要求强一致性的写入操作，比如更新全部副本的内容。

-- 更新所有分片副本中的 updated_at 字段为固定时间戳
SELECT run_command_on_placements(
  'my_distributed_table',
  $cmd$
    UPDATE %s SET updated_at = '2017-01-01';
  $cmd$
);

与之配套使用的还有另一个实用工具函数 run_command_on_colocated_placements，它可以同时引用两张具有相同分布策略的表的位置信息。借助这个特性，可以实现跨表联动更新或其他高级功能，例如触发器同步：

-- 创建两个分布键相同的表
CREATE TABLE small_data (id int, value int);
CREATE TABLE large_data (id int, value int);
SELECT create_distributed_table('small_data', 'id');
SELECT create_distributed_table('large_data', 'id');

-- 定义触发器函数，用于将小表插入的数据放大后写入大表
CREATE OR REPLACE FUNCTION expand_value() RETURNS TRIGGER AS $$
BEGIN
  IF (TG_OP = 'INSERT') THEN
    EXECUTE format(
      'INSERT INTO %s (id, value) VALUES ($1.id, $1.value * 2);',
      TG_ARGV[0]
    ) USING NEW;
  END IF;
  RETURN NULL;
END;
$$ LANGUAGE plpgsql;

-- 对共址表建立触发器关联
SELECT run_command_on_colocated_placements(
  'small_data',
  'large_data',
  $cmd$
    CREATE TRIGGER sync_insert AFTER INSERT ON %s
      FOR EACH ROW EXECUTE PROCEDURE expand_value(%L)
  $cmd$
);

注意事项

• 手动传播不包含多事务环境下的防死锁保护机制。
• 缺乏对中途错误导致部分成功情况的恢复能力。
• 查询结果会被完整加载进内存，不适合大数据量输出。
• 如果任一目标节点不可达，则整个调用会立即报错终止。
• 滥用此类功能可能带来严重后果，请务必慎重使用。