Funkcje usługi Azure Cosmos DB for PostgreSQL

Artykuł
10/27/2023

DOTYCZY: Usługa Azure Cosmos DB for PostgreSQL (obsługiwana przez rozszerzenie bazy danych Citus do bazy danych PostgreSQL)

Ta sekcja zawiera informacje referencyjne dotyczące funkcji zdefiniowanych przez użytkownika udostępnianych przez usługę Azure Cosmos DB for PostgreSQL. Te funkcje pomagają w dostarczaniu funkcji rozproszonych do usługi Azure Cosmos DB for PostgreSQL.

Uwaga

klastry z starszymi wersjami aparatu Citus mogą nie oferować wszystkich funkcji wymienionych na tej stronie.

Tabela i Shard DDL

citus_schema_distribute

Konwertuje istniejące schematy regularne na schematy rozproszone. Schematy rozproszone są automatycznie skojarzone z poszczególnymi grupami kolokacji. Tabele utworzone w tych schematach są konwertowane na kolokowane tabele rozproszone bez klucza fragmentu. Proces dystrybucji schematu jest automatycznie przypisywany i przenosi go do istniejącego węzła w klastrze.

Argumenty

schemaname: nazwa schematu, który musi być dystrybuowany.

Wartość zwracana

Nie dotyczy

Przykład

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

Aby uzyskać więcej przykładów, zobacz jak zaprojektować mikrousługi.

citus_schema_undistribute

Konwertuje istniejący schemat rozproszony z powrotem na zwykły schemat. Proces powoduje przeniesienie tabel i danych z bieżącego węzła z powrotem do węzła koordynacji w klastrze.

Argumenty

schemaname: nazwa schematu, który musi być dystrybuowany.

Wartość zwracana

Nie dotyczy

Przykład

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

Aby uzyskać więcej przykładów, zobacz jak zaprojektować mikrousługi.

create_distributed_table

Funkcja create_distributed_table() służy do definiowania tabeli rozproszonej i tworzenia fragmentów, jeśli jest to tabela rozproszona przy użyciu skrótu. Ta funkcja przyjmuje nazwę tabeli, kolumnę dystrybucji i opcjonalną metodę dystrybucji oraz wstawia odpowiednie metadane, aby oznaczyć tabelę jako rozproszoną. Funkcja jest domyślnie ustawiona na dystrybucję skrótu, jeśli nie określono żadnej metody dystrybucji. Jeśli tabela jest dystrybuowana przy użyciu skrótu, funkcja tworzy również fragmenty procesów roboczych na podstawie liczby fragmentów i wartości konfiguracji współczynnika replikacji fragmentów. Jeśli tabela zawiera jakiekolwiek wiersze, są one automatycznie dystrybuowane do węzłów roboczych.

Ta funkcja zastępuje użycie master_create_distributed_table(), a następnie master_create_worker_shards().

Argumenty

table_name: nazwa tabeli, która musi być dystrybuowana.

distribution_column: kolumna, w której ma być dystrybuowana tabela.

distribution_type: (Opcjonalnie) Metoda, zgodnie z którą tabela ma być dystrybuowana. Dopuszczalne wartości to dołączanie lub skrót z wartością domyślną "skrót".

colocate_with: (Opcjonalnie) dołącz bieżącą tabelę do grupy kolokacji innej tabeli. Domyślnie tabele są kolokowane, gdy są dystrybuowane według kolumn tego samego typu, mają tę samą liczbę fragmentów i mają ten sam współczynnik replikacji. Możliwe wartości colocate_with to default, none aby uruchomić nową grupę kolokacji lub nazwę innej tabeli do przeniesienia z tą tabelą. (Zobacz kolokację tabeli).

Należy pamiętać, że wartość domyślna colocate_with funkcji wykonuje niejawną kolokację. Kolokacja może być świetną rzeczą, gdy tabele są powiązane lub zostaną połączone. Jednak jeśli dwie tabele są niepowiązane, ale mają miejsce użycie tego samego typu danych dla kolumn dystrybucji, przypadkowe przeniesienie ich może zmniejszyć wydajność podczas ponownego równoważenia fragmentu. Fragmenty tabeli zostaną niepotrzebnie przeniesione w kaskadę.

Jeśli nowa tabela rozproszona nie jest powiązana z innymi tabelami, najlepiej określić wartość colocate_with => 'none'.

shard_count: (Opcjonalnie) liczba fragmentów do utworzenia dla nowej tabeli rozproszonej. Podczas określania shard_count nie można określić wartości innej colocate_with niż żadna. Aby zmienić liczbę fragmentów istniejącej tabeli lub grupy kolokacji, użyj funkcji alter_distributed_table .

Możliwe wartości to shard_count od 1 do 64000. Aby uzyskać wskazówki dotyczące wybierania optymalnej wartości, zobacz Liczba fragmentów.

Wartość zwracana

Nie dotyczy

Przykład

Ten przykład informuje bazę danych, że tabela github_events powinna być dystrybuowana przez skrót w kolumnie 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

Ta funkcja ma ten sam interfejs i przeznaczenie co create_distributed_function, ale nie blokuje zapisów podczas dystrybucji tabel.

Jednak create_distributed_table_concurrently ma kilka ograniczeń:

Nie można użyć funkcji w bloku transakcji, co oznacza, że można dystrybuować tylko jedną tabelę naraz. (Można jednak użyć funkcji w tabelach podzielonych na partycje czasowe).
Nie można użyć create_distributed_table_concurrently , gdy tabela jest przywołynięta przez klucz obcy lub odwołuje się do innej tabeli lokalnej. Jednak klucze obce do tabel odwołań działają i można utworzyć klucze obce w innych tabelach rozproszonych po zakończeniu dystrybucji tabel.
Jeśli nie masz klucza podstawowego ani tożsamości repliki w tabeli, aktualizacja i usunięcie poleceń zakończy się niepowodzeniem podczas dystrybucji tabel z powodu ograniczeń związanych z replikacją logiczną.

truncate_local_data_after_distributing_table

Obcinaj wszystkie wiersze lokalne po dystrybucji tabeli i zapobiegaj awarii ograniczeń z powodu nieaktualnych rekordów lokalnych. Kaskadowe obcinanie tabel o obcym kluczu do wyznaczonej tabeli. Jeśli tabele odwołujące się nie są rozproszone, obcinanie jest zabronione do czasu ich uzyskania, aby chronić integralność referencyjną:

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

Obcinanie lokalnych danych tabeli węzłów koordynacji jest bezpieczne dla tabel rozproszonych, ponieważ ich wiersze, jeśli istnieją, są kopiowane do węzłów roboczych podczas dystrybucji.

Argumenty

table_name: nazwa tabeli rozproszonej, której lokalny odpowiednik w węźle koordynacji powinien zostać obcięty.

Wartość zwracana

Nie dotyczy

Przykład

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

create_reference_table

Funkcja create_reference_table() służy do definiowania małej tabeli odwołań lub wymiarów. Ta funkcja przyjmuje nazwę tabeli i tworzy tabelę rozproszoną z tylko jednym fragmentem replikowanym do każdego węzła roboczego.

Argumenty

table_name: nazwa małej tabeli wymiarowej lub referencyjnej, która musi być dystrybuowana.

Wartość zwracana

Nie dotyczy

Przykład

Ten przykład informuje bazę danych, że tabela nation powinna być zdefiniowana jako tabela referencyjna

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Dodaje lokalną tabelę Postgres do metadanych Citus. Głównym przypadkiem użycia tej funkcji jest udostępnienie tabel lokalnych w koordynatorze z dowolnego węzła w klastrze. Dane skojarzone z tabelą lokalną pozostają na koordynatorze — do procesów roboczych są wysyłane tylko jego schemat i metadane.

Dodanie tabel lokalnych do metadanych wiąże się z niewielkimi kosztami. Po dodaniu tabeli Citus musi ją śledzić w tabeli partycji. Tabele lokalne dodawane do metadanych dziedziczą te same ograniczenia co tabele odwołań.

Po cofnięciu dystrybucji tabeli Citus usuwa wynikowe tabele lokalne z metadanych, co eliminuje takie ograniczenia w tych tabelach.

Argumenty

table_name: nazwa tabeli koordynatora, która ma zostać dodana do metadanych Citus.

cascade_via_foreign_keys: (Opcjonalnie) Jeśli ten argument ma wartość "true", citus_add_local_table_to_metadata dodaje inne tabele, które znajdują się w relacji klucza obcego z daną tabelą do metadanych automatycznie. Należy zachować ostrożność w przypadku tego parametru, ponieważ może to potencjalnie mieć wpływ na wiele tabel.

Wartość zwracana

Nie dotyczy

Przykład

Ten przykład informuje bazę danych, że tabela narodu powinna być zdefiniowana jako tabela lokalna koordynatora, dostępna z dowolnego węzła:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

Funkcja alter_distributed_table() może służyć do zmiany kolumny dystrybucji, liczby fragmentów lub właściwości kolokacji tabeli rozproszonej.

Argumenty

table_name: nazwa tabeli, która zostanie zmieniona.

distribution_column: (Opcjonalnie) Nazwa nowej kolumny dystrybucji.

shard_count: (Opcjonalnie) Nowa liczba fragmentów.

colocate_with: (Opcjonalnie) Tabela, z którą zostanie przeniesiona bieżąca tabela rozproszona. Możliwe wartości to default, none aby uruchomić nową grupę kolokacji lub nazwę innej tabeli, z którą ma być kolokacja. (Zobacz kolokację tabeli).

cascade_to_colocated: (Opcjonalnie) Jeśli ten argument jest ustawiony na wartość "true", shard_count a colocate_with zmiany zostaną również zastosowane do wszystkich tabel, które zostały wcześniej przeniesione do tabeli, a kolokacja zostanie zachowana. Jeśli jest to wartość "false", bieżąca kolokacja tej tabeli zostanie przerwana.

Wartość zwracana

Nie dotyczy

Przykład

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

Funkcja update_distributed_table_colocation() służy do aktualizowania kolokacji tabeli rozproszonej. Ta funkcja może również służyć do przerywania kolokacji tabeli rozproszonej. Usługa Azure Cosmos DB for PostgreSQL niejawnie kolokuje dwie tabele, jeśli kolumna dystrybucji jest tego samego typu, może to być przydatne, jeśli tabele są powiązane i będą wykonywać pewne sprzężenia. Jeśli tabele A i B są kolokowane, a tabela A zostanie ponownie zrównoważona, tabela B również zostanie ponownie zrównoważona. Jeśli tabela B nie ma tożsamości repliki, ponowne równoważenie zakończy się niepowodzeniem. W związku z tym ta funkcja może być przydatna, powodując niezgodność niejawnej kolokacji w tym przypadku.

Ta funkcja nie przenosi żadnych danych w sposób fizyczny.

Argumenty

table_name: nazwa kolokacji tabeli, która zostanie zaktualizowana.

colocate_with: tabela, z którą powinna zostać przeniesiona tabela.

Jeśli chcesz przerwać kolokację tabeli, należy określić wartość colocate_with => 'none'.

Wartość zwracana

Nie dotyczy

Przykład

W tym przykładzie pokazano, że kolokacja tabeli A jest aktualizowana jako kolokacja tabeli B.

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

Załóżmy, że tabela A i tabela B są kolokowane (prawdopodobnie niejawnie), jeśli chcesz przerwać kolokację:

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

Teraz załóżmy, że tabela A, tabela B, tabela C i tabela D są kolokowane i chcesz kolokować tabelę A i tabelę B razem, a tabelę C i tabelę D razem:

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

Jeśli masz tabelę rozproszoną skrótu o nazwie none i chcesz zaktualizować jej kolokację, możesz wykonać następujące czynności:

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

undistribute_table

Funkcja undistribute_table() cofa akcję create_distributed_table lub create_reference_table. Cofanie dystrybucji przenosi wszystkie dane z fragmentów z powrotem do tabeli lokalnej w węźle koordynacji (przy założeniu, że dane mogą pasować), a następnie usuwa fragmenty.

Usługa Azure Cosmos DB for PostgreSQL nie będzie odwoływała tabel, do których odwołują się klucze obce, chyba że argument cascade_via_foreign_keys ma wartość true. Jeśli ten argument jest fałszywy (lub pominięty), przed cofnięciem należy ręcznie usunąć naruszenia ograniczeń klucza obcego.

Argumenty

table_name: nazwa tabeli rozproszonej lub referencyjnej, która ma być niezakłócona.

cascade_via_foreign_keys: (Opcjonalnie) Jeśli ten argument ma wartość "true", undistribute_table również nie rozdziela wszystkich tabel powiązanych z table_name za pomocą kluczy obcych. Należy zachować ostrożność w przypadku tego parametru, ponieważ może to potencjalnie mieć wpływ na wiele tabel.

Wartość zwracana

Nie dotyczy

Przykład

Ten przykład dystrybuuje tabelę github_events , a następnie ją nie rozdziela.

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

Propaguje funkcję z węzła koordynatora do procesów roboczych i oznacza ją do wykonywania rozproszonego. Gdy funkcja rozproszona jest wywoływana na koordynatorze, usługa Azure Cosmos DB for PostgreSQL używa wartości "argumentu dystrybucji", aby wybrać węzeł procesu roboczego do uruchomienia funkcji. Wykonywanie funkcji dla procesów roboczych zwiększa równoległość i może przybliżyć kod do danych w fragmentach w celu uzyskania mniejszego opóźnienia.

Ścieżka wyszukiwania Postgres nie jest propagowana z koordynatora do procesów roboczych podczas wykonywania funkcji rozproszonej, dlatego kod funkcji rozproszonej powinien w pełni kwalifikować nazwy obiektów bazy danych. Ponadto powiadomienia emitowane przez funkcje nie będą wyświetlane użytkownikowi.

Argumenty

function_name: nazwa funkcji, która ma być dystrybuowana. Nazwa musi zawierać typy parametrów funkcji w nawiasach, ponieważ wiele funkcji może mieć taką samą nazwę w usłudze PostgreSQL. Na przykład 'foo(int)' różni się od 'foo(int, text)'.

distribution_arg_name: (Opcjonalnie) Nazwa argumentu, za pomocą którego ma być dystrybuowana. Dla wygody (lub jeśli argumenty funkcji nie mają nazw), symbol zastępczy pozycyjny jest dozwolony, taki jak '$1'. Jeśli ten parametr nie jest określony, funkcja o nazwie by function_name jest tworzona tylko dla procesów roboczych. Jeśli węzły procesu roboczego zostaną dodane w przyszłości, funkcja zostanie również automatycznie utworzona.

colocate_with: (Opcjonalnie) Gdy funkcja rozproszona odczytuje lub zapisuje w tabeli rozproszonej (lub ogólniej, w grupie kolokacji), pamiętaj, aby nazwać tę tabelę przy użyciu parametru colocate_with . Następnie każde wywołanie funkcji zostanie uruchomione w węźle roboczym zawierającym odpowiednie fragmenty.

Wartość zwracana

Nie dotyczy

Przykład

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

Funkcja alter_columnar_table_set() zmienia ustawienia w tabeli kolumnowej. Wywołanie tej funkcji w tabeli niekolumnanej powoduje wystąpienie błędu. Wszystkie argumenty z wyjątkiem nazwy tabeli są opcjonalne.

Aby wyświetlić bieżące opcje dla wszystkich tabel kolumnowych, zapoznaj się z tą tabelą:

SELECT * FROM columnar.options;

Wartości domyślne dla ustawień kolumnowych dla nowo utworzonych tabel można zastąpić następującymi interfejsami GUCs:

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

Argumenty

table_name: nazwa tabeli kolumnowej.

chunk_row_count: (Opcjonalnie) Maksymalna liczba wierszy na fragment dla nowo wstawionych danych. Istniejące fragmenty danych nie zostaną zmienione i mogą zawierać więcej wierszy niż ta maksymalna wartość. Wartość domyślna to 10000.

stripe_row_count: (Opcjonalnie) Maksymalna liczba wierszy na paski dla nowo wstawionych danych. Istniejące paski danych nie zostaną zmienione i mogą mieć więcej wierszy niż ta maksymalna wartość. Wartość domyślna to 150000.

kompresja: (Opcjonalnie) [none|pglz|zstd|lz4|lz4hc] Typ kompresji dla nowo wstawionych danych. Istniejące dane nie będą rekompresowane ani dekompresowane. Wartość domyślna i sugerowana to zstd (jeśli obsługa została skompilowana w pliku).

compression_level: (Opcjonalnie) Prawidłowe ustawienia to od 1 do 19. Jeśli metoda kompresji nie obsługuje wybranego poziomu, zostanie wybrany najbliższy poziom.

Wartość zwracana

Nie dotyczy

Przykład

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

alter_table_set_access_method

Funkcja alter_table_set_access_method() zmienia metodę dostępu tabeli (na przykład stertę lub kolumnę).

Argumenty

table_name: nazwa tabeli, której metoda dostępu ulegnie zmianie.

access_method: nazwa nowej metody dostępu.

Wartość zwracana

Nie dotyczy

Przykład

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

create_time_partitions

Funkcja create_time_partitions() tworzy partycje danego interwału w celu pokrycia danego zakresu czasu.

Argumenty

table_name: (regclass) tabela, dla której mają zostać utworzone nowe partycje. Tabela musi być podzielona na partycje w jednej kolumnie, typu data, sygnatura czasowa lub sygnatura czasowa.

partition_interval: interwał czasu, taki jak '2 hours', lub '1 month', do użycia podczas ustawiania zakresów na nowych partycjach.

end_at: (timestamptz) utwórz partycje do tej pory. Ostatnia partycja będzie zawierać punkt end_at i nie zostaną utworzone żadne późniejsze partycje.

start_from: (sygnatura czasowa, opcjonalnie) wybierz pierwszą partycję, aby zawierała start_from punktów. Domyślna wartość to now().

Wartość zwracana

Wartość True, jeśli jest to konieczne do utworzenia nowych partycji, wartość false, jeśli wszystkie już istniały.

Przykład

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

Funkcja drop_old_time_partitions() usuwa wszystkie partycje, których interwały spadną przed danym znacznikiem czasu. Oprócz korzystania z tej funkcji można rozważyć alter_old_partitions_set_access_method kompresować stare partycje z magazynem kolumnowym.

Argumenty

table_name: (regclass) tabela, dla której mają być usuwane partycje. Tabela musi być podzielona na partycje w jednej kolumnie, typu data, sygnatura czasowa lub sygnatura czasowa.

older_than: (timestamptz) upuść partycje, których górny zakres jest mniejszy lub równy older_than.

Wartość zwracana

Nie dotyczy

Przykład

-- drop partitions that are over a year old

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

alter_old_partitions_set_access_method

W przypadku użycia czasowych tabele są często partycjonowane według czasu, a stare partycje są kompresowane do magazynu kolumnowego tylko do odczytu.

Argumenty

parent_table_name: (regclass) tabela, dla której mają być zmieniane partycje. Tabela musi być podzielona na partycje w jednej kolumnie, typu data, sygnatura czasowa lub sygnatura czasowa.

older_than: (sygnatura czasowa) zmienia partycje, których górny zakres jest mniejszy lub równy older_than.

new_access_method: (nazwa) "sterta" dla magazynu opartego na wierszach lub "columnar" dla magazynu kolumnowego.

Wartość zwracana

Nie dotyczy

Przykład

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

Metadane/informacje o konfiguracji

get_shard_id_for_distribution_column

Usługa Azure Cosmos DB for PostgreSQL przypisuje każdy wiersz tabeli rozproszonej do fragmentu na podstawie wartości kolumny dystrybucji wiersza i metody rozkładu tabeli. W większości przypadków dokładne mapowanie to szczegóły niskiego poziomu, które administrator bazy danych może zignorować. Jednak może to być przydatne do określenia fragmentu wiersza, zarówno w przypadku ręcznych zadań konserwacji bazy danych, jak i po prostu w celu zaspokojenia ciekawości. Funkcja get_shard_id_for_distribution_column udostępnia te informacje dla tabel rozproszonych przy użyciu skrótów, rozproszonych zakresów i odwołań. Nie działa w przypadku dystrybucji dołączania.

Argumenty

table_name: tabela rozproszona.

distribution_value: wartość kolumny dystrybucji.

Wartość zwracana

Identyfikator fragmentu usługi Azure Cosmos DB for PostgreSQL kojarzy się z wartością kolumny dystrybucji dla danej tabeli.

Przykład

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

Tłumaczy kolumnę partkeypg_dist_partition na tekstową nazwę kolumny. Tłumaczenie jest przydatne do określenia kolumny rozkładu tabeli rozproszonej.

Aby uzyskać bardziej szczegółową dyskusję, zobacz wybieranie kolumny dystrybucji.

Argumenty

table_name: tabela rozproszona.

column_var_text: wartość partkey w pg_dist_partition tabeli.

Wartość zwracana

Nazwa table_namekolumny dystrybucji.

Przykład

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

Wyjście:

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

citus_relation_size

Pobierz miejsce na dysku używane przez wszystkie fragmenty określonej tabeli rozproszonej. Miejsce na dysku obejmuje rozmiar "głównego rozwidlenia", ale wyklucza mapę widoczności i mapę wolnego miejsca dla fragmentów.

Argumenty

logicalrelid: nazwa tabeli rozproszonej.

Wartość zwracana

Rozmiar w bajtach jako bigint.

Przykład

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

Pobierz miejsce na dysku używane przez wszystkie fragmenty określonej tabeli rozproszonej, z wyłączeniem indeksów (ale w tym TOAST, wolna mapa miejsca i mapa widoczności).

Argumenty

logicalrelid: nazwa tabeli rozproszonej.

Wartość zwracana

Rozmiar w bajtach jako bigint.

Przykład

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

Pobierz łączną ilość miejsca na dysku używanego przez wszystkie fragmenty określonej tabeli rozproszonej, w tym wszystkie indeksy i dane TOAST.

Argumenty

logicalrelid: nazwa tabeli rozproszonej.

Wartość zwracana

Rozmiar w bajtach jako bigint.

Przykład

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

Usuwa wszystkie wiersze z citus_stat_statements. Ta funkcja działa niezależnie od pg_stat_statements_reset(). Aby zresetować wszystkie statystyki, wywołaj obie funkcje.

Argumenty

Nie dotyczy

Wartość zwracana

Brak

citus_get_active_worker_nodes

Funkcja citus_get_active_worker_nodes() zwraca listę aktywnych nazw hostów procesu roboczego i numerów portów.

Argumenty

Nie dotyczy

Wartość zwracana

Lista krotki, w których każda krotka zawiera następujące informacje:

node_name: nazwa DNS węzła roboczego

node_port: Port w węźle roboczym, na którym nasłuchuje serwer bazy danych

Przykład

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

(3 rows)

Zarządzanie klastrem i naprawianie

master_copy_shard_placement

Jeśli nie można zaktualizować umieszczania fragmentów podczas polecenia modyfikacji lub operacji DDL, zostanie ona oznaczona jako nieaktywna. Następnie można wywołać funkcję master_copy_shard_placement w celu naprawienia nieaktywnego umieszczania fragmentów przy użyciu danych z umieszczania w dobrej kondycji.

Aby naprawić fragment, funkcja najpierw usuwa umieszczanie fragmentów w złej kondycji i tworzy je ponownie przy użyciu schematu koordynatora. Po utworzeniu umieszczania fragmentów funkcja kopiuje dane z umieszczania w dobrej kondycji i aktualizuje metadane, aby oznaczyć nowe rozmieszczenie fragmentów jako w dobrej kondycji. Ta funkcja gwarantuje, że fragment będzie chroniony przed wszelkimi współbieżnych modyfikacjami podczas naprawy.

Argumenty

shard_id: identyfikator fragmentu, który ma zostać naprawiony.

source_node_name: nazwa DNS węzła, w którym znajduje się umieszczanie fragmentów w dobrej kondycji ("węzeł źródłowy").

source_node_port: port w źródłowym węźle roboczym, na którym nasłuchuje serwer bazy danych.

target_node_name: nazwa DNS węzła, w którym znajduje się nieprawidłowe rozmieszczenie fragmentów ("węzeł docelowy").

target_node_port: port w docelowym węźle roboczym, na którym nasłuchuje serwer bazy danych.

Wartość zwracana

Nie dotyczy

Przykład

W poniższym przykładzie naprawiono nieaktywne rozmieszczenie fragmentu 12345, który znajduje się na serwerze bazy danych uruchomionym na "bad_host" na porcie 5432. Aby go naprawić, będzie używać danych z umieszczania fragmentów w dobrej kondycji na serwerze uruchomionym na "good_host" na porcie 5432.

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

master_move_shard_placement

Ta funkcja przenosi dany fragment (i fragmenty kolokowane z nim) z jednego węzła do drugiego. Jest on zwykle używany pośrednio podczas ponownego równoważenia fragmentu, a nie wywoływany bezpośrednio przez administratora bazy danych.

Istnieją dwa sposoby przenoszenia danych: blokowanie lub blokowanie. Podejście blokujące oznacza, że podczas przenoszenia wszystkie modyfikacje fragmentu są wstrzymane. Drugi sposób, który unika blokowania zapisów fragmentów, opiera się na replikacji logicznej Postgres 10.

Po pomyślnej operacji przenoszenia fragmenty w węźle źródłowym zostaną usunięte. Jeśli przeniesienie zakończy się niepowodzeniem w dowolnym momencie, ta funkcja zgłasza błąd i pozostawia węzły źródłowe i docelowe bez zmian.

Argumenty

shard_id: identyfikator fragmentu do przeniesienia.

source_node_name: nazwa DNS węzła, w którym znajduje się umieszczanie fragmentów w dobrej kondycji ("węzeł źródłowy").

source_node_port: port w źródłowym węźle roboczym, na którym nasłuchuje serwer bazy danych.

target_node_name: nazwa DNS węzła, w którym znajduje się nieprawidłowe rozmieszczenie fragmentów ("węzeł docelowy").

target_node_port: port w docelowym węźle roboczym, na którym nasłuchuje serwer bazy danych.

shard_transfer_mode: (opcjonalnie) Określ metodę replikacji, niezależnie od tego, czy używać replikacji logicznej PostgreSQL, czy polecenia COPY między procesami roboczymi. Możliwe wartości to:

auto: Wymagaj tożsamości repliki, jeśli jest możliwa replikacja logiczna, w przeciwnym razie użyj starszego zachowania (np. do naprawy fragmentów, PostgreSQL 9.6). Jest to wartość domyślna.

force_logical: Użyj replikacji logicznej, nawet jeśli tabela nie ma tożsamości repliki. Wszystkie współbieżne instrukcje aktualizacji/usuwania do tabeli nie powiedzą się podczas replikacji.

block_writes: Użyj funkcji COPY (blokujących zapisy) dla tabel, w których brakuje klucza podstawowego lub tożsamości repliki.

Wartość zwracana

Nie dotyczy

Przykład

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

rebalance_table_shards

Funkcja rebalance_table_shards() przenosi fragmenty danej tabeli, aby równomiernie rozłożyć je między procesami roboczymi. Funkcja najpierw oblicza listę ruchów, które musi wykonać, aby upewnić się, że klaster jest zrównoważony w ramach danego progu. Następnie przenosi umieszczanie fragmentów jeden po jednym z węzła źródłowego do węzła docelowego i aktualizuje odpowiednie metadane fragmentu w celu odzwierciedlenia przeniesienia.

Każdy fragment jest przypisywany koszt podczas określania, czy fragmenty są "równomiernie rozproszone". Domyślnie każdy fragment ma ten sam koszt (wartość 1), więc dystrybucja w celu wyrównania kosztów między procesami roboczymi jest taka sama jak równanie liczby fragmentów na każdym z nich. Strategia stałego kosztu jest nazywana "by_shard_count" i jest domyślną strategią ponownego równoważenia.

Strategia "by_shard_count" jest odpowiednia w następujących okolicznościach:

Fragmenty mają mniej więcej taki sam rozmiar
Fragmenty uzyskują mniej więcej taką samą ilość ruchu
Węzły procesu roboczego mają ten sam rozmiar/typ
Fragmenty nie zostały przypięte do określonych procesów roboczych

Jeśli którekolwiek z tych założeń nie zostanie wstrzymane, ponowne równoważenie "by_shard_count" może spowodować zły plan.

Domyślna strategia ponownego równoważenia to "by_disk_size". Zawsze możesz dostosować strategię przy użyciu parametru rebalance_strategy .

Zaleca się wywołanie get_rebalance_table_shards_plan przed uruchomieniem rebalance_table_shards, aby zobaczyć i zweryfikować akcje do wykonania.

Argumenty

table_name: (Opcjonalnie) Nazwa tabeli, której fragmenty muszą zostać ponownie zrównoważone. Jeśli wartość NULL, należy ponownie zrównoważyć wszystkie istniejące grupy kolokacji.

próg: (Opcjonalnie) Liczba zmiennoprzecinkowa z zakresu od 0,0 do 1,0, która wskazuje maksymalny współczynnik wykorzystania węzła ze średniego wykorzystania. Na przykład określenie wartości 0,1 spowoduje ponowne równoważenie fragmentów, aby spróbować zrównoważyć wszystkie węzły do przechowywania tej samej liczby fragmentów ±10%. W szczególności moduł ponownego równoważenia fragmentu spróbuje zrównoważyć wykorzystanie wszystkich węzłów procesu roboczego do wartości (1 - próg) * average_utilization ... (1

próg) * zakres average_utilization.

max_shard_moves: (Opcjonalnie) Maksymalna liczba fragmentów do przeniesienia.

excluded_shard_list: (opcjonalnie) Identyfikatory fragmentów, które nie powinny być przenoszone podczas operacji ponownego równoważenia.

auto: Wymagaj tożsamości repliki, jeśli jest możliwa replikacja logiczna, w przeciwnym razie użyj starszego zachowania (np. do naprawy fragmentów, PostgreSQL 9.6). Jest to wartość domyślna.

force_logical: Użyj replikacji logicznej, nawet jeśli tabela nie ma tożsamości repliki. Wszystkie współbieżne instrukcje aktualizacji/usuwania do tabeli nie powiedzą się podczas replikacji.

block_writes: Użyj funkcji COPY (blokujących zapisy) dla tabel, w których brakuje klucza podstawowego lub tożsamości repliki.

drain_only: (Opcjonalnie) Jeśli wartość true, przenieś fragmenty z węzłów roboczych, które zostały shouldhaveshards ustawione na wartość false w pg_dist_node; nie przenieś żadnych innych fragmentów.

rebalance_strategy: (Opcjonalnie) nazwa strategii w pg_dist_rebalance_strategy. Jeśli ten argument zostanie pominięty, funkcja wybierze strategię domyślną, jak wskazano w tabeli.

Wartość zwracana

Nie dotyczy

Przykład

Poniższy przykład spróbuje ponownie zrównoważyć fragmenty tabeli github_events w ramach domyślnego progu.

SELECT rebalance_table_shards('github_events');

To przykładowe użycie spróbuje ponownie zrównoważyć tabelę github_events bez przenoszenia fragmentów o identyfikatorze 1 i 2.

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

get_rebalance_table_shards_plan

Wyprowadź planowane ruchy fragmentów rebalance_table_shards bez ich wykonywania. Chociaż jest mało prawdopodobne, get_rebalance_table_shards_plan może uzyskać nieco inny plan niż wywołanie rebalance_table_shards z tymi samymi argumentami. Nie są one wykonywane w tym samym czasie, więc fakty dotyczące klastra — na przykład miejsce na dysku — mogą się różnić między wywołaniami.

Argumenty

Te same argumenty co rebalance_table_shards: relacja, próg, max_shard_moves, excluded_shard_list i drain_only. Zapoznaj się z dokumentacją tej funkcji, aby zapoznać się z znaczeniem argumentów.

Wartość zwracana

Krotki zawierające następujące kolumny:

table_name: Tabela, której fragmenty zostaną przeniesione
shardid: Fragment, o którym mowa
shard_size: rozmiar w bajtach
sourcename: Nazwa hosta węzła źródłowego
sourceport: port węzła źródłowego
targetname: nazwa hosta węzła docelowego
targetport: port węzła docelowego

get_rebalance_progress

Po rozpoczęciu get_rebalance_progress() ponownego równoważenia fragmentu funkcja wyświetla postęp każdego zaangażowanego fragmentu. Monitoruje planowane i wykonywane rebalance_table_shards()przez program ruchy .

Argumenty

Nie dotyczy

Wartość zwracana

Krotki zawierające następujące kolumny:

sessionid: Postgres PID monitora ponownego równoważenia
table_name: Tabela, której fragmenty są przenoszone
shardid: Fragment, o którym mowa
shard_size: rozmiar w bajtach
sourcename: Nazwa hosta węzła źródłowego
sourceport: port węzła źródłowego
targetname: nazwa hosta węzła docelowego
targetport: port węzła docelowego
postęp: 0 = oczekiwanie na przeniesienie; 1 = przenoszenie; 2 = ukończone

Przykład

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

Dołącz wiersz do pg_dist_rebalance_strategy .

Argumenty

Aby uzyskać więcej informacji na temat tych argumentów, zobacz odpowiednie wartości kolumn w pliku pg_dist_rebalance_strategy.

name: identyfikator nowej strategii

shard_cost_function: identyfikuje funkcję używaną do określania "kosztu" każdego fragmentu

node_capacity_function: identyfikuje funkcję do mierzenia pojemności węzła

shard_allowed_on_node_function: identyfikuje funkcję, która określa, które fragmenty można umieścić w których węzłach

default_threshold: próg zmiennoprzecinkowa, który dostraja, jak dokładnie skumulowany koszt fragmentu powinien być zrównoważony między węzłami

minimum_threshold: (Opcjonalnie) kolumna ochrony zawierająca minimalną wartość dozwoloną dla argumentu progu rebalance_table_shards(). Jego wartość domyślna to 0

Wartość zwracana

Nie dotyczy

citus_set_default_rebalance_strategy

Zaktualizuj tabelę pg_dist_rebalance_strategy , zmieniając strategię o nazwie według jej argumentu na wartość domyślną wybraną podczas ponownego równoważenia fragmentów.

Argumenty

name: nazwa strategii w pg_dist_rebalance_strategy

Wartość zwracana

Nie dotyczy

Przykład

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

Funkcja citus_remote_connection_stats() pokazuje liczbę aktywnych połączeń z każdym węzłem zdalnym.

Argumenty

Nie dotyczy

Przykład

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

Ta funkcja tworzy nowy fragment do przechowywania wierszy z określoną pojedynczą wartością w kolumnie dystrybucji. Jest to szczególnie przydatne w przypadku wielodostępnego użycia, w którym duża dzierżawa może zostać umieszczona samodzielnie na własnym fragmentie i ostatecznie własnym węźle fizycznym.

Argumenty

table_name: nazwa tabeli w celu pobrania nowego fragmentu.

tenant_id: wartość kolumny dystrybucji, która zostanie przypisana do nowego fragmentu.

cascade_option: (Opcjonalnie) Po ustawieniu wartości "CASCADE" również izoluje fragment ze wszystkich tabel w grupie kolokacji bieżącej tabeli.

Wartość zwracana

shard_id: funkcja zwraca unikatowy identyfikator przypisany do nowo utworzonego fragmentu.

Przykłady

Utwórz nowy fragment do przechowywania elementów lineitem dla dzierżawy 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Następne kroki

Wiele funkcji w tym artykule modyfikuje tabele metadanych systemu
Parametry serwera dostosują zachowanie niektórych funkcji

Udostępnij przez

Funkcje usługi Azure Cosmos DB for PostgreSQL

Tabela i Shard DDL

citus_schema_distribute

Argumenty

Wartość zwracana

Przykład

citus_schema_undistribute

Argumenty

Wartość zwracana

Przykład

create_distributed_table

Argumenty

Wartość zwracana

Przykład

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argumenty

Wartość zwracana

Przykład

create_reference_table

Argumenty

Wartość zwracana

Przykład

citus_add_local_table_to_metadata

Argumenty

Wartość zwracana

Przykład

alter_distributed_table

Argumenty

Wartość zwracana

Przykład

update_distributed_table_colocation

Argumenty

Wartość zwracana

Przykład

undistribute_table

Argumenty

Wartość zwracana

Przykład

create_distributed_function

Argumenty

Wartość zwracana

Przykład

alter_columnar_table_set

Argumenty

Wartość zwracana

Przykład

alter_table_set_access_method

Argumenty

Wartość zwracana

Przykład

create_time_partitions

Argumenty

Wartość zwracana

Przykład

drop_old_time_partitions

Argumenty

Wartość zwracana

Przykład

alter_old_partitions_set_access_method

Argumenty

Wartość zwracana

Przykład

Metadane/informacje o konfiguracji

get_shard_id_for_distribution_column

Argumenty

Wartość zwracana

Przykład

column_to_column_name

Argumenty

Wartość zwracana

Przykład

citus_relation_size

Argumenty

Wartość zwracana

Przykład

citus_table_size

Argumenty

Wartość zwracana