Funciones de Azure Cosmos DB for PostgreSQL

Artículo
08/15/2024

SE APLICA A: Azure Cosmos DB for PostgreSQL (con tecnología de la extensión de base de datos de Citus en PostgreSQL)

Esta sección contiene información de referencia para las funciones definidas por el usuario proporcionadas por Azure Cosmos DB for PostgreSQL. Estas funciones ayudan a proporcionar una funcionalidad distribuida para Azure Cosmos DB for PostgreSQL.

Nota:

Los clústeres que ejecutan versiones anteriores del motor de Citus pueden no ofrecer todas las funciones que se enumeran en esta página.

DDL de tabla y de partición

citus_schema_distribute

Convierte los esquemas normales existentes en esquemas distribuidos. Los esquemas distribuidos se asocian automáticamente con grupos de coubicación individuales. Las tablas creadas en esos esquemas se convierten en tablas distribuidas colocadas sin una clave de partición. El proceso de distribución del esquema lo asigna y mueve automáticamente a un nodo existente del clúster.

Argumentos

schemaname: Nombre del esquema que debe distribuirse.

Valor devuelto

N/D

Ejemplo

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

Para obtener más ejemplos, consulte cómo diseñar para microservicios.

citus_schema_undistribute

Convierte un esquema distribuido existente en un esquema normal. El proceso da como resultado las tablas y los datos que se mueven del nodo actual al nodo de coordinación del clúster.

Argumentos

schemaname: Nombre del esquema que debe distribuirse.

Valor devuelto

N/D

Ejemplo

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

Para obtener más ejemplos, consulte cómo diseñar para microservicios.

create_distributed_table

La función create_distributed_table () se usa para definir una tabla distribuida y crear sus fragmentos si es una tabla distribuida por hash. Esta función adopta un nombre de tabla, la columna de distribución y un método de distribución opcional e inserta los metadatos adecuados para marcar la tabla como distribuida. De forma predeterminada, la función realiza una distribución por"hash" si no se especifica ningún método de distribución. Si la tabla está distribuida por hash, la función también crea particiones de trabajo basadas en los valores de configuración de factor de replicación de particiones y recuento de particiones. Si la tabla contiene filas, se distribuyen automáticamente a los nodos de trabajo.

Esta función reemplaza el uso de master_create_distributed_table () seguido de master_create_worker_shards ().

Argumentos

table_name: Nombre de la tabla que se debe distribuir.

distribution_column: La columna en la que se va a distribuir la tabla.

distribution_type: (Opcional) El método según el cual se distribuirá la tabla. Los valores permitidos son append o hash, con un valor predeterminado de "hash".

colocate_with: (Opcional) Incluir la tabla actual en el grupo de coubicación de otra tabla. De forma predeterminada, las tablas se coubican cuando se distribuyen según columnas del mismo tipo, tienen el mismo recuento de particiones y tienen el mismo factor de replicación. Los valores posibles para colocate_with son default y none para iniciar un nuevo grupo de coubicación, o bien el nombre de otra tabla que se coubicará con esa tabla. (Vea Coubicación en tabla).

Tenga en cuenta que el valor predeterminado de colocate_with realiza la coubicación implícita. La coubicación puede resultar ideal cuando las tablas están relacionadas o si se van a combinar. Sin embargo, cuando dos tablas no están relacionadas, pero se usa el mismo tipo de datos para sus columnas de distribución, coubicarlas accidentalmente puede reducir el rendimiento durante el reequilibrio de particiones. Las particiones de tabla se moverán juntas innecesariamente "en cascada".

Si una nueva tabla distribuida no está relacionada con otras tablas, es mejor especificar colocate_with => 'none'.

shard_count: (opcional) el número de particiones que se van a crear para la nueva tabla distribuida. Al especificar shard_count, no se puede especificar un valor de colocate_with distinto de none. Para cambiar el recuento de particiones de un grupo de coubicación o tabla existente, use la función alter_distributed_table.

Los valores posibles de shard_count están comprendidos entre 1 y 64000. Para obtener instrucciones sobre cómo elegir el valor óptimo, consulte Número de particiones.

Valor devuelto

N/D

Ejemplo

Este ejemplo informa a la base de datos que la tabla github_events debe distribuirse mediante hash en la columna 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

Esta función tiene la misma interfaz y propósito que create_distributed_function, pero no bloquea las escrituras durante la distribución de tablas.

Sin embargo, create_distributed_table_concurrently tiene algunas limitaciones:

No se puede usar la función en un bloque de transacciones, lo que significa que solo se puede distribuir una tabla a la vez. (Sin embargo, puede usar la función en tablas con particiones de tiempo).
No se puede usar create_distributed_table_concurrently cuando una clave externa hace referencia a la tabla o hace referencia a otra tabla local. Sin embargo, las claves externas para hacer referencia a las tablas funcionan y puede crear claves externas para otras tablas distribuidas una vez completada la distribución de tablas.
Si no tiene una identidad de clave principal o de réplica en la tabla, se producirá un error de los comandos de actualización y eliminación durante la distribución de la tabla debido a las limitaciones en la replicación lógica.

truncate_local_data_after_distributing_table

Trunca todas las filas locales después de distribuir una tabla y evita que se produzca un problema en las restricciones debido a registros locales obsoletos. El truncamiento se desplaza en cascada hasta las tablas que tienen una clave externa a la tabla designada. Si las tablas de referencia no se distribuyen por sí mismas, se prohíbe el truncamiento hasta que lo estén para proteger la integridad referencial:

ERROR:  cannot truncate a table referenced in a foreign key constraint by a local table

Truncar los datos de la tabla de nodos de coordinación local es seguro para las tablas distribuidas porque sus filas, si las hay, se copian en los nodos de trabajo durante la distribución.

Argumentos

table_name: nombre de la tabla distribuida cuyo homólogo local en el nodo de coordinación se debe truncar.

Valor devuelto

N/D

Ejemplo

-- requires that argument is a distributed table
SELECT truncate_local_data_after_distributing_table('public.github_events');

create_reference_table

La función create_reference_table () se usa para definir una pequeña tabla de referencia o dimensión. Esta función adopta un nombre de tabla y crea una tabla distribuida con una sola partición, replicada en cada nodo de trabajo.

Argumentos

table_name: Nombre de la tabla pequeña de dimensión o de referencia que se debe distribuir.

Valor devuelto

N/D

Ejemplo

En este ejemplo se informa a la base de datos de que la tabla nation debe definirse como una tabla de referencia.

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Agrega una tabla de Postgres local a los metadatos de Citus. Un caso de uso importante para esta función es hacer que las tablas locales del coordinador sean accesibles desde cualquier nodo del clúster. Los datos asociados a la tabla local permanecen en el coordinador: solo su esquema y los metadatos se envían a los trabajos.

Agregar tablas locales a los metadatos conlleva un ligero costo. Al agregar la tabla, Citus debe realizar un seguimiento en la tabla de particiones. Las tablas locales que se agregan a los metadatos heredan las mismas limitaciones que las tablas de referencia.

Al anular la distribución de la tabla, Citus quita las tablas locales resultantes de los metadatos, lo que elimina estas limitaciones en esas tablas.

Argumentos

table_name: Nombre de la tabla en el coordinador que se va a agregar a los metadatos de Citus.

cascade_via_foreign_keys: (Opcional) Cuando este argumento se establece en “true,” citus_add_local_table_to_metadata agrega otras tablas que se encuentran en una relación de clave externa con una tabla determinada en metadatos automáticamente. Tenga cuidado con este parámetro, ya que puede afectar a muchas tablas.

Valor devuelto

N/D

Ejemplo

En este ejemplo se informa a la base de datos de que la tabla de naciones debe definirse como una tabla local de coordinación, accesible desde cualquier nodo:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

La función alter_distributed_table() se puede usar para cambiar la columna de distribución, el recuento de particiones o las propiedades de coubicación de una tabla distribuida.

Argumentos

table_name: Nombre de la tabla que se modificará.

distribution_column: (opcional) Nombre de la nueva columna de distribución.

shard_count: (opcional) El nuevo recuento de particiones.

colocate_with: (opcional) Tabla con la que se coubicará la tabla distribuida actual. Los valores posibles son default, none para iniciar un nuevo grupo de coubicación, o bien el nombre de otra tabla con la que se coubicará. (Vea Coubicación en tabla).

cascade_to_colocated: (opcional) Cuando este argumento se establece en "true", los cambios de shard_count y colocate_with también se aplicarán a todas las tablas que se coubicaron previamente con la tabla y la coubicación se conservará. Si es "false", se romperá la coubicación actual de esta tabla.

Valor devuelto

N/D

Ejemplo

-- 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

La función update_distributed_table_colocation() se usa para actualizar la coubicación de una tabla distribuida. Esta función también se puede usar para interrumpir la coubicación de una tabla distribuida. Azure Cosmos DB for PostgreSQL coubicará implícitamente dos tablas si la columna de distribución es del mismo tipo, lo que puede ser útil si las tablas están relacionadas y realizarán algunas combinaciones. Si las tablas A y B están coubicadas y la tabla A se reequilibra, también se reequilibrará la tabla B. Si la tabla B no tiene una identidad de réplica, se producirá un error en el reequilibrio. Por lo tanto, esta función puede ser útil para romper la coubicación implícita en ese caso.

Esta función no mueve ningún dato físicamente.

Argumentos

table_name: Nombre de la coubicación de tabla de la que se actualizará.

colocate_with: Tabla con la que se debe coubicar la tabla.

Si desea romper la coubicación de una tabla, debe especificar colocate_with => 'none'.

Valor devuelto

N/D

Ejemplo

En este ejemplo se muestra que la coubicación de la tabla A se actualiza como coubicación de la tabla B.

SELECT update_distributed_table_colocation('A', colocate_with => 'B');

Suponga que la tabla A y la tabla B están coubicadas (posiblemente implícitamente), si desea interrumpir la colocación:

SELECT update_distributed_table_colocation('A', colocate_with => 'none');

Ahora, suponga que la tabla A, la tabla B, la tabla C y la tabla D están coubicadas y desea coubicar las tablas A y B juntas, y las tablas C y D juntas:

SELECT update_distributed_table_colocation('C', colocate_with => 'none');
SELECT update_distributed_table_colocation('D', colocate_with => 'C');

Si tiene una tabla distribuida por hash denominada none y desea actualizar su coubicación, puede hacer lo siguiente:

SELECT update_distributed_table_colocation('"none"', colocate_with => 'some_other_hash_distributed_table');

undistribute_table

La función undistribute_table() deshace la acción de create_distributed_table o create_reference_table. Si elimina la distribución, se mueven todos los datos de las particiones a una tabla local en el nodo de coordinación (suponiendo que los datos quepan) y, a continuación, se eliminan las particiones.

Azure Cosmos DB for PostgreSQL no eliminará la distribución de las tablas a las que se hace referencia mediante claves externas, a menos que el argumento cascade_via_foreign_keys esté establecido en true. Si este argumento es false (o se omite), debe anular manualmente las restricciones de clave externa que ofenden antes de eliminar la distribución.

Argumentos

table_name: Nombre de la tabla distribuida o de referencia cuya distribución se elimina.

cascade_via_foreign_keys: (opcional) Cuando este argumento se establece en "true", undistribute_table también elimina la distribución de todas las tablas relacionadas con table_name a través de claves externas. Tenga cuidado con este parámetro, ya que puede afectar a muchas tablas.

Valor devuelto

N/D

Ejemplo

En este ejemplo se distribuye una tabla github_events y, a continuación, se elimina su distribución.

-- 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

Propaga una función del nodo de coordinación a los nodos de trabajo, y la marca para la ejecución distribuida. Cuando se llama a una función distribuida en el nodo de coordinación, Azure Cosmos DB for PostgreSQL usa el valor del "argumento de distribución" para seleccionar un nodo de trabajo para ejecutar la función. La ejecución de la función en los nodos de trabajo aumenta el paralelismo y puede aproximar más el código a los datos en las particiones para reducir la latencia.

La ruta de búsqueda de Postgres no se propaga del nodo de coordinación a los nodos de trabajo durante la ejecución de la función distribuida, por lo que el código de la función distribuida debe utilizar los nombres completos de los objetos de base de datos. Además, los avisos emitidos por las funciones no se mostrarán al usuario.

Argumentos

function_name: Nombre de la función que se va a distribuir. El nombre debe incluir los tipos de parámetros de la función entre paréntesis, ya que varias funciones pueden tener el mismo nombre en PostgreSQL. Por ejemplo, 'foo(int)' es diferente de 'foo(int, text)'.

distribution_arg_name: (Opcional) Nombre del argumento según el cual realizar la distribución. Para mayor comodidad, o si los argumentos de la función no tienen nombres, se permite un marcador de posición posicional, como '$1'. Si no se especifica este parámetro, la función con el nombre function_name simplemente se crea en los nodos de trabajo. Si se agregan nodos de trabajo en el futuro, la función también se creará automáticamente.

colocate_with: (Opcional) Cuando la función distribuida lea o escriba en una tabla distribuida, o, a nivel más general, en el grupo de coubicación, asegúrese de asignar un nombre a la tabla mediante el parámetro colocate_with. Después, cada invocación de la función se ejecutará en el nodo de trabajo que contiene las particiones pertinentes.

Valor devuelto

N/D

Ejemplo

-- 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

La función alter_columnar_table_set() cambia la configuración de una tabla en columnas. Si se llama a esta función en una tabla que no es de columnas, se produce un error. Todos los argumentos, excepto el nombre de la tabla, son opcionales.

Para ver las opciones actuales de todas las tablas en columnas, consulte esta tabla:

SELECT * FROM columnar.options;

Los valores predeterminados de la configuración de columnas para las tablas recién creadas se pueden invalidar con estos GUC:

columnar.compression
columnar.compression_level
columnar.stripe_row_count
columnar.chunk_row_count

Argumentos

table_name: nombre de la tabla en columnas.

chunk_row_count: (opcional) número máximo de filas por fragmento para los datos recién insertados. Los fragmentos de datos existentes no se cambiarán y podrían tener más filas que este valor máximo. El valor predeterminado es 10000.

stripe_row_count: (opcional) número máximo de filas por franja para los datos recién insertados. Las franjas de datos existentes no se cambiarán y podrían tener más filas que este valor máximo. El valor predeterminado es 150 000.

compression: (opcional) [none|pglz|zstd|lz4|lz4hc] tipo de compresión para los datos recién insertados. Los datos existentes no se volverán a comprimir ni descomprimir. El valor predeterminado y sugerido es zstd (si la compatibilidad se ha compilado).

compression_level: (opcional) la configuración válida es de 1 a 19. Si el método de compresión no admite el nivel elegido, se seleccionará en su lugar el nivel más cercano.

Valor devuelto

N/D

Ejemplo

SELECT alter_columnar_table_set(
  'my_columnar_table',
  compression => 'none',
  stripe_row_count => 10000);

alter_table_set_access_method

La función alter_table_set_access_method() cambia el método de acceso de una tabla (por ejemplo, de montón o de columnas).

Argumentos

table_name: Nombre de la tabla cuyo método de acceso cambiará.

access_method: Nombre del nuevo método de acceso.

Valor devuelto

N/D

Ejemplo

SELECT alter_table_set_access_method('github_events', 'columnar');

create_time_partitions

La función create_time_partitions() crea particiones de un intervalo determinado para cubrir un rango de tiempo determinado.

Argumentos

table_name: tabla (regclass) para la que se crean nuevas particiones. La tabla debe tener particiones en una columna, de tipo date, timestamp o timestamptz.

partition_interval: intervalo de tiempo, como '2 hours' o '1 month', que se usará al establecer intervalos en nuevas particiones.

end_at: (timestamptz) crea particiones hasta este momento. La última partición contendrá el punto end_at y no se crearán particiones posteriores.

start_from: (timestamptz, opcional) elija la primera partición para que contenga el punto start_from. El valor predeterminado es now().

Valor devuelto

True si necesita crear nuevas particiones, false si ya existían.

Ejemplo

-- 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

La función drop_old_time_partitions() quita todas las particiones cuyos intervalos están antes de una marca de tiempo determinada. Además de usar esta función, puede considerar la posibilidad de usar alter_old_partitions_set_access_method para comprimir las particiones antiguas con almacenamiento en columnas.

Argumentos

table_name: tabla (regclass) para la que se quitan particiones. La tabla debe tener particiones en una columna, de tipo date, timestamp o timestamptz.

older_than: (timestamptz) anula particiones cuyo rango superior es menor o igual que older_than.

Valor devuelto

N/D

Ejemplo

-- drop partitions that are over a year old

CALL drop_old_time_partitions('foo', now() - interval '12 months');

alter_old_partitions_set_access_method

En un caso de uso de series temporales, las tablas suelen particionarse por tiempo y las particiones antiguas se comprimen en almacenamiento en columnas de solo lectura.

Argumentos

paren_table_name: tabla (regclass) para la que se cambian particiones. La tabla debe tener particiones en una columna, de tipo date, timestamp o timestamptz.

older_than: (timestamptz) cambia particiones cuyo rango superior es menor o igual que older_than.

new_access_method: (nombre) "heap" para el almacenamiento basado en filas o "columnar" para el almacenamiento en columnas.

Valor devuelto

N/D

Ejemplo

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

Información de configuración y metadatos

get_shard_id_for_distribution_column

Azure Cosmos DB for PostgreSQL asigna cada fila de una tabla distribuida a una partición según el valor de la columna de distribución de la fila y el método de distribución de la tabla. En la mayoría de los casos, la asignación precisa es un detalle de bajo nivel que el administrador de la base de datos puede omitir. Sin embargo, puede ser útil determinar la partición de una fila, ya sea para las tareas manuales de mantenimiento de bases de datos o simplemente por curiosidad. La función get_shard_id_for_distribution_column proporciona esta información para las tablas distribuidas por hash e intervalo, así como para las tablas de referencia. No funciona para la distribución mediante append.

Argumentos

table_name: La tabla distribuida.

distribution_value: El valor de la columna de distribución.

Valor devuelto

El identificador de la partición de Azure Cosmos DB for PostgreSQL se asocia con el valor de la columna de distribución para la tabla especificada.

Ejemplo

SELECT get_shard_id_for_distribution_column('my_table', 4);

 get_shard_id_for_distribution_column
--------------------------------------
                               540007
(1 row)

column_to_column_name

Convierte la columna partkey de pg_dist_partition en un nombre de columna de texto. La conversión es útil para determinar la columna de distribución de una tabla distribuida.

Para obtener una explicación más detallada, vea Elección de una columna de distribución.

Argumentos

table_name: La tabla distribuida.

column_var_text: El valor de partkey en la tabla pg_dist_partition.

Valor devuelto

Nombre de la columna de distribución de table_name.

Ejemplo

-- 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;

Salida:

┌───────────────┐
│ dist_col_name │
├───────────────┤
│ company_id    │
└───────────────┘

citus_relation_size

Obtiene el espacio en disco que usan todas las particiones de la tabla distribuida especificada. El espacio en disco incluye el tamaño de la "bifurcación principal", pero excluye el mapa de visibilidad y el mapa de espacio disponible para las particiones.

Argumentos

logicalrelid: el nombre de una tabla distribuida.

Valor devuelto

Tamaño en bytes como un bigint.

Ejemplo

SELECT pg_size_pretty(citus_relation_size('github_events'));

pg_size_pretty
--------------
23 MB

citus_table_size

Obtiene el espacio en disco que usan todas las particiones de la tabla distribuida especificada, excluidos los índices (incluidos el AVISO, el mapa de espacio libre y el mapa de visibilidad).

Argumentos

logicalrelid: el nombre de una tabla distribuida.

Valor devuelto

Tamaño en bytes como un bigint.

Ejemplo

SELECT pg_size_pretty(citus_table_size('github_events'));

pg_size_pretty
--------------
37 MB

citus_total_relation_size

Obtiene el espacio total en disco utilizado por todas las particiones de la tabla distribuida especificada, incluidos todos los índices y los datos de los AVISOS.

Argumentos

logicalrelid: el nombre de una tabla distribuida.

Valor devuelto

Tamaño en bytes como un bigint.

Ejemplo

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

pg_size_pretty
--------------
73 MB

citus_stat_statements_reset

Quita todas las filas de citus_stat_statements. Esta función es independiente de pg_stat_statements_reset(). Para restablecer todas las estadísticas, llame a ambas funciones.

Argumentos

N/D

Valor devuelto

None

citus_get_active_worker_nodes

La función citus_get_active_worker_nodes() devuelve una lista de nombres de host y números de puerto de trabajo activos.

Argumentos

N/D

Valor devuelto

Lista de tuplas donde cada tupla contiene la siguiente información:

node_name: Nombre DNS del nodo de trabajo

node_port: Puerto del nodo de trabajo de origen en el que escucha el servidor de bases de datos

Ejemplo

SELECT * from citus_get_active_worker_nodes();
 node_name | node_port
-----------+-----------
 localhost |      9700
 localhost |      9702
 localhost |      9701

(3 rows)

Administración y reparación de clústeres

master_copy_shard_placement

Si no se puede actualizar una ubicación de partición durante un comando de modificación o una operación DDL, se marca como inactiva. A continuación, se puede llamar a la función master_copy_shard_placement para reparar una ubicación de partición inactiva con datos en una ubicación correcta.

Para reparar una partición, la función quita primero la ubicación de la partición incorrecta y la vuelve a crear con el esquema en el nodo de coordinación. Una vez creada la ubicación de la partición, la función copia los datos de la ubicación correcta y actualiza los metadatos para marcar la nueva ubicación de la partición como correcta. Esta función garantiza la protección de la partición de cualquier modificación simultánea durante la reparación.

Argumentos

shard_id: identificador de la partición que se va a reparar.

source_node_name: nombre DNS del nodo en el que está presente la ubicación de la partición correcta (nodo de "origen").

source_node_port: El puerto del nodo de trabajo de origen en el que escucha el servidor de bases de datos.

target_node_name: Nombre DNS del nodo en el que está presente la ubicación de la partición no válida (nodo de "destino").

target_node_port: El puerto del nodo de trabajo de destino en el que escucha el servidor de bases de datos.

Valor devuelto

N/D

Ejemplo

En el ejemplo siguiente se reparará una ubicación de partición inactiva de la partición 12345, que se encuentra en el servidor de bases de datos que se ejecuta en "bad_host" en el puerto 5432. Para repararla, utilizará los datos de una ubicación de partición correcta presente en el servidor que se ejecuta en "good_host" en el puerto 5432.

SELECT master_copy_shard_placement(12345, 'good_host', 5432, 'bad_host', 5432);

master_move_shard_placement

Esta función mueve una partición determinada y las particiones colocadas con ella de un nodo a otro. Normalmente, se usa indirectamente durante el reequilibrio de particiones en lugar de que la llame directamente un administrador de bases de datos.

Hay dos maneras de trasladar los datos: bloqueo o desbloqueo. El enfoque de bloqueo implica que, durante el traslado, se pausan todas las modificaciones realizadas en la partición. La segunda opción, que evita que se bloqueen las escrituras en las particiones, se basa en la replicación lógica de Postgres 10.

Después de una operación de transición correcta, las particiones del nodo de origen se eliminan. Si se produce un error en la transición en cualquier momento, esta función produce un error y deja sin modificar los nodos de origen y destino.

Argumentos

shard_id: identificador de la partición que se va a mover.

source_node_name: nombre DNS del nodo en el que está presente la ubicación de la partición correcta (nodo de "origen").

source_node_port: El puerto del nodo de trabajo de origen en el que escucha el servidor de bases de datos.

target_node_name: Nombre DNS del nodo en el que está presente la ubicación de la partición no válida (nodo de "destino").

target_node_port: El puerto del nodo de trabajo de destino en el que escucha el servidor de bases de datos.

shard_transfer_mode: (Opcional) Especifica el método de replicación, si va a usar la replicación lógica de PostgreSQL o un comando COPY entre nodos de trabajo. Los valores posibles son:

auto: requerir la identidad de réplica si es posible la replicación lógica; de lo contrario, use el comportamiento heredado (por ejemplo, para la reparación de particiones, PostgreSQL 9.6). Este es el valor predeterminado.

force_logical: utilizar la replicación lógica incluso si la tabla no tiene una identidad de réplica. Se producirá un error en las instrucciones update/delete simultáneas de la tabla durante la replicación.

block_writes: usar COPY (escrituras de bloqueo) para las tablas que carecen de identidad de réplica o clave principal.

Valor devuelto

N/D

Ejemplo

SELECT master_move_shard_placement(12345, 'from_host', 5432, 'to_host', 5432);

rebalance_table_shards

La función rebalance_table_shards() mueve las particiones de la tabla especificada para que se distribuyan uniformemente entre los nodos de trabajo. La función calcula primero la lista de movimientos que debe realizar para asegurarse de que el clúster está equilibrado en el umbral especificado. A continuación, mueve las ubicaciones de las particiones de una en una desde el nodo de origen al nodo de destino y actualiza los metadatos de las particiones correspondientes para reflejar el movimiento.

A cada partición se le asigna un costo al determinar si las particiones se "distribuyen de manera uniforme". De forma predeterminada, cada partición tiene el mismo costo (un valor de 1), por lo que la distribución para igualar el costo entre los nodos de trabajo es lo mismo que igualar el número de particiones en cada una. La estrategia de costo constante se denomina "by_shard_count", y es la estrategia de reequilibrio predeterminada.

La estrategia "by_shard_count" es adecuada en estas circunstancias:

Las particiones tienen aproximadamente el mismo tamaño.
Las particiones obtienen aproximadamente la misma cantidad de tráfico.
Todos los nodos de trabajo tienen el mismo tamaño o tipo.
Las particiones no se han anclado a determinados roles de trabajo.

Si no se mantiene alguna de estas suposiciones, el reequilibrio “by_shard_count” puede resultar en un plan incorrecto.

La estrategia de reequilibrio predeterminada es “by_disk_size”. Siempre puede personalizar la estrategia mediante el parámetro rebalance_strategy.

Es aconsejable llamar a get_rebalance_table_shards_plan antes de ejecutar rebalance_table_shards, para ver y comprobar las acciones que se van a realizar.

Argumentos

table_name: (Opcional) nombre de la tabla cuyas particiones se deben reequilibrar. Si es NULL, vuelva a equilibrar todos los grupos de coubicación existentes.

threshold: (opcional) un número de punto flotante entre 0,0 y 1,0 que indica la relación de diferencia máxima del uso del nodo con respecto al promedio de uso. Por ejemplo, si se especifica 0,1, el reequilibrador de particiones intentará equilibrar todos los nodos para que contengan el mismo número de particiones ± 10 %. En concreto, el reequilibrador de particiones intentará converger la utilización de todos los nodos de trabajo en el intervalo (1 - umbral) average_utilization ... (1

umbral) * average_utilization range.

max_shard_moves: (Opcional) Número máximo de particiones que se van a mover.

excluded_shard_list: Opcional) Identificadores de las particiones que no deben moverse durante la operación de reequilibrio.

shard_transfer_mode: (Opcional) Especifica el método de replicación, si va a usar la replicación lógica de PostgreSQL o un comando COPY entre nodos de trabajo. Los valores posibles son:

auto: requerir la identidad de réplica si es posible la replicación lógica; de lo contrario, use el comportamiento heredado (por ejemplo, para la reparación de particiones, PostgreSQL 9.6). Este es el valor predeterminado.

force_logical: utilizar la replicación lógica incluso si la tabla no tiene una identidad de réplica. Se producirá un error en las instrucciones update/delete simultáneas de la tabla durante la replicación.

block_writes: usar COPY (escrituras de bloqueo) para las tablas que carecen de identidad de réplica o clave principal.

drain_only: (Opcional) Cuando es true, mueve las particiones fuera de los nodos de trabajo que tienen shouldhaveshards establecido en false en pg_dist_node; no se mueve ninguna otra partición.

rebalance_strategy: (Opcional) Nombre de una estrategia en pg_dist_rebalance_strategy. Si se omite este argumento, la función elige la estrategia predeterminada, como se indica en la tabla.

Valor devuelto

N/D

Ejemplo

En el ejemplo siguiente, se intentarán reequilibrar las particiones de la tabla github_events dentro del umbral predeterminado.

SELECT rebalance_table_shards('github_events');

En este ejemplo de uso, se intentará reequilibrar la tabla github_events sin mover las particiones con los identificadores 1 y 2.

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

get_rebalance_table_shards_plan

Se genera la salida de los movimientos de particiones planeados de rebalance_table_shards sin ejecutarlos. Si bien es poco probable, get_rebalance_table_shards_plan puede generar un plan ligeramente diferente al que hará una llamada rebalance_table_shards con los mismos argumentos. No se ejecutan al mismo tiempo, por lo que los datos sobre el clúster, por ejemplo, el espacio en disco, pueden diferir entre las llamadas.

Argumentos

Los mismos argumentos que rebalance_table_shards: relación, umbral, max_shard_moves, excluded_shard_list y drain_only. Consulte la documentación de esa función para ver el significado de los argumentos.

Valor devuelto

Tuplas que contienen estas columnas:

table_name: Las tablas cuyas particiones se moverán
shardid: partición en cuestión.
shard_size: Tamaño en bytes
sourcename: nombre de host del nodo de origen
sourceport: puerto del nodo de origen
targetname: nombre de host del nodo de destino
targetport: puerto del nodo de destino

get_rebalance_progress

Una vez que comienza el reequilibrio de una partición, la función get_rebalance_progress() muestra el progreso de cada una de las particiones involucradas. Supervisa los movimientos planeados y ejecutados por rebalance_table_shards().

Argumentos

N/D

Valor devuelto

Tuplas que contienen estas columnas:

sessionid: PID de Postgres del monitor de reequilibrio
table_name: La tabla cuyas particiones se van a mover
shardid: partición en cuestión.
shard_size: Tamaño en bytes
sourcename: nombre de host del nodo de origen
sourceport: puerto del nodo de origen
targetname: nombre de host del nodo de destino
targetport: puerto del nodo de destino
progress: 0 = en espera de moverse; 1 = en movimiento; 2 = completado

Ejemplo

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

Anexar una fila a pg_dist_rebalance_strategy.

Argumentos

Para obtener más información sobre estos argumentos, vea los valores de columna correspondientes en pg_dist_rebalance_strategy.

name: identificador de la estrategia nueva.

shard_cost_function: Identifica la función utilizada para determinar el "costo" de cada partición

node_capacity_function: Identifica la función para medir la capacidad del nodo

shard_allowed_on_node_function: Identifica la función que determina qué particiones se pueden colocar en determinados nodos

default_threshold: Un umbral de número de punto flotante que optimiza la precisión con la que se debe equilibrar el costo acumulado de las particiones entre los nodos

minimum_threshold: (Opcional) Columna de protección que contiene el valor mínimo permitido para el argumento de umbral de rebalance_table_shards(). El valor predeterminado es 0.

Valor devuelto

N/D

citus_set_default_rebalance_strategy

Actualizar la tabla pg_dist_rebalance_strategy, cambiando la estrategia denominada por su argumento para que sea el valor predeterminado elegido al reequilibrar las particiones.

Argumentos

name: El nombre de una estrategia en pg_dist_rebalance_strategy

Valor devuelto

N/D

Ejemplo

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

La función citus_remote_connection_stats () muestra el número de conexiones activas a cada nodo remoto.

Argumentos

N/D

Ejemplo

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

Esta función crea una partición que contiene filas con un valor único específico en la columna de distribución. Es especialmente útil para el caso de uso multiinquilino, donde un inquilino grande puede colocarse por sí solo en su propia partición y, en última instancia, en su propio nodo físico.

Argumentos

table_name: El nombre de la tabla para obtener una nueva partición.

tenant_id: El valor de la columna de distribución que se asignará a la nueva partición.

cascade_option: (Opcional) cuando se establece en "CASCADE", también aísla una partición de todas las tablas en el grupo de coubicación de la tabla actual.

Valor devuelto

shard_id: La función devuelve el identificador único asignado a la partición recién creada.

Ejemplos

Cree una partición para que contenga los elementos lineitems para el inquilino 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Pasos siguientes

Muchas de las funciones de este artículo modifican las tablas de metadatos del sistema.
Los parámetros del servidor personalizan el comportamiento de algunas funciones.

Compartir a través de

Funciones de Azure Cosmos DB for PostgreSQL

DDL de tabla y de partición

citus_schema_distribute

Argumentos

Valor devuelto

Ejemplo

citus_schema_undistribute

Argumentos

Valor devuelto

Ejemplo

create_distributed_table

Argumentos

Valor devuelto

Ejemplo

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argumentos

Valor devuelto

Ejemplo

create_reference_table

Argumentos

Valor devuelto

Ejemplo

citus_add_local_table_to_metadata

Argumentos

Valor devuelto

Ejemplo

alter_distributed_table

Argumentos

Valor devuelto

Ejemplo

update_distributed_table_colocation

Argumentos

Valor devuelto

Ejemplo

undistribute_table

Argumentos

Valor devuelto

Ejemplo

create_distributed_function

Argumentos

Valor devuelto

Ejemplo

alter_columnar_table_set

Argumentos

Valor devuelto

Ejemplo

alter_table_set_access_method

Argumentos

Valor devuelto

Ejemplo

create_time_partitions

Argumentos

Valor devuelto

Ejemplo

drop_old_time_partitions

Argumentos

Valor devuelto

Ejemplo

alter_old_partitions_set_access_method

Argumentos

Valor devuelto

Ejemplo

Información de configuración y metadatos

get_shard_id_for_distribution_column

Argumentos

Valor devuelto

Ejemplo

column_to_column_name

Argumentos

Valor devuelto

Ejemplo

citus_relation_size

Argumentos

Valor devuelto

Ejemplo

citus_table_size

Argumentos

Valor devuelto