Azure Cosmos DB for PostgreSQL-Funktionen

Artikel
11/15/2023

GILT FÜR: Azure Cosmos DB for PostgreSQL (unterstützt von der Citus-Datenbankerweiterung auf PostgreSQL)

Dieser Abschnitt enthält Referenzinformationen zu den benutzerdefinierten Funktionen, die von Azure Cosmos DB for PostgreSQL bereitgestellt werden. Diese Funktionen helfen bei der Bereitstellung verteilter Funktionalität für Azure Cosmos DB for PostgreSQL.

Hinweis

Cluster, auf denen ältere Versionen der Citus-Engine ausgeführt werden, bieten möglicherweise nicht alle auf diese Seite aufgeführten Funktionen.

Tabellen- und Shard-DDL

citus_schema_distribute

Konvertiert vorhandene reguläre Schemas in verteilte Schemas. Verteilte Schemas werden automatisch einzelnen Zusammenstellungsgruppen zugeordnet. Die in diesen Schemas erstellten Tabellen werden in zusammengestellte verteilte Tabellen ohne Shardschlüssel konvertiert. Bei der Schemaverteilung wird das Schema automatisch zugewiesen und in einen vorhandenen Knoten im Cluster verschoben.

Argumente

schemaname: Name des Schemas, das verteilt werden muss

Rückgabewert

Nicht zutreffend

Beispiel

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

Weitere Beispiele finden Sie in der Anleitung zum Entwurf für Microservices.

citus_schema_undistribute

Konvertiert ein vorhandenes verteiltes Schema wieder in ein normales Schema. Der Prozess führt dazu, dass die Tabellen und Daten vom aktuellen Knoten zurück in den Koordinatorknoten im Cluster verschoben werden.

Argumente

schemaname: Name des Schemas, das verteilt werden muss

Rückgabewert

Nicht zutreffend

Beispiel

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

Weitere Beispiele finden Sie in der Anleitung zum Entwurf für Microservices.

create_distributed_table

Die Funktion „create_distributed_table()“ wird verwendet, um eine verteilte Tabelle zu definieren und deren Shards zu erstellen, wenn es sich um eine Tabelle mit Hashverteilung handelt. Diese Funktion nimmt einen Tabellennamen, die Verteilungsspalte und eine optionale Verteilungsmethode an und fügt geeignete Metadaten ein, um die Tabelle als verteilt zu kennzeichnen. Die Funktion ist standardmäßig auf die Verteilung „hash“ festgelegt, wenn keine Verteilungsmethode angegeben wird. Wenn die Tabelle Hashverteilung aufweist, erstellt die Funktion auch Workershards auf der Grundlage der Shardanzahl und der Konfigurationswerte für den Shardreplikationsfaktor. Wenn die Tabelle Zeilen enthält, werden diese automatisch an Workerknoten verteilt.

Diese Funktion ersetzt „master_create_distributed_table()“, gefolgt von „master_create_worker_shards()“.

Argumente

table_name: Name der Tabelle, die verteilt werden muss

distribution_column: Spalte, für die die Tabelle verteilt werden soll

distribution_type: (optional) Methode, nach der die Tabelle verteilt werden soll Zulässige Werte sind „append“ oder „hash“ mit dem Standardwert „hash“.

colocate_with: (optional) schließt die aktuelle Tabelle in die Colocationsgruppe einer anderen Tabelle ein. Standardmäßig werden Tabellen verbunden, wenn sie durch Spalten desselben Typs verteilt werden und die gleiche Shardanzahl und denselben Replikationsfaktor aufweisen. Mögliche Werte für colocate_with sind default, none, um eine neue Colocationsgruppe zu starten, oder der Name einer anderen Tabelle, für die Colocation mit dieser Tabelle verwendet werden soll. (Weitere Informationen finden Sie unter Tabellencolocation.)

Beachten Sie, dass der Standardwert colocate_with eine implizite Colocation vornimmt. Colocation kann eine hervorragende Lösung sein, wenn Tabellen in Beziehung stehen oder verknüpft werden sollen. Wenn jedoch zwei Tabellen nicht miteinander in Beziehung stehen, aber zufällig den gleichen Datentyp für ihre Verteilungsspalten verwenden, kann die Leistung bei Shardausgleich durch eine versehentliche Colocation beeinträchtigt werden. Die Tabellenshards werden unnötig in einer „Kaskade“ miteinander verschoben.

Wenn eine neue verteilte Tabelle nicht in Beziehung mit anderen Tabellen steht, ist es am besten, colocate_with => 'none' anzugeben.

shard_count: (Optional) die Anzahl der Shards, die für die neue verteilte Tabelle erstellt werden sollen. Wenn Sie shard_count angeben, können Sie nur den Wert von colocate_with oder keinen angeben. Verwenden Sie die Funktion alter_distributed_table, um die Shardanzahl einer vorhandenen Tabelle oder Colocation-Gruppe zu ändern.

Mögliche Werte für shard_count liegen zwischen 1 und 64.000. Eine Anleitung zur Auswahl des optimalen Werts finden Sie unter Anzahl von Shards.

Rückgabewert

Nicht zutreffend

Beispiel

Dieses Beispiel informiert die Datenbank, dass die Tabelle „github_events“ per Hash auf die Spalte „repo_id“ verteilt werden soll.

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

Diese Funktion hat die gleiche Schnittstelle und denselben Zweck wie create_distributed_function, blockiert aber Schreibvorgänge während der Tabellenverteilung nicht.

Für create_distributed_table_concurrently gibt es jedoch einige Einschränkungen:

Sie können die Funktion nicht in einem Transaktionsblock verwenden, was bedeutet, dass Sie nur jeweils eine Tabelle verteilen können. (Sie können die Funktion jedoch für zeitpartitionierte Tabellen verwenden.)
Sie können create_distributed_table_concurrently nicht verwenden, wenn auf die Tabelle durch einen Fremdschlüssel verwiesen wird oder sie auf eine andere lokale Tabelle verweist. Fremdschlüssel zum Verweisen auf Tabellen funktionieren jedoch, und Sie können Fremdschlüssel für andere verteilte Tabellen erstellen, nachdem die Tabellenverteilung abgeschlossen ist.
Wenn Sie nicht über einen Primärschlüssel oder eine Replikatidentität in Ihrer Tabelle verfügen, schlagen Aktualisierungs- und Löschbefehle während der Tabellenverteilung aufgrund von Einschränkungen bei der logischen Replikation fehl.

truncate_local_data_after_distributing_table

Schneidet nach dem Verteilen einer Tabelle alle lokalen Zeilen ab und verhindert, dass bei Einschränkungen aufgrund veralteter lokaler Datensätze ein Fehler auftritt. Die Kürzung wird an Tabellen mit einem Fremdschlüssel für die vorgesehene Tabelle weitergegeben. Wenn die verweisenden Tabellen nicht selbst verteilt werden, ist das Abschneiden bis zu ihrer Verteilung unzulässig, um die referentielle Integrität zu schützen:

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

Das Abschneiden der Tabellendaten des lokalen Koordinatorknotens ist für verteilte Tabellen sicher, da ihre Zeilen (sofern vorhanden) während der Verteilung auf Workerknoten kopiert werden.

Argumente

table_name: Name der verteilten Tabelle, deren lokale Entsprechung im Koordinatorknoten abgeschnitten werden soll

Rückgabewert

Nicht zutreffend

Beispiel

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

create_reference_table

Die Funktion „create_reference_table()“ wird verwendet, um eine kleine Verweis- oder Dimensionstabelle zu definieren. Diese Funktion nimmt einen Tabellennamen an und erstellt eine verteilte Tabelle mit nur einem Shard, der auf jeden Workerknoten repliziert wird.

Argumente

table_name: Name der kleinen Dimensions- oder Verweistabelle, die verteilt werden muss

Rückgabewert

Nicht zutreffend

Beispiel

Dieses Beispiel informiert die Datenbank, dass die Tabelle „nation“ als Verweistabelle definiert werden sollte.

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Fügt eine lokale Postgres-Tabelle zu Citus-Metadaten hinzu. Ein wichtiger Anwendungsfall für diese Funktion besteht darin, lokale Tabellen auf dem Koordinator von jedem Knoten im Cluster aus zugänglich zu machen. Die Daten, die der lokalen Tabelle zugeordnet sind, bleiben auf dem Koordinator – nur das Schema und die Metadaten werden an die Worker gesendet.

Das Hinzufügen lokaler Tabellen zu den Metadaten ist mit geringen Kosten verbunden. Wenn Sie die Tabelle hinzufügen, muss Citus sie in der Partitionstabelle nachverfolgen. Lokale Tabellen, die Metadaten hinzugefügt werden, erben dieselben Einschränkungen wie Verweistabellen.

Wenn Sie die Verteilung der Tabelle aufheben, entfernt Citus die resultierenden lokalen Tabellen aus den Metadaten. Dadurch werden solche Einschränkungen für diese Tabellen beseitigt.

Argumente

table_name: Name der Tabelle auf einem Koordinator, die den Citus-Metadaten hinzugefügt werden soll

cascade_via_foreign_keys: (Optional) Wenn dieses Argument auf „true“ festgelegt ist, fügt citus_add_local_table_to_metadata andere Tabellen, die in einer Fremdschlüsselbeziehung zu der angegebenen Tabelle stehen, automatisch zu den Metadaten hinzu. Verwenden Sie diesen Parameter mit Vorsicht, da er sich potenziell auf zahlreiche Tabellen auswirken kann.

Rückgabewert

Nicht zutreffend

Beispiel

Dieses Beispiel informiert die Datenbank, dass die Tabelle „nation“ als im Koordinator lokale Tabelle definiert werden sollte, auf die von jedem Knoten zugegriffen werden kann:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

Die Funktion „alter_distributed_table()“ kann verwendet werden, um die Verteilungsspalte, die Shardanzahl oder die Zusammenstellungseigenschaften einer verteilten Tabelle zu ändern.

Argumente

table_name: Name der Tabelle, die geändert wird

distribution_column: (Optional) Name der neuen Verteilungsspalte

shard_count: (Optional) Die neue Shardanzahl

colocate_with: (Optional) Die Tabelle, mit der die derzeit verteilte Tabelle zusammengestellt wird. Mögliche Werte sind default, none zum Beginnen einer neuen Zusammenstellungsgruppe oder der Name einer anderen Tabelle, mit der die Zusammenstellung erfolgen soll. (Weitere Informationen finden Sie unter Tabellencolocation.)

cascade_to_colocated: (Optional) Wenn dieses Argument auf „true“ festgelegt wird, werden Änderungen an shard_count und colocate_with auch auf alle Tabellen angewendet, die zuvor mit der Tabelle verbunden waren, und die Zusammenstellung wird beibehalten. Wenn der Wert „false“ lautet, wird die aktuelle Zusammenstellung dieser Tabelle aufgehoben.

Rückgabewert

Nicht zutreffend

Beispiel

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

Die Funktion „update_distributed_table_colocation()“ wird zum Aktualisieren der Zusammenstellung einer verteilten Tabelle verwendet. Diese Funktion kann auch verwendet werden, um die Zusammenstellung einer verteilten Tabelle aufzuheben. Azure Cosmos DB for PostgreSQL stellt implizit zwei Tabellen zusammen, wenn die Verteilungsspalte denselben Typ aufweist. Dies kann nützlich sein, wenn die Tabellen in Beziehung stehen oder Verknüpfungen herstellen. Wenn Tabellen A und B zusammengestellt werden und Tabelle A neu ausgeglichen wird, wird auch Tabelle B neu ausgeglichen. Verfügt Tabelle B nicht über eine Replikatidentität, tritt beim Neuausgleich ein Fehler auf. Daher kann diese Funktion hilfreich sein, um die implizite Zusammenstellung in diesem Fall aufzuheben.

Mit dieser Funktion werden Daten nicht physisch verschoben.

Argumente

table_name: Name der Tabellenzusammenstellung, die aktualisiert wird

colocate_with: Die Tabelle, mit der die Tabelle zusammengestellt werden soll.

Wenn Sie die Zusammenstellung einer Tabelle aufheben möchten, müssen Sie colocate_with => 'none' angeben.

Rückgabewert

Nicht zutreffend

Beispiel

Dieses Beispiel zeigt, dass die Zusammenstellung von Tabelle A als Zusammenstellung von Tabelle B aktualisiert wird.

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

Angenommen, Tabelle A und Tabelle B werden (möglicherweise implizit) zusammengestellt, wenn Sie die Zusammenstellung aufheben möchten:

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

Nehmen wir nun an, dass Tabelle A, Tabelle B, Tabelle C und Tabelle D zusammengestellt sind und Sie Tabelle A und Tabelle B sowie Tabelle C und Tabelle D zusammenstellen möchten:

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

Wenn Sie über eine Tabelle mit Hashverteilung mit dem Namen „none“ verfügen und deren Zusammenstellung aktualisieren möchten, können Sie Folgendes ausführen:

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

undistribute_table

Mit der Funktion „undistribute_table()“ wird die Aktion von „create_distributed_table“ oder „create_reference_table“ rückgängig gemacht. Beim Aufheben der Verteilung werden alle Daten von Shards zurück in eine lokale Tabelle im Koordinatorknoten verschoben (vorausgesetzt, die Daten passen hinein). Anschließend werden die Shards gelöscht.

Azure Cosmos DB for PostgreSQL hebt die Verteilung von Tabellen, die über Fremdschlüssel verfügen oder auf die durch Fremdschlüssel verwiesen wird, nicht auf, es sei denn, das Argument „cascade_via_foreign_keys“ wird auf „true“ festgelegt. Wird dieses Argument auf „false“ festgelegt (oder ausgelassen), müssen Sie die problematischen Einschränkungen des Fremdschlüssels manuell löschen, bevor Sie die Verteilung aufheben.

Argumente

table_name: Name der verteilten Tabelle oder Verweistabelle, deren Verteilung aufgehoben werden soll

cascade_via_foreign_keys: (Optional) Wenn dieses Argument auf „true“ festgelegt wird, wird mit „undistribute_table“ auch die Verteilung aller Tabellen aufgehoben, die über Fremdschlüssel mit „table_name“ in Beziehung stehen. Verwenden Sie diesen Parameter mit Vorsicht, da er sich potenziell auf zahlreiche Tabellen auswirken kann.

Rückgabewert

Nicht zutreffend

Beispiel

In diesem Beispiel wird eine Tabelle vom Typ github_events verteilt und ihre Verteilung anschließend wieder aufgehoben.

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

Gibt eine Funktion vom Koordinatorknoten an Worker weiter und markiert sie für verteilte Ausführung. Wenn eine verteilte Funktion für den Koordinator aufgerufen wird, verwendet Azure Cosmos DB for PostgreSQL den Wert des distribution-Arguments, um einen Workerknoten zum Ausführen der Funktion auszuwählen. Das Ausführen der Funktion für Worker erhöht die Parallelität und kann den Code in Shards näher an Daten bringen, um geringere Latenz zu erzielen.

Der Postgres-Suchpfad wird während der Ausführung verteilter Funktionen nicht vom Koordinator an Worker weitergegeben. Daher sollte der Code der verteilten Funktion die Namen von Datenbankobjekten als vollqualifizierte Namen angeben. Außerdem werden dem Benutzer keine Benachrichtigungen angezeigt, die von den Funktionen ausgegeben werden.

Argumente

function_name: Name der zu verteilenden Funktion. Der Name muss die Parametertypen der Funktion in Klammern enthalten, da mehrere Funktionen in PostgreSQL denselben Namen haben können. Beispielsweise unterscheidet sich 'foo(int)' von 'foo(int, text)'.

distribution_arg_name: (optional) Argumentname, nach dem verteilt werden soll. Zur einfacheren Handhabung (oder wenn die Funktionsargumente keine Namen besitzen) ist ein Positionsplatzhalter zulässig, z. B. '$1'. Wenn dieser Parameter nicht angegeben wird, wird die durch function_name benannte Funktion nur für die Worker erstellt. Wenn Workerknoten zu einem späteren Zeitpunkt hinzugefügt werden, wird die Funktion auf ihnen ebenfalls automatisch erstellt.

colocate_with: (optional) Wenn die verteilte Funktion Lese- oder Schreibvorgänge für eine verteilte Tabelle (oder allgemeiner für eine Colocationgruppe) ausführt, stellen Sie sicher, dass Sie diese Tabelle mithilfe des Parameters colocate_with benennen. Anschließend wird jeder Aufruf der Funktion auf dem Workerknoten ausgeführt, der relevante Shards enthält.

Rückgabewert

Nicht zutreffend

Beispiel

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

Die Funktion „alter_columnar_table_set()“ ändert die Einstellungen bei einer Spaltentabelle. Das Aufrufen dieser Funktion bei einer Nicht-Spaltentabelle führt zu einem Fehler. Alle Argumente außer dem Tabellennamen sind optional.

Informationen zum Anzeigen der aktuellen Optionen für alle Spaltentabellen finden Sie in dieser Tabelle:

SELECT * FROM columnar.options;

Die Standardwerte für Spalteneinstellungen bei neu erstellten Tabellen können mit diesen GUCs überschrieben werden:

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

Argumente

table_name: Der Name der Spaltentabelle.

chunk_row_count: (Optional) Die maximale Anzahl von Zeilen pro Block für neu eingefügte Daten. Vorhandene Datenblöcke werden nicht geändert und enthalten möglicherweise mehr Zeilen als diesen Höchstwert. Der Standardwert ist 10.000.

stripe_row_count: (Optional) Die maximale Anzahl von Zeilen pro Bereichsstreifen für neu eingefügte Daten. Vorhandene Bereichsstreifen von Daten werden nicht geändert und enthalten möglicherweise mehr Zeilen als diesen Höchstwert. Der Standardwert ist 150.000.

compression: (Optional) [none|pglz|zstd|lz4|lz4hc] Der Komprimierungstyp für neu eingefügte Daten. Vorhandene Daten werden nicht erneut komprimiert oder dekomprimiert. Der Standardwert und der vorgeschlagene Wert ist „zstd“ (wenn die Unterstützung kompiliert wurde).

compression_level: (Optional) Gültige Einstellungen liegen zwischen 1 und 19. Wenn die Komprimierungsmethode die ausgewählte Ebene nicht unterstützt, wird stattdessen die nächstgelegene Ebene ausgewählt.

Rückgabewert

Nicht zutreffend

Beispiel

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

alter_table_set_access_method

Mit der Funktion „alter_table_set_access_method()“ wird die Zugriffsmethode einer Tabelle (etwa einer Heap- oder Spaltentabelle) geändert.

Argumente

table_name: Name der Tabelle, deren Zugriffsmethode geändert wird

access_method: Name der neuen Zugriffsmethode

Rückgabewert

Nicht zutreffend

Beispiel

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

create_time_partitions

Die Funktion „create_time_partitions()“ erstellt Partitionen eines bestimmten Intervalls, um einen bestimmten Zeitbereich abzudecken.

Argumente

table_name: (regclass) Tabelle, für die neue Partitionen erstellt werden sollen. Die Tabelle muss nach einer Spalte vom Typ „date“, „timestamp“ oder „timestamptz“ partitioniert werden.

partition_interval: Ein Zeitintervall wie '2 hours' oder '1 month', das zum Festlegen von Bereichen für neue Partitionen verwendet werden soll

end_at: (timestamptz) Mit diesem Argument werden Partitionen bis zu diesem Zeitpunkt erstellt. Die letzte Partition enthält den Punkt „end_at“, und es werden keine späteren Partitionen erstellt.

start_from: (timestamptz, optional) Wählen Sie die erste Partition aus, sodass sie den Punkt „start_from“ enthält. Der Standardwert ist now().

Rückgabewert

„true“, wenn neue Partitionen erstellt werden müssen, „false“, wenn alle bereits vorhanden waren.

Beispiel

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

Mit der Funktion „drop_old_time_partitions()“ werden alle Partitionen entfernt, deren Intervalle vor einem bestimmten Zeitstempel liegen. Zusätzlich zu dieser Funktion können Sie die Verwendung von alter_old_partitions_set_access_method zum Komprimieren der alten Partitionen mit spaltenbasiertem Speicher in Erwägung ziehen.

Argumente

table_name: (regclass) Tabelle, für die Partitionen entfernt werden sollen. Die Tabelle muss nach einer Spalte vom Typ „date“, „timestamp“ oder „timestamptz“ partitioniert werden.

older_than: (timestamptz) Dient zum Löschen von Partitionen, deren oberer Bereich kleiner oder gleich „older_than“ ist

Rückgabewert

Nicht zutreffend

Beispiel

-- drop partitions that are over a year old

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

alter_old_partitions_set_access_method

In einem Anwendungsfall mit Zeitreihen werden Tabellen häufig nach Zeit partitioniert, und alte Partitionen werden in schreibgeschütztem spaltenbasiertem Speicher komprimiert.

Argumente

parent_table_name: (regclass) Tabelle, für die Partitionen geändert werden sollen. Die Tabelle muss nach einer Spalte vom Typ „date“, „timestamp“ oder „timestamptz“ partitioniert werden.

older_than: (timestamptz) Dient zum Ändern von Partitionen, deren oberer Bereich kleiner oder gleich „older_than“ ist

new_access_method: (name) entweder „heap“ für zeilenbasierten Speicher oder „columnar“ für spaltenbasierten Speicher.

Rückgabewert

Nicht zutreffend

Beispiel

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

Metadaten/Konfigurationsinformationen

get_shard_id_for_distribution_column

Azure Cosmos DB for PostgreSQL weist jede Zeile einer verteilten Tabelle einem Shard basierend auf dem Wert der Verteilungsspalte der Zeile und der Verteilungsmethode der Tabelle zu. In den meisten Fällen handelt es sich bei der exakten Zuordnung um Details auf niedriger Ebene, die vom Datenbankadministrator ignoriert werden können. Allerdings kann es hilfreich sein, den Shard einer Zeile zu bestimmen, entweder für manuelle Datenbankverwaltungsaufgaben oder nur aus Neugier. Die Funktion get_shard_id_for_distribution_column stellt diese Informationen für Tabellen mit Hash- und Bereichsverteilung sowie für Verweistabellen bereit. Dies funktioniert nicht für die Anfügeverteilung.

Argumente

table_name: die verteilte Tabelle

distribution_value: Wert der Verteilungsspalte

Rückgabewert

Die Shard-ID, die Azure Cosmos DB for PostgreSQL mit dem Wert der Verteilungsspalte für die angegebene Tabelle verknüpft.

Beispiel

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

Übersetzt die partkey-Spalte von pg_dist_partition in einen Textspaltennamen. Die Übersetzung ist hilfreich, um die Verteilungsspalte einer verteilten Tabelle zu ermitteln.

Eine ausführlichere Erläuterung finden Sie unter Auswählen einer Verteilungsspalte.

Argumente

table_name: die verteilte Tabelle

column_var_text: Wert von partkey in der Tabelle pg_dist_partition

Rückgabewert

Der Name der Verteilungsspalte von table_name.

Beispiel

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

Ausgabe:

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

citus_relation_size

Ruft den von allen Shards der angegebenen verteilten Tabelle verwendeten Speicherplatz auf dem Datenträger ab. Der Speicherplatz auf dem Datenträger umfasst die Größe des „Hauptforks“, schließt jedoch die Sichtbarkeitszuordnung und die Zuordnung des freien Speicherplatzes für die Shards aus.

Argumente

logicalrelid: Der Name einer verteilten Tabelle.

Rückgabewert

Die Größe in Bytes als bigint-Wert.

Beispiel

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

Ruft den Speicherplatz auf dem Datenträger ab, der von allen Shards der angegebenen verteilten Tabelle verwendet wird, ausschließlich der Indizes (jedoch einschließlich TOAST, Zuordnung des freien Speicherplatzes und Sichtbarkeitszuordnung).

Argumente

logicalrelid: Der Name einer verteilten Tabelle.

Rückgabewert

Die Größe in Bytes als bigint-Wert.

Beispiel

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

Ruft den Speicherplatz auf dem Datenträger ab, der von allen Shards der angegebenen verteilten Tabelle verwendet wird, einschließlich aller Indizes und TOAST-Daten.

Argumente

logicalrelid: Der Name einer verteilten Tabelle.

Rückgabewert

Die Größe in Bytes als bigint-Wert.

Beispiel

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

Entfernt alle Zeilen aus citus_stat_statements. Diese Funktion funktioniert unabhängig von pg_stat_statements_reset(). Um alle Statistiken zurückzusetzen, rufen Sie beide Funktionen auf.

Argumente

Nicht zutreffend

Rückgabewert

Keiner

citus_get_active_worker_nodes

Mit der Funktion „citus_get_active_worker_nodes()“ wird eine Liste mit Hostnamen und Portnummern aktiver Worker zurückgegeben.

Argumente

Nicht zutreffend

Rückgabewert

Liste der Tupel, wobei jedes Tupel die folgenden Informationen enthält:

node_name: DNS-Name des Workerknotens

node_port: Port im Workerknoten, auf dem der Datenbankserver lauscht

Beispiel

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

(3 rows)

Clusterverwaltung und -reparatur

master_copy_shard_placement

Wenn eine Shardplatzierung bei einem Änderungsbefehl oder einem DDL-Vorgang nicht aktualisiert werden kann, wird sie als inaktiv markiert. Die Funktion „master_copy_shard_placement“ kann dann aufgerufen werden, um eine inaktive Shardplatzierung mithilfe von Daten aus einer fehlerfreien Platzierung zu reparieren.

Zum Reparieren eines Shards löscht die Funktion zuerst die fehlerhafte Shardplatzierung und erstellt sie mithilfe des Schemas für den Koordinator neu. Nachdem die Shardplatzierung erstellt wurde, kopiert die Funktion Daten aus der fehlerfreien Platzierung und aktualisiert die Metadaten, um die neue Shardplatzierung als fehlerfrei zu markieren. Diese Funktion stellt sicher, dass der Shard vor gleichzeitigen Änderungen während der Reparatur geschützt wird.

Argumente

shard_id: ID des zu reparierenden Shards

source_node_name: DNS-Name des Knotens, auf dem die fehlerfreie Shardplatzierung vorhanden ist (Quellknoten)

source_node_port: Port auf dem Quellworkerknoten, an dem der Datenbankserver lauscht

target_node_name: DNS-Name des Knotens, auf dem die ungültige Shardplatzierung vorhanden ist (Zielknoten)

target_node_port: Port auf dem Zielworkerknoten, an dem der Datenbankserver lauscht

Rückgabewert

Nicht zutreffend

Beispiel

Im folgenden Beispiel wird eine inaktive Shardplatzierung von Shard 12345 repariert, die sich auf dem Datenbankserver befindet, der für „bad_host“ an Port 5432 ausgeführt wird. Um sie zu reparieren, werden Daten aus einer fehlerfreien Shardplatzierung auf dem Server verwendet, der für „good_host“ an Port 5432 ausgeführt wird.

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

master_move_shard_placement

Diese Funktion verschiebt einen angegebenen Shard (und darin verbundene Shards) von einem Knoten auf einen anderen. Sie wird in der Regel indirekt beim Shardausgleich verwendet, anstatt direkt von einem Datenbankadministrator aufgerufen zu werden.

Es gibt zwei Möglichkeiten, die Daten zu verschieben: blockierend oder nicht blockierend. Der Blockierungsansatz bedeutet, dass während der Verschiebung alle Änderungen am Shard angehalten werden. Die zweite Möglichkeit, mit der das Blockieren von Shardschreibvorgängen vermieden wird, beruht auf logischer Postgres 10-Replikation.

Nach einem erfolgreichen Verschiebevorgang werden Shards im Quellknoten gelöscht. Wenn die Verschiebung zu einem beliebigen Zeitpunkt fehlschlägt, löst diese Funktion einen Fehler aus, und die Quell- und Zielknoten bleiben unverändert.

Argumente

shard_id: ID des zu verschiebenden Shards

source_node_name: DNS-Name des Knotens, auf dem die fehlerfreie Shardplatzierung vorhanden ist (Quellknoten)

source_node_port: Port auf dem Quellworkerknoten, an dem der Datenbankserver lauscht

target_node_name: DNS-Name des Knotens, auf dem die ungültige Shardplatzierung vorhanden ist (Zielknoten)

target_node_port: Port auf dem Zielworkerknoten, an dem der Datenbankserver lauscht

shard_transfer_mode: (optional) Geben Sie die Replikationsmethode an: logische PostgreSQL-Replikation oder einen workerübergreifenden COPY-Befehl. Mögliche Werte sind:

auto: Erfordert Replikatidentität, wenn logische Replikation möglich ist, andernfalls wird das Legacyverhalten (für Shardreparatur z. B. PostgreSQL 9.6) verwendet. Dies ist der Standardwert.

force_logical: Verwendet logische Replikation auch dann, wenn die Tabelle keine Replikatidentität besitzt. Alle gleichzeitigen update/delete-Anweisungen für die Tabelle schlagen während der Replikation fehl.

block_writes: Verwenden Sie COPY (blockierende Schreibvorgänge) für Tabellen, die keinen Primärschlüssel oder keine Replikatidentität aufweisen.

Rückgabewert

Nicht zutreffend

Beispiel

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

rebalance_table_shards

Die Funktion „rebalance_table_shards()“ verschiebt Shards der angegebenen Tabelle, damit sie gleichmäßig auf die Worker verteilt werden. Die Funktion berechnet zunächst die Liste der erforderlichen Verschiebungen, um sicherzustellen, dass der Cluster innerhalb des angegebenen Schwellenwerts ausgeglichen ist. Anschließend werden die Shardplatzierungen nacheinander vom Quellknoten auf den Zielknoten verschoben, und die entsprechenden Shardmetadaten werden aktualisiert, um die Verschiebung widerzuspiegeln.

Jedem Shard werden Kosten zugewiesen, wenn ermittelt wird, ob Shards gleichmäßig verteilt sind. Standardmäßig weist jeder Shard die gleichen Kosten (den Wert 1) auf. Daher ist die Verteilung zum Ausgleichen der Kosten auf mehrere Worker identisch mit dem Ausgleichen der Anzahl der Shards für jeden Worker. Die konstante Kostenstrategie wird als „by_shard_count“ bezeichnet und ist die standardmäßige Ausgleichsstrategie.

Die Strategie „by_shard_count“ ist unter den folgenden Umständen angemessen:

Die Shards weisen ungefähr dieselbe Größe auf.
Die Shards erhalten ungefähr die gleiche Menge an Datenverkehr.
Die Workerknoten weisen alle dieselbe Größe bzw. denselben Typ auf.
Shards wurden nicht an bestimmte Worker angeheftet.

Wenn eine dieser Annahmen nicht zutrifft, dann kann der Neuausgleich von „by_shard_count“ zu einem schlechten Plan führen.

Die Standardstrategie für den Neuausgleich ist „by_disk_size“. Sie können die Strategie stets anpassen, indem Sie den Parameter rebalance_strategy verwenden.

Es empfiehlt sich, get_rebalance_table_shards_plan aufzurufen, bevor Sie „rebalance_table_shards“ ausführen, um die auszuführenden Aktionen anzuzeigen und zu überprüfen.

Argumente

table_name: (optional) Name der Tabelle, deren Shards ausgeglichen werden müssen. Wenn der Wert NULL ist, werden alle vorhandenen Colocationsgruppen ausgeglichen.

threshold: (Optional) Eine Gleitkommazahl zwischen 0,0 und 1,0, die das maximale Differenzverhältnis der Knotenverwendung von der durchschnittlichen Auslastung angibt. Wenn Sie z. B. 0,1 angeben, versucht der Shardrebalancer, alle Knoten so auszugleichen, dass sie die gleiche Anzahl von Shards (± 10 %) enthalten. Der Shardrebalancer versucht insbesondere, die Auslastung aller Workerknoten auf den (1 - Schwellenwert) × average_utilization ... (1

Schwellenwert) × average_utilization anzugleichen.

max_shard_moves: (optional) maximale Anzahl der zu verschiebenden Shards

excluded_shard_list: (optional) Bezeichner von Shards, die während des Vorgangs zum erneuten Ausgleichen nicht verschoben werden sollten

shard_transfer_mode: (optional) Geben Sie die Replikationsmethode an: logische PostgreSQL-Replikation oder einen workerübergreifenden COPY-Befehl. Mögliche Werte sind:

auto: Erfordert Replikatidentität, wenn logische Replikation möglich ist, andernfalls wird das Legacyverhalten (für Shardreparatur z. B. PostgreSQL 9.6) verwendet. Dies ist der Standardwert.

force_logical: Verwendet logische Replikation auch dann, wenn die Tabelle keine Replikatidentität besitzt. Alle gleichzeitigen update/delete-Anweisungen für die Tabelle schlagen während der Replikation fehl.

block_writes: Verwenden Sie COPY (blockierende Schreibvorgänge) für Tabellen, die keinen Primärschlüssel oder keine Replikatidentität aufweisen.

drain_only: (optional) beim Wert TRUE werden Shards von Workerknoten verschoben, für die shouldhaveshards in pg_dist_node auf FALSE festgelegt ist. Andere Shards werden nicht verschoben.

rebalance_strategy: (optional) Name einer Strategie in pg_dist_rebalance_strategy. Wenn dieses Argument ausgelassen wird, wählt die Funktion die Standardstrategie (wie in der Tabelle angegeben) aus.

Rückgabewert

Nicht zutreffend

Beispiel

Im folgenden Beispiel wird versucht, die Shards in der Tabelle „github_events“ innerhalb des Standardschwellenwerts auszugleichen.

SELECT rebalance_table_shards('github_events');

In diesem Beispiel wird versucht, die Tabelle „github_events“ neu auszugleichen, ohne Shards mit der ID 1 und 2 zu verschieben.

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

get_rebalance_table_shards_plan

Gibt die geplanten Shardbewegungen von rebalance_table_shards aus, ohne sie auszuführen. Es ist zwar unwahrscheinlich, aber „get_rebalance_table_shards_plan“ kann einen etwas anderen Plan ausgeben als ein Aufruf von „rebalance_table_shards“ mit den gleichen Argumenten. Die Aufrufe werden nicht gleichzeitig ausgeführt, sodass sich Fakten zum Cluster (z. B. der Speicherplatz) auf dem Datenträger möglicherweise zwischen den Aufrufen unterscheiden.

Argumente

Dieselben Argumente wie bei „rebalance_table_shards“: relation, threshold, max_shard_moves, excluded_shard_list und drain_only. Die Bedeutung der Argumente finden Sie in der Dokumentation der jeweiligen Funktion.

Rückgabewert

Tupel, die die folgenden Spalten enthalten:

table_name: Tabelle, deren Shards verschoben werden
shardid: Der jeweilige Shard.
shard_size: Größe in Byte
sourcename: Der Hostname des Quellknotens.
sourceport: Der Port des Quellknotens.
targetname: Der Hostname des Zielknotens.
targetport: Der Port des Zielknotens.

get_rebalance_progress

Nachdem ein Shardausgleich begonnen wurde, listet die get_rebalance_progress() -Funktion den Fortschritt aller beteiligten Shards auf. Sie überwacht die geplanten und von rebalance_table_shards() ausgeführten Verschiebungen.

Argumente

Nicht zutreffend

Rückgabewert

Tupel, die die folgenden Spalten enthalten:

sessionid: Die Postgres-PID des Ausgleichsmonitors.
table_name: Tabelle, deren Shards verschoben werden
shardid: Der jeweilige Shard.
shard_size: Größe in Byte
sourcename: Der Hostname des Quellknotens.
sourceport: Der Port des Quellknotens.
targetname: Der Hostname des Zielknotens.
targetport: Der Port des Zielknotens.
progress: 0 = auf Verschiebung wird gewartet, 1 = wird verschoben; 2 = abgeschlossen

Beispiel

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

Fügt pg_dist_rebalance_strategy eine Zeile hinzu.

Argumente

Weitere Informationen zu diesen Argumenten finden Sie in den entsprechenden Spaltenwerten in pg_dist_rebalance_strategy.

name: Bezeichner für die neue Strategie.

shard_cost_function: gibt die Funktion an, mit der die „Kosten“ der einzelnen Shards bestimmt werden

node_capacity_function: gibt die Funktion zum Messen der Knotenkapazitätapazität an

shard_allowed_on_node_function: gibt die Funktion an, die ermittelt, welche Shards auf welchen Knoten platziert werden können

default_threshold: Gleitkommaschwellenwert, der optimiert, wie genau die kumulierten Shardkosten zwischen den Knoten ausgeglichen werden sollen

minimum_threshold: (optional) Schutzspalte, die den Mindestwert enthält, der für das Schwellenwertargument von „rebalance_table_shards()“ zulässig ist. Der Standardwert ist 0.

Rückgabewert

Nicht zutreffend

citus_set_default_rebalance_strategy

Aktualisiert die pg_dist_rebalance_strategy-Tabelle und ändern die durch das Argument benannte Strategie so, dass sie beim erneuten Ausgleichen von Shards als Standard ausgewählt wird.

Argumente

name: Name einer Strategie in „pg_dist_rebalance_strategy“

Rückgabewert

Nicht zutreffend

Beispiel

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

Die Funktion „citus_remote_connection_stats“ zeigt die Anzahl der aktiven Verbindungen mit den einzelnen Remoteknoten an.

Argumente

Nicht zutreffend

Beispiel

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

Diese Funktion erstellt einen neuen Shard, der Zeilen mit einem bestimmten einzelnen Wert in der Verteilungsspalte enthält. Dies ist besonders nützlich für den Anwendungsfall mit mehreren Mandanten, bei dem ein großer Mandant allein in seinem eigenen Shard und damit auf seinem eigenen physischen Knoten platziert werden kann.

Argumente

table_name: Name der Tabelle, um einen neuen Shard abzurufen

tenant_id: Wert der Verteilungsspalte, der dem neuen Shard zugewiesen wird

cascade_option: (optional) Wenn diese Option auf CASCADE festgelegt ist, wird auch einen Shard aus allen Tabellen in der Colocationsguppe der aktuellen Tabelle isoliert.

Rückgabewert

shard_id: Die Funktion gibt die eindeutige ID zurück, die dem neu erstellten Shard zugewiesen ist.

Beispiele

Erstellen Sie einen neuen Shard, der die lineitems für den Mandanten 135 enthalten soll:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Nächste Schritte

Viele der Funktionen in diesem Artikel ändern Metadatentabellen des Systems.
Serverparameter passen das Verhalten einiger Funktionen an.