Функции Azure Cosmos DB для PostgreSQL

Статья
09/29/2023

Область применения: Azure Cosmos DB для PostgreSQL (на базе расширения базы данных Citus до PostgreSQL)

В этом разделе содержатся справочные сведения о определяемых пользователем функциях, предоставляемых Azure Cosmos DB для PostgreSQL. Эти функции помогают обеспечить распределенную функциональность в Azure Cosmos DB для PostgreSQL.

Примечание.

Кластеры под управлением более старых версий обработчика Citus могут не предлагать все функции, перечисленные на этой странице.

Таблицы и сегменты DDL

citus_schema_distribute

Преобразует существующие обычные схемы в распределенные схемы. Распределенные схемы автоматически связаны с отдельными группами совместного размещения. Таблицы, созданные в этих схемах, преобразуются в совместно размещенные распределенные таблицы без ключа сегмента. Процесс распространения схемы автоматически назначается и перемещает его на существующий узел в кластере.

Аргументы

имя схемы: имя схемы, которая должна быть распределена.

Возвращаемое значение

Н/П

Пример

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

Дополнительные примеры см. в руководстве по проектированию микрослужб.

citus_schema_undistribute

Преобразует существующую распределенную схему обратно в обычную схему. Процесс приводит к перемещению таблиц и данных из текущего узла обратно в узел координатора в кластере.

Аргументы

имя схемы: имя схемы, которая должна быть распределена.

Возвращаемое значение

Н/П

Пример

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 не является неявным совместным размещением. Совместное размещение может быть отличным решением, если таблицы связаны или будут объединены. Однако если две таблицы не связаны, но при этом используют один и тот же тип данных для столбцов распределения, их случайное совместное размещение может снизить производительность во время перераспределения сегментов. Сегменты таблицы будут без необходимости перемещаться "каскадно".

Если новая распределенная таблица не связана с другими таблицами, лучше указать colocate_with => 'none'.

shard_count: (необязательно) количество сегментов, создаваемых для новой распределенной таблицы. При указании shard_count не удается указать значение colocate_with , отличное от ни одного. Чтобы изменить количество сегментов существующей таблицы или группы совместного размещения, используйте функцию 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 , если таблица ссылается на внешний ключ или ссылается на другую локальную таблицу. Однако внешние ключи для ссылок на таблицы работают, и вы можете создать внешние ключи к другим распределенным таблицам после завершения распределения таблиц.
Если у вас нет первичного ключа или удостоверения реплика в таблице, обновление и удаление команд завершится ошибкой во время распространения таблицы из-за ограничений на логические реплика tion.

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: имя небольшой таблицы измерения или ссылочной таблицы, которую необходимо распределить.

Возвращаемое значение

Н/П

Пример

В этом примере база данных получает информацию о том, что таблица "nation" должна быть определена как ссылочная таблица.

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 для 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 для PostgreSQL не отменяет distribute таблицы, имеющие или ссылающиеся на внешние ключи, если аргумент 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 для 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: (необязательно) максимальное число строк на полосу для вновь вставляемых данных. Существующие полосы данных не будут изменены и могут иметь больше строк, чем это максимальное значение. Значение по умолчанию — 150 000.

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) удаление секций, верхний диапазон которых меньше или равен 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.

older_than: (timestamptz) изменение секций, верхний диапазон которых меньше или равен older_than.

new_access_method: (имя) либо кучи для хранилища на основе строк, либо columnar для хранилища columnar.

Возвращаемое значение

Н/П

Пример

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

Метаданные или сведения о конфигурации

get_shard_id_for_distribution_column

Azure Cosmos DB для PostgreSQL назначает каждую строку распределенной таблицы сегменту на основе значения столбца распределения строки и метода распределения таблицы. В большинстве случаев точное сопоставление является самым низким уровнем детализации, который администратор базы данных может игнорировать. Однако может быть полезно определить сегмент строки либо для задач обслуживания базы данных вручную, либо из любопытства. Функция get_shard_id_for_distribution_column предоставляет эти сведения для хэш-распределения, распределения по диапазону и ссылочных таблиц. Она не подходит для распределения методом добавления.

Аргументы

table_name: имя распределенной таблицы.

distribution_value: значение столбца распределения.

Возвращаемое значение

Идентификатор сегмента Azure Cosmos DB для PostgreSQL связывается со значением столбца распространения для данной таблицы.

Пример

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: значение partkey в таблице pg_dist_partition.

Возвращаемое значение

Имя столбца распределения для 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: идентификатор сегмента, который необходимо восстановить.

source_node_name: DNS-имя узла, в котором есть работоспособное размещение сегмента ("исходный" узел).

source_node_port: порт на исходном рабочем узле, который прослушивается сервером базы данных.

target_node_name: DNS-имя узла, на котором есть недопустимое размещение сегмента ("целевой" узел).

target_node_port: порт на целевом рабочем узле, который прослушивается сервером базы данных.

Возвращаемое значение

Н/П

Пример

В приведенном ниже примере исправляется неактивное размещение сегмента 12345, которое присутствует на сервере базы данных, работающем на узле bad_host на порте 5432. Для восстановления будут использоваться данные из работоспособного расположения сегмента, присутствующего на сервере, который работает на узле good_host на порте 5432.

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_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 параметра.

Рекомендуется вызвать функцию get_rebalance_table_shards_plan перед выполнением функции rebalance_table_shards, чтобы просмотреть и проверить действия, которые необходимо выполнить.

Аргументы

table_name: (необязательно) имя таблицы, сегменты которой необходимо перераспределить. Если значение равно NULL, перераспределите все существующие группы совместного размещения.

threshold: (необязательно) число с плавающей точкой в диапазоне от 0.0 до 1.0, указывающее на максимальное отклонение использования узла от среднего использования. Например, если указать значение 0.1, то подсистема перераспределения сегментов попытается сбалансировать все узлы так, чтобы они содержали одинаковое количество сегментов ± 10%. В частности, подсистема балансировки сегментов попытается свести использование всех рабочих узлов к диапазону (1 – порог) * average_utilization ... (1 –

порог) * average_utilization.

max_shard_moves: (необязательно) максимальное количество сегментов для перемещения.

excluded_shard_list: (необязательно) идентификаторы сегментов, которые не следует перемещать во время операции перераспределения.

auto: требуется идентификатор реплики, если логическая репликация возможна, в противном случае используется традиционный подход (например, PostgreSQL 9.6 для восстановления сегмента). Это значение по умолчанию.

force_logical: использовать логическую репликацию, даже если в таблице нет идентификатора реплики. Во время репликации все параллельные инструкции обновления и удаления в таблице будут завершаться ошибкой.

block_writes: использовать команду COPY (блокирующие операции записи) для таблиц, в которых отсутствует первичный ключ или идентификатор реплики.

drain_only: если значение равно true, перемещаются сегменты из рабочих узлов, для shouldhaveshards в которых задано значение false, в узел pg_dist_node; перемещение других сегментов не выполняется.

rebalance_strategy: (необязательно) имя стратегии в pg_dist_rebalance_strategy. Если этот аргумент опущен, функция выбирает стратегию по умолчанию, как указано в таблице.

Возвращаемое значение

Н/П

Пример

В примере будет предпринята попытка перераспределения сегментов таблицы 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. Значения аргументов см. в документации по этой функции.

Возвращаемое значение

Кортежи, содержащие следующие столбцы:

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_nod_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: функция возвращает уникальный идентификатор, назначенный только что созданному сегменту.

Примеры

Создание нового сегмента для хранения позиций (lineitem) для клиента 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Следующие шаги

Многие из функций, описанных в этой статье, изменяют системные таблицы метаданных.
Параметры сервера настраивают поведение некоторых функций.

Share via

Функции Azure Cosmos DB для PostgreSQL

Таблицы и сегменты 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

Аргументы

Возвращаемое значение