Azure Cosmos DB for PostgreSQL-függvények

Cikk
08/15/2024

A KÖVETKEZŐKRE VONATKOZIK: Azure Cosmos DB for PostgreSQL (a Citus adatbázisbővítménye a PostgreSQL-re)

Ez a szakasz az Azure Cosmos DB for PostgreSQL által biztosított felhasználó által megadott függvényekre vonatkozó referenciainformációkat tartalmazza. Ezek a függvények segítenek elosztott funkciók biztosításában az Azure Cosmos DB for PostgreSQL számára.

Feljegyzés

A Citus Engine régebbi verzióit futtató fürtök nem feltétlenül biztosítják az ezen a lapon felsorolt összes függvényt.

Tábla és szegmens DDL

citus_schema_distribute

A meglévő normál sémákat elosztott sémákká alakítja. Az elosztott sémák automatikusan társítva vannak az egyes elhelyezési csoportokkal. Az ezekben a sémákban létrehozott táblák szilánkkulcs nélküli elosztott táblákká lesznek konvertálva. A séma terjesztésének folyamata automatikusan hozzárendeli és áthelyezi azt a fürt egy meglévő csomópontjára.

Argumentumok

sémanév: A séma neve, amelyet el kell osztani.

Visszaadott érték

n/a

Példa

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

További példákért tekintse meg a mikroszolgáltatások tervezésének útmutatóit.

citus_schema_undistribute

Egy meglévő elosztott sémát visszaalakít normál sémává. A folyamat azt eredményezi, hogy a táblák és az adatok az aktuális csomópontról visszakerülnek a fürt koordinátor csomópontja felé.

Argumentumok

sémanév: A séma neve, amelyet el kell osztani.

Visszaadott érték

n/a

Példa

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

További példákért tekintse meg a mikroszolgáltatások tervezésének útmutatóit.

create_distributed_table

A create_distributed_table() függvény egy elosztott tábla definiálására és szegmenseinek létrehozására szolgál, ha kivonatelosztott tábla. Ez a függvény egy táblanevet, egy terjesztési oszlopot és egy opcionális terjesztési módszert vesz fel, és beszúrja a megfelelő metaadatokat a tábla elosztottként való megjelöléséhez. A függvény alapértelmezés szerint "kivonat" eloszlás, ha nincs megadva terjesztési módszer. Ha a tábla kivonatos eloszlású, a függvény a szegmensek száma és a szegmensreplikációs tényező konfigurációs értékei alapján is létrehoz munkavégző szegmenseket. Ha a tábla tartalmaz sorokat, azok automatikusan el lesznek osztva a feldolgozó csomópontok között.

Ez a függvény felváltja a master_create_distributed_table() használatát, majd a master_create_worker_shards() függvényt.

Argumentumok

table_name: Az elosztandó tábla neve.

distribution_column: Az az oszlop, amelyen a táblázatot el kell osztani.

distribution_type: (Nem kötelező) A táblázat elosztásának módja. A megengedett értékek hozzáfűzők vagy kivonatok, alapértelmezett "kivonat" értékkel.

colocate_with: (Nem kötelező) adja meg az aktuális táblát egy másik tábla helycsoportjában. Alapértelmezés szerint a táblák akkor lesznek együtt helyezve, ha azonos típusú oszlopok osztják el őket, azonos szegmensszámúak, és ugyanazzal a replikációs tényezővel rendelkeznek. A lehetséges értékek colocate_with a következők none default: új társhelycsoport indítása, vagy egy másik tábla neve, amelyet az adott táblával együtt szeretne áthelyezni. (Lásd a tábla áthelyezését.)

Ne feledje, hogy az implicit áthelyezés alapértelmezett értéke colocate_with nem. A közös elhelyezés nagyszerű dolog lehet, ha a táblák kapcsolódnak vagy csatlakoznak. Ha azonban két tábla nem kapcsolódik egymáshoz, de ugyanazt az adattípust használja a terjesztési oszlopaikhoz, a horizontális újraegyensúlyozás során a véletlenszerű elhelyezés csökkentheti a teljesítményt. A táblaszilánkok szükségtelenül egy "kaszkádban" lesznek áthelyezve.

Ha egy új elosztott tábla nem kapcsolódik más táblákhoz, célszerű megadni colocate_with => 'none'.

shard_count: (Nem kötelező) az új elosztott táblához létrehozandó szegmensek száma. Ha megadja, shard_count nem adhat meg egy másik értéket colocate_with sem. Egy meglévő tábla vagy helycsoport szegmensszámának módosításához használja a alter_distributed_table függvényt.

A lehetséges értékek shard_count 1 és 64000 között vannak. Az optimális érték kiválasztásával kapcsolatos útmutatásért tekintse meg a Szegmensek száma című témakört.

Visszaadott érték

n/a

Példa

Ez a példa arról tájékoztatja az adatbázist, hogy a github_events táblát a repo_id oszlop kivonatával kell elosztani.

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

Ez a függvény ugyanazzal a felülettel és céllal rendelkezik, mint a create_distributed_function, de nem blokkolja az írásokat a táblaterjesztés során.

create_distributed_table_concurrently Azonban van néhány korlátozás:

A függvény nem használható tranzakcióblokkokban, ami azt jelenti, hogy egyszerre csak egy táblát oszthat ki. (A függvényt azonban időparticionált táblákon is használhatja.)
Nem használható create_distributed_table_concurrently , ha a táblára idegen kulcs hivatkozik, vagy egy másik helyi táblára hivatkozik. A táblákra hivatkozó idegen kulcsok azonban működnek, és a táblaeloszlás befejeződése után más elosztott táblákhoz is létrehozhat idegen kulcsokat.
Ha nem rendelkezik elsődleges kulccsal vagy replika-identitással a táblán, akkor a frissítési és törlési parancsok a táblaterjesztés során meghiúsulnak a logikai replikáció korlátozásai miatt.

truncate_local_data_after_distributing_table

A tábla terjesztése után csonkíthatja az összes helyi sort, és megakadályozhatja, hogy a korlátozások elavult helyi rekordok miatt meghiúsuljanak. A csonkolás a kijelölt táblához idegen kulccsal rendelkező táblákra kaszkádolt. Ha a hivatkozó táblák nem oszlanak el egymástól, akkor a hivatkozási integritás védelme érdekében a csonkolás tilos:

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

A helyi koordinátor csomóponttábláinak adatainak csonkolása biztonságos az elosztott táblák számára, mivel a sorok , ha vannak ilyenek, át lesznek másolva a munkavégző csomópontokra a terjesztés során.

Argumentumok

table_name: Annak az elosztott táblának a neve, amelynek helyi megfelelője a koordinátorcsomóponton csonkolt.

Visszaadott érték

n/a

Példa

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

create_reference_table

A create_reference_table() függvény egy kis referencia- vagy dimenziótáblát határoz meg. Ez a függvény egy táblanevet vesz fel, és egyetlen szegmenst tartalmazó elosztott táblát hoz létre, amely minden munkavégző csomópontra replikálva van.

Argumentumok

table_name: Az elosztandó kis dimenzió vagy referenciatábla neve.

Visszaadott érték

n/a

Példa

Ez a példa tájékoztatja az adatbázist, hogy a nemzet táblát referenciatáblaként kell definiálni

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Hozzáad egy helyi Postgres-táblát a Citus metaadataihoz. A függvény egyik fő felhasználási esete, hogy a koordinátor helyi táblái elérhetővé válnak a fürt bármely csomópontjáról. A helyi táblához társított adatok a koordinátoron maradnak – csak a sémát és a metaadatokat küldi el a feldolgozóknak.

A helyi táblák metaadatokhoz való hozzáadása kis költséggel jár. A tábla hozzáadásakor a Citusnak nyomon kell követnie a partíciótáblában. A metaadatokhoz hozzáadott helyi táblák ugyanazokat a korlátozásokat öröklik, mint a referenciatáblák.

A tábla leválasztásakor a Citus eltávolítja az eredményül kapott helyi táblákat a metaadatokból, ami kiküszöböli az ilyen korlátozásokat ezeken a táblákon.

Argumentumok

table_name: A Citus metaadataihoz hozzáadni kívánt koordinátor táblájának neve.

cascade_via_foreign_keys: (Nem kötelező) Ha ez az argumentum "true" (igaz) értékre van állítva, citus_add_local_table_to_metadata automatikusan hozzáad más táblákat, amelyek idegenkulcs-kapcsolatban állnak az adott táblával. Ezzel a paraméterrel körültekintően járjon el, mert sok táblát érinthet.

Visszaadott érték

n/a

Példa

Ez a példa arról tájékoztatja az adatbázist, hogy a nemzettáblát koordinátor-helyi táblaként kell definiálni, amely bármely csomópontról elérhető:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

A alter_distributed_table() függvénnyel módosíthatja egy elosztott tábla terjesztési oszlopát, szegmensszámát vagy elhelyezési tulajdonságait.

Argumentumok

table_name: A módosítandó tábla neve.

distribution_column: (Nem kötelező) Az új terjesztési oszlop neve.

shard_count: (Nem kötelező) Az új szegmensek száma.

colocate_with: (Nem kötelező) Az a tábla, amellyel az aktuális elosztott tábla együtt lesz helyezve. A lehetséges értékek egy defaultnone új helycsoport elindításához vagy egy másik tábla nevéhez tartoznak, amellyel együtt kell helyezni. (Lásd a tábla áthelyezését.)

cascade_to_colocated: (Nem kötelező) Ha ez az argumentum "true" (igaz) értékre van állítva, shard_count és colocate_with a módosításokat az összes olyan táblára is alkalmazza a program, amelyek korábban a táblával együtt voltak helyezve, és a közös hely megmarad. Ha "false" (hamis) értékről van szó, a tábla aktuális áthelyezése megszakad.

Visszaadott érték

n/a

Példa

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

A update_distributed_table_colocation() függvénnyel frissíthetők az elosztott táblák. Ez a függvény egy elosztott tábla megosztott helyének megszakítására is használható. Az Azure Cosmos DB for PostgreSQL implicit módon két táblát fog egymás mellé helyezni, ha a terjesztési oszlop azonos típusú, ez akkor lehet hasznos, ha a táblák kapcsolódnak egymáshoz, és bizonyos illesztéseket hajtanak végre. Ha az A és a B tábla együtt van helyezve, és az A tábla újraegyensúlyozódik, a B tábla is újraegyensúlyozódik. Ha a B tábla nem rendelkezik replika-identitással, az újraegyensúlyozás sikertelen lesz. Ezért ez a függvény hasznos lehet az implicit kolocáció feltörése ebben az esetben.

Ez a függvény nem helyez át adatokat fizikailag.

Argumentumok

table_name: Annak a táblázatnak a neve, amelynek a helye frissül.

colocate_with: Az a táblázat, amellyel a táblázatot együtt kell helyezni.

Ha meg szeretné szakítani egy tábla áthelyezését, meg kell adnia colocate_with => 'none'.

Visszaadott érték

n/a

Példa

Ez a példa azt mutatja be, hogy az A tábla áthelyezése a B tábla helyeként frissül.

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

Tegyük fel, hogy az A és a B tábla együtt van helyezve (esetleg implicit módon), ha meg szeretné szakítani a közös elhelyezést:

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

Tegyük fel, hogy az A tábla, a B tábla, a C és a D tábla együtt van helyezve, és együtt szeretné áthelyezni az A és a B táblát, valamint a C és a D táblát:

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

Ha nincs nevű kivonatelosztott táblával rendelkezik, és frissíteni szeretné annak helyét, a következő műveleteket végezheti el:

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

undistribute_table

A undistribute_table() függvény visszavonja create_distributed_table vagy create_reference_table műveletét. A feloldás feloldása visszaviszi az összes adatot a szegmensekből egy helyi táblába a koordinátorcsomóponton (feltéve, hogy az adatok elférnek), majd törli a szegmenseket.

Az Azure Cosmos DB for PostgreSQL nem fogja elosztani az idegen kulcsokkal vagy hivatkozással rendelkező táblákat, kivéve, ha a cascade_via_foreign_keys argumentum értéke igaz. Ha ez az argumentum hamis (vagy nincs megadva), akkor a feloldás előtt manuálisan kell elvetnie a megsértő idegenkulcs-korlátozásokat.

Argumentumok

table_name: A felosztandó elosztott vagy hivatkozási tábla neve.

cascade_via_foreign_keys: (Nem kötelező) Ha ez az argumentum "true" (igaz) értékre van állítva, undistribute_table a table_name idegen kulcsokon keresztüli összes táblát is elosztja. Ezzel a paraméterrel körültekintően járjon el, mert sok táblát érinthet.

Visszaadott érték

n/a

Példa

Ez a példa elosztja a táblázatot github_events , majd visszavonja azt.

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

Propagálja a függvényt a koordinátor csomópontról a feldolgozókra, és megjelöli az elosztott végrehajtáshoz. Amikor egy elosztott függvényt hív meg a koordinátor, az Azure Cosmos DB for PostgreSQL a "terjesztési argumentum" értékével választ ki egy feldolgozó csomópontot a függvény futtatásához. A függvény feldolgozókon való végrehajtása növeli a párhuzamosságot, és közelebb hozhatja a kódot a szegmensekben lévő adatokhoz az alacsonyabb késés érdekében.

A Postgres keresési útvonala nem propagálható a koordinátortól a feldolgozókhoz az elosztott függvény végrehajtása során, ezért az elosztott függvénykódnak teljes mértékben meg kell jelölnie az adatbázis-objektumok nevét. A függvények által kibocsátott értesítések sem jelennek meg a felhasználó számára.

Argumentumok

function_name: Az elosztandó függvény neve. A névnek zárójelben kell tartalmaznia a függvény paramétertípusait, mert több függvénynek is ugyanaz a neve lehet a PostgreSQL-ben. Például 'foo(int)' eltér 'foo(int, text)'a .

distribution_arg_name: (Nem kötelező) Az argumentum neve, amellyel elosztható. A kényelem érdekében (vagy ha a függvényargumentumok nem rendelkeznek névvel), a helyőrzők használata engedélyezett, például '$1'. Ha ez a paraméter nincs megadva, akkor az általa function_name elnevezett függvény csak a feldolgozókon jön létre. Ha a jövőben feldolgozó csomópontokat adnak hozzá, a függvény automatikusan ott is létrejön.

colocate_with: (Nem kötelező) Ha az elosztott függvény egy elosztott táblába (vagy általánosabban a társhelycsoportba) ír, ügyeljen arra, hogy a paraméterrel nevezze el a colocate_with táblát. Ezután a függvény minden egyes meghívása a releváns szegmenseket tartalmazó feldolgozó csomóponton fog futni.

Visszaadott érték

n/a

Példa

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

A alter_columnar_table_set() függvény módosítja az oszlopos táblák beállításait. A függvény nem oszlopos táblán való meghívása hibát jelez. A táblanév kivételével minden argumentum megadása nem kötelező.

Az összes oszlopos tábla aktuális beállításainak megtekintéséhez tekintse meg ezt a táblázatot:

SELECT * FROM columnar.options;

Az újonnan létrehozott táblák oszlopos beállításainak alapértelmezett értékei felülírhatók az alábbi TARTOMÁNYVEZÉRLŐ-kkel:

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

Argumentumok

table_name: Az oszlopos tábla neve.

chunk_row_count: (Nem kötelező) Az újonnan beszúrt adatok adattömbönkénti sorainak maximális száma. A meglévő adattömbök nem módosulnak, és több sort tartalmazhatnak, mint ez a maximális érték. Az alapértelmezett érték 10000.

stripe_row_count: (Nem kötelező) Az újonnan beszúrt adatok sávonkénti sorainak maximális száma. A meglévő adatsávok nem változnak, és több sor is lehet, mint ez a maximális érték. Az alapértelmezett érték 150000.

tömörítés: (Nem kötelező) [none|pglz|zstd|lz4|lz4hc] Az újonnan beszúrt adatok tömörítési típusa. A meglévő adatok nem lesznek újrakomponálva vagy kibontva. Az alapértelmezett és javasolt érték a zstd (ha a támogatás be lett fordítva).

compression_level: (Nem kötelező) Az érvényes beállítások 1 és 19 közöttiek. Ha a tömörítési módszer nem támogatja a választott szintet, a legközelebbi szint lesz kiválasztva.

Visszaadott érték

n/a

Példa

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

alter_table_set_access_method

A alter_table_set_access_method() függvény megváltoztatja egy tábla hozzáférési módszerét (például halom vagy oszlop).

Argumentumok

table_name: Annak a táblának a neve, amelynek a hozzáférési módja megváltozik.

access_method: Az új hozzáférési módszer neve.

Visszaadott érték

n/a

Példa

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

create_time_partitions

A create_time_partitions() függvény egy adott intervallum partícióit hozza létre, hogy lefedje az adott időtartományt.

Argumentumok

table_name: (regclass) tábla, amelyhez új partíciókat szeretne létrehozni. A táblát egy oszlopban kell particionelni, dátum, időbélyeg vagy időbélyeg típusú.

partition_interval: az új partíciók tartományainak beállításakor használandó időintervallum, például '2 hours', vagy '1 month'.

end_at: (timestamptz) hozzon létre partíciókat eddig az időpontig. Az utolsó partíció tartalmazza a pont end_at, és a rendszer nem hoz létre újabb partíciókat.

start_from: (timestamptz, nem kötelező) válassza ki az első partíciót, hogy tartalmazza a pont start_from. Az alapértelmezett érték now().

Visszaadott érték

Igaz, ha új partíciók létrehozására van szükség, hamis, ha már léteztek.

Példa

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

A drop_old_time_partitions() függvény eltávolítja azokat a partíciókat, amelyek időközei egy adott időbélyeg előtt esnek. A függvény használata mellett megfontolhatja alter_old_partitions_set_access_method a régi partíciók oszlopos tárolóval való tömörítését is.

Argumentumok

table_name: (regclass) tábla, amelynek partícióit el szeretné távolítani. A táblát egy oszlopban kell particionelni, dátum, időbélyeg vagy időbélyeg típusú.

older_than: (timestamptz) olyan legördülő partíciók, amelyek felső tartománya kisebb vagy egyenlő older_than.

Visszaadott érték

n/a

Példa

-- drop partitions that are over a year old

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

alter_old_partitions_set_access_method

Az időbélyegek használata esetén a táblákat gyakran idő szerint particionáltuk, a régi partíciókat pedig írásvédett oszlopos tárolóba tömörítjük.

Argumentumok

parent_table_name: (regclass) tábla, amelynek partícióit módosítani szeretné. A táblát egy oszlopban kell particionelni, dátum, időbélyeg vagy időbélyeg típusú.

older_than: (timestamptz) olyan partíciók módosítása, amelyek felső tartománya kisebb vagy egyenlő older_than.

new_access_method: (név) soralapú tárolás esetén halom, oszlopos tárolás esetén oszlopos tárolás esetén.

Visszaadott érték

n/a

Példa

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

Metaadatok / Konfigurációs információk

get_shard_id_for_distribution_column

Az Azure Cosmos DB for PostgreSQL egy elosztott tábla minden sorát egy szegmenshez rendeli a sor terjesztési oszlopának és a tábla terjesztési módszerének értéke alapján. A legtöbb esetben a pontos leképezés egy alacsony szintű részlet, amelyet az adatbázis-rendszergazda figyelmen kívül hagyhat. Azonban hasznos lehet egy sor szegmensének meghatározása manuális adatbázis-karbantartási feladatokhoz vagy csak a kíváncsiság kielégítése érdekében. A get_shard_id_for_distribution_column függvény ezeket az információkat kivonatolt, tartományelosztott és referenciatáblákhoz biztosítja. Nem működik a hozzáfűző eloszláshoz.

Argumentumok

table_name: Az elosztott tábla.

distribution_value: A terjesztési oszlop értéke.

Visszaadott érték

Az Azure Cosmos DB for PostgreSQL szegmensazonosítója az adott tábla terjesztési oszlopértékéhez van társítva.

Példa

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

Lefordítja az partkey oszlopot pg_dist_partition egy szöveges oszlopnévre. A fordítás hasznos az elosztott tábla terjesztési oszlopának meghatározásához.

Részletesebb ismertetésért tekintse meg a terjesztési oszlop kiválasztását.

Argumentumok

table_name: Az elosztott tábla.

column_var_text: A tábla értéke partkey pg_dist_partition .

Visszaadott érték

A terjesztési oszlop neve table_name.

Példa

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

Hozam:

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

citus_relation_size

Kérje le a megadott elosztott tábla összes szegmense által használt lemezterületet. A lemezterület tartalmazza a "főág" méretét, de kizárja a láthatósági térképet és a szegmensek szabad területtérképét.

Argumentumok

logicalrelid: egy elosztott tábla neve.

Visszaadott érték

Méret bájtban nagy méretként.

Példa

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

Szerezze be a megadott elosztott tábla összes szegmense által használt lemezterületet, kivéve az indexeket (de beleértve a TOAST-ot, a szabad terület térképét és a láthatósági térképet).

Argumentumok

logicalrelid: egy elosztott tábla neve.

Visszaadott érték

Méret bájtban nagy méretként.

Példa

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

Szerezze be a megadott elosztott tábla összes szegmense által felhasznált lemezterületet, beleértve az összes indexet és a TOAST-adatot.

Argumentumok

logicalrelid: egy elosztott tábla neve.

Visszaadott érték

Méret bájtban nagy méretként.

Példa

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

Eltávolítja az összes sort a citus_stat_statements. Ez a függvény a függvénytől pg_stat_statements_reset()függetlenül működik. Az összes statisztika alaphelyzetbe állításához hívja meg mindkét függvényt.

Argumentumok

n/a

Visszaadott érték

Egyik sem

citus_get_active_worker_nodes

A citus_get_active_worker_nodes() függvény az aktív feldolgozó állomásneveinek és portszámainak listáját adja vissza.

Argumentumok

n/a

Visszaadott érték

Azon rekordok listája, ahol az egyes tuple-ok a következő információkat tartalmazzák:

node_name: A feldolgozó csomópont DNS-neve

node_port: Port azon a feldolgozó csomóponton, amelyen az adatbázis-kiszolgáló figyel

Példa

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

(3 rows)

Fürtkezelés és -javítás

master_copy_shard_placement

Ha egy szegmenselhelyezés nem frissíthető egy módosítási parancs vagy egy DDL-művelet során, akkor inaktívként lesz megjelölve. A master_copy_shard_placement függvény ezután meghívható egy inaktív szegmenselhelyezés helyreállításához egy kifogástalan elhelyezésből származó adatok használatával.

A szegmensek javításához a függvény először elveti a sérült szegmensek elhelyezését, majd újra létrehozza azt a koordinátor sémájával. A szegmenselhelyezés létrehozása után a függvény adatokat másol az kifogástalan elhelyezésből, és frissíti a metaadatokat, hogy az új szegmenselhelyezés kifogástalan állapotúként legyen megjelölve. Ez a függvény biztosítja, hogy a szegmens védve legyen a javítás során esetlegesen bekövetkező módosításoktól.

Argumentumok

shard_id: A javítandó szegmens azonosítója.

source_node_name: Annak a csomópontnak a DNS-neve, amelyen az kifogástalan szegmenselhelyezés található ("forrás" csomópont).

source_node_port: A forrásmunkacsomópont portja, amelyen az adatbázis-kiszolgáló figyel.

target_node_name: Annak a csomópontnak a DNS-neve, amelyen az érvénytelen szegmenselhelyezés található ("cél" csomópont).

target_node_port: A cél feldolgozó csomópont portja, amelyen az adatbázis-kiszolgáló figyel.

Visszaadott érték

n/a

Példa

Az alábbi példa az 12345-ös szegmens inaktív szegmenselhelyezését fogja javítani, amely az 5432-s porton futó "bad_host" adatbázis-kiszolgálón található. A javításhoz az 5432-s porton futó "good_host" kiszolgálón található, kifogástalan állapotú szegmenselhelyezésből származó adatokat fogja használni.

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

master_move_shard_placement

Ez a függvény áthelyez egy adott szegmenst (és a vele együtt áthelyezett szegmenseket) egyik csomópontról a másikra. Általában közvetetten használják a szegmensek újraelosztása során, nem pedig közvetlenül egy adatbázis-rendszergazda hívja meg.

Az adatok áthelyezésének két módja van: blokkolás vagy letiltás. A blokkolási módszer azt jelenti, hogy az áthelyezés során a szegmens összes módosítása szünetel. A második módszer, amely elkerüli a szegmensek írásának blokkolását, a Postgres 10 logikai replikációjára támaszkodik.

A sikeres áthelyezési művelet után a forráscsomópont szegmensei törlődnek. Ha az áthelyezés bármikor meghiúsul, ez a függvény hibát jelez, és változatlanul hagyja a forrás- és célcsomópontokat.

Argumentumok

shard_id: Az áthelyezendő szegmens azonosítója.

source_node_name: Annak a csomópontnak a DNS-neve, amelyen az kifogástalan szegmenselhelyezés található ("forrás" csomópont).

source_node_port: A forrásmunkacsomópont portja, amelyen az adatbázis-kiszolgáló figyel.

target_node_name: Annak a csomópontnak a DNS-neve, amelyen az érvénytelen szegmenselhelyezés található ("cél" csomópont).

target_node_port: A cél feldolgozó csomópont portja, amelyen az adatbázis-kiszolgáló figyel.

shard_transfer_mode: (Nem kötelező) Adja meg a replikáció módját, függetlenül attól, hogy a PostgreSQL logikai replikációt vagy a munkavégzők közötti MÁSOLÁS parancsot kívánja-e használni. A lehetséges értékek a következők:

auto: Szükség van replikaidentitásra, ha logikai replikáció lehetséges, ellenkező esetben használjon örökölt viselkedést (például szegmensjavításhoz, PostgreSQL 9.6). Ez az alapértelmezett érték.

force_logical: Akkor is használjon logikai replikációt, ha a tábla nem rendelkezik replika-identitással. A tábla egyidejű frissítési/törlési utasításai sikertelenek lesznek a replikáció során.

block_writes: Használja a COPY (blokkoló írások) parancsot az elsődleges kulcs- vagy replikaidentitást nem tartalmazó táblákhoz.

Visszaadott érték

n/a

Példa

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

rebalance_table_shards

A rebalance_table_shards() függvény az adott tábla szegmenseit mozgatja, hogy egyenletesen eloszthassa őket a feldolgozók között. A függvény először kiszámítja a szükséges áthelyezések listáját annak érdekében, hogy a fürt egyensúlyban legyen az adott küszöbértéken belül. Ezután egyenként áthelyezi a szegmenselhelyezéseket a forráscsomópontról a célcsomópontra, és frissíti a megfelelő szegmens metaadatait, hogy tükrözzék az áthelyezést.

Minden szegmenshez költség van hozzárendelve annak meghatározásakor, hogy a szegmensek "egyenlően elosztottak-e". Alapértelmezés szerint minden szegmensnek ugyanaz a költsége (értéke 1), ezért a költségnek a feldolgozók közötti kiegyenlítése megegyezik az egyes szegmensek számának kiegyenlítésével. Az állandó költségstratégiát "by_shard_count" néven nevezik, és ez az alapértelmezett újraegyensúlyozási stratégia.

A "by_shard_count" stratégia az alábbi körülmények között megfelelő:

A szegmensek nagyjából azonos méretűek
A szegmensek nagyjából ugyanannyi forgalmat kapnak
A feldolgozó csomópontok mérete és típusa megegyezik
A szegmenseket nem rögzítették bizonyos feldolgozókhoz

Ha ezek közül a feltételezések közül bármelyik nem áll meg, akkor a "by_shard_count" kiegyensúlyozása rossz tervet eredményezhet.

Az alapértelmezett újraelosztási stratégia a "by_disk_size". A paraméterrel mindig testre szabhatja a rebalance_strategy stratégiát.

A rebalance_table_shards futtatása előtt célszerű meghívni get_rebalance_table_shards_plan , hogy lássa és ellenőrizze a végrehajtandó műveleteket.

Argumentumok

table_name: (Nem kötelező) Annak a táblának a neve, amelynek szegmenseit újra ki kell egyensúlyba helyezni. Ha NULL, akkor az összes meglévő társhelycsoport újraegyensúlyozása.

küszöbérték: (Nem kötelező) 0,0 és 1,0 közötti lebegőpontos szám, amely a csomópont kihasználtságának az átlagos kihasználtságtól való maximális eltérését jelzi. A 0.1 megadása például azt eredményezi, hogy a szegmensek újraegyensúlyozója megkísérli kiegyensúlyozni az összes csomópontot, hogy azonos számú szegmenst ±10%. Pontosabban, a szegmens rebalancer megpróbálja konvergens kihasználtsága az összes feldolgozó csomópontok a (1 - küszöbérték) * average_utilization ... (1

küszöbérték) * average_utilization tartomány.

max_shard_moves: (Nem kötelező) Az áthelyezni kívánt szegmensek maximális száma.

excluded_shard_list: (Nem kötelező) Azon szegmensek azonosítója, amelyeket nem szabad áthelyezni az újraegyensúlyozási művelet során.

auto: Szükség van replikaidentitásra, ha logikai replikáció lehetséges, ellenkező esetben használjon örökölt viselkedést (például szegmensjavításhoz, PostgreSQL 9.6). Ez az alapértelmezett érték.

force_logical: Akkor is használjon logikai replikációt, ha a tábla nem rendelkezik replika-identitással. A tábla egyidejű frissítési/törlési utasításai sikertelenek lesznek a replikáció során.

block_writes: Használja a COPY (blokkoló írások) parancsot az elsődleges kulcs- vagy replikaidentitást nem tartalmazó táblákhoz.

drain_only: (Nem kötelező) Ha igaz, helyezze át a szegmenseket a pg_dist_node hamis értékre beállított munkavégző csomópontokrólshouldhaveshards; ne helyezzen át más szegmenseket.

rebalance_strategy: (Nem kötelező) egy stratégia neve a pg_dist_rebalance_strategy. Ha ezt az argumentumot nem adja meg, a függvény az alapértelmezett stratégiát választja a táblában leírtak szerint.

Visszaadott érték

n/a

Példa

Az alábbi példa megpróbálja újraegyensúlyozni a github_events tábla szegmenseit az alapértelmezett küszöbértéken belül.

SELECT rebalance_table_shards('github_events');

Ez a példahasználat megkísérli újraegyensúlyozni a github_events táblát az 1. és 2. azonosítójú szegmensek áthelyezése nélkül.

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

get_rebalance_table_shards_plan

A rebalance_table_shards tervezett szegmensmozgásainak kimenete anélkül, hogy végrehajtanák őket. Bár ez nem valószínű, get_rebalance_table_shards_plan egy kicsit más tervet tud kihozni, mint amit egy rebalance_table_shards hívás ugyanazokkal az argumentumokkal fog végrehajtani. A rendszer nem egyszerre hajtja végre őket, így a fürttel kapcsolatos tények – például a lemezterület – eltérhetnek a hívások között.

Argumentumok

Ugyanazok az argumentumok, mint rebalance_table_shards: reláció, küszöbérték, max_shard_moves, excluded_shard_list és drain_only. Az argumentumok jelentéséhez tekintse meg a függvény dokumentációját.

Visszaadott érték

Az alábbi oszlopokat tartalmazó csuplesek:

table_name: A táblázat, amelynek szegmensei áthelyeződnek
shardid: A kérdéses szegmens
shard_size: Méret bájtban
sourcename: A forráscsomópont állomásneve
sourceport: A forráscsomópont portja
célnév: A célcsomópont állomásneve
célport: A célcsomópont portja

get_rebalance_progress

A szegmensek újraegyensúlyozásának megkezdése után a get_rebalance_progress() függvény felsorolja az összes érintett szegmens előrehaladását. Figyeli a tervezett és végrehajtott rebalance_table_shards()lépéseket.

Argumentumok

n/a

Visszaadott érték

Az alábbi oszlopokat tartalmazó csuplesek:

sessionid: Az újraegyensúlyozási figyelő postgres PID-je
table_name: A táblázat, amelynek szegmensei mozognak
shardid: A kérdéses szegmens
shard_size: Méret bájtban
sourcename: A forráscsomópont állomásneve
sourceport: A forráscsomópont portja
célnév: A célcsomópont állomásneve
célport: A célcsomópont portja
előrehaladás: 0 = várakozás az áthelyezésre; 1 = áthelyezés; 2 = kész

Példa

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

Sor hozzáfűzése pg_dist_rebalance_strategy .

Argumentumok

Ezekről az argumentumokról további információt a megfelelő oszlopértékek között pg_dist_rebalance_strategytalál.

név: az új stratégia azonosítója

shard_cost_function: azonosítja az egyes szegmensek "költségének" meghatározásához használt függvényt

node_capacity_function: azonosítja a csomópont kapacitásának mérésére használt függvényt

shard_allowed_on_node_function: azonosítja azt a függvényt, amely meghatározza, hogy mely szegmensek helyezhetők el a csomópontokon

default_threshold: lebegőpontos küszöbérték, amely azt határozza meg, hogy az összesített szegmensköltséget pontosan kell-e kiegyensúlyozni a csomópontok között

minimum_threshold: (Nem kötelező) olyan védelmi oszlop, amely a rebalance_table_shards() küszöbértékargumentumában megengedett minimális értéket tartalmazza. Alapértelmezett értéke 0

Visszaadott érték

n/a

citus_set_default_rebalance_strategy

Frissítse a pg_dist_rebalance_strategy táblát, és módosítsa az argumentuma által elnevezett stratégiát úgy, hogy a szegmensek újraegyensúlyozásakor az alapértelmezett legyen.

Argumentumok

név: a stratégia neve a pg_dist_rebalance_strategy

Visszaadott érték

n/a

Példa

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

A citus_remote_connection_stats() függvény az egyes távoli csomópontokhoz való aktív kapcsolatok számát jeleníti meg.

Argumentumok

n/a

Példa

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

Ez a függvény létrehoz egy új szegmenst, amely egy adott egyetlen értékkel rendelkező sorokat tárol a terjesztési oszlopban. Különösen hasznos a több-bérlős használati esetnél, ahol egy nagy bérlő önállóan helyezhető el a saját szegmensén és végső soron saját fizikai csomópontján.

Argumentumok

table_name: A tábla neve egy új szegmens lekéréséhez.

tenant_id: Az új szegmenshez hozzárendelendő terjesztési oszlop értéke.

cascade_option: (Nem kötelező) Ha a "CASCADE" értékre van állítva, egy szegmenst is elkülönít az aktuális tábla helycsoportjának összes táblájától.

Visszaadott érték

shard_id: A függvény az újonnan létrehozott szegmenshez rendelt egyedi azonosítót adja vissza.

Példák

Hozzon létre egy új szegmenst a 135-ös bérlő vonalainak tárolásához:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Következő lépések

A cikk számos függvénye módosítja a rendszer metaadattábláját
A kiszolgálóparaméterek testre szabják egyes függvények viselkedését

Megosztás a következőn keresztül:

Azure Cosmos DB for PostgreSQL-függvények

Tábla és szegmens DDL

citus_schema_distribute

Argumentumok

Visszaadott érték

Példa

citus_schema_undistribute

Argumentumok

Visszaadott érték

Példa

create_distributed_table

Argumentumok

Visszaadott érték

Példa

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argumentumok

Visszaadott érték

Példa

create_reference_table

Argumentumok

Visszaadott érték

Példa

citus_add_local_table_to_metadata

Argumentumok

Visszaadott érték

Példa

alter_distributed_table

Argumentumok

Visszaadott érték

Példa

update_distributed_table_colocation

Argumentumok

Visszaadott érték

Példa

undistribute_table

Argumentumok

Visszaadott érték

Példa

create_distributed_function

Argumentumok

Visszaadott érték

Példa

alter_columnar_table_set

Argumentumok

Visszaadott érték

Példa

alter_table_set_access_method

Argumentumok

Visszaadott érték

Példa

create_time_partitions

Argumentumok

Visszaadott érték

Példa

drop_old_time_partitions

Argumentumok

Visszaadott érték

Példa

alter_old_partitions_set_access_method

Argumentumok

Visszaadott érték

Példa

Metaadatok / Konfigurációs információk

get_shard_id_for_distribution_column

Argumentumok

Visszaadott érték

Példa

column_to_column_name

Argumentumok

Visszaadott érték

Példa

citus_relation_size

Argumentumok

Visszaadott érték

Példa

citus_table_size

Argumentumok

Visszaadott érték