Funzioni di Azure Cosmos DB per PostgreSQL

Articolo
09/29/2023

SI APPLICA A: Azure Cosmos DB per PostgreSQL (basato sull'estensione del database Citus in PostgreSQL)

Questa sezione contiene informazioni di riferimento per le funzioni definite dall'utente fornite da Azure Cosmos DB per PostgreSQL. Queste funzioni consentono di fornire funzionalità distribuite ad Azure Cosmos DB per PostgreSQL.

Nota

I cluster che eseguono versioni precedenti del motore Citus potrebbero non offrire tutte le funzioni elencate in questa pagina.

DDL tabella e partizione

citus_schema_distribute

Converte gli schemi regolari esistenti in schemi distribuiti. Gli schemi distribuiti vengono associati automaticamente con singoli gruppi di condivisione. Le tabelle create in tali schemi vengono convertite in tabelle distribuite con percorso condiviso senza una chiave di partizione. Il processo di distribuzione dello schema assegna automaticamente e lo sposta in un nodo esistente nel cluster.

Argomenti

schemaname: nome dello schema, che deve essere distribuito.

Valore restituito

N/D

Esempio

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

Per altri esempi, vedere procedure per la progettazione per i microservizi.

citus_schema_undistribute

Converte nuovamente uno schema distribuito esistente in uno schema normale. Il processo comporta lo spostamento delle tabelle e dei dati dal nodo corrente al nodo coordinatore nel cluster.

Argomenti

schemaname: nome dello schema, che deve essere distribuito.

Valore restituito

N/D

Esempio

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

Per altri esempi, vedere procedure per la progettazione per i microservizi.

create_distributed_table

La funzione create_distributed_table() viene usata per definire una tabella distribuita e crearne le partizioni se si tratta di una tabella con distribuzione hash. Questa funzione accetta un nome di tabella, la colonna di distribuzione e un metodo di distribuzione facoltativo e inserisce i metadati appropriati per contrassegnare la tabella come distribuita. Per impostazione predefinita, la funzione è la distribuzione 'hash' se non viene specificato alcun metodo di distribuzione. Se la tabella è distribuita tramite hash, la funzione crea anche partizioni di lavoro in base al numero di partizioni e ai valori di configurazione del fattore di replica partizione. Se la tabella contiene righe, vengono distribuite automaticamente ai nodi di lavoro.

Questa funzione sostituisce l'utilizzo di master_create_distributed_table() seguito da master_create_worker_shards().

Argomenti

table_name: nome della tabella da distribuire.

distribution_column: colonna in cui distribuire la tabella.

distribution_type: (facoltativo) Metodo in base al quale deve essere distribuita la tabella. I valori consentiti sono append o hash, con un valore predefinito "hash".

colocate_with: (facoltativo) includere la tabella corrente nel gruppo di condivisione di un'altra tabella. Per impostazione predefinita, le tabelle vengono raggruppate quando vengono distribuite da colonne dello stesso tipo, hanno lo stesso numero di partizioni e hanno lo stesso fattore di replica. I valori possibili per colocate_with sono default, none per avviare un nuovo gruppo di condivisione o il nome di un'altra tabella per la condivisione con tale tabella. Vedere colocation della tabella.

Tenere presente che il valore predefinito di colocate_with esegue la corilevazione implicita. La condivisione del percorso può essere un'ottima cosa quando le tabelle sono correlate o verranno unite in join. Tuttavia, quando due tabelle non sono correlate, ma si usa lo stesso tipo di dati per le colonne di distribuzione, l'individuazione accidentale di tali tabelle può ridurre le prestazioni durante il ribilanciamento delle partizioni. Le partizioni della tabella verranno spostate insieme inutilmente in una "cascata".

Se una nuova tabella distribuita non è correlata ad altre tabelle, è consigliabile specificare colocate_with => 'none'.

shard_count: (facoltativo) numero di partizioni da creare per la nuova tabella distribuita. Quando si specifica shard_count non è possibile specificare un valore diverso colocate_with da nessuno. Per modificare il numero di partizioni di una tabella o di un gruppo di condivisione esistente, usare la funzione alter_distributed_table .

I valori possibili per shard_count sono compresi tra 1 e 64000. Per indicazioni sulla scelta del valore ottimale, vedere Conteggio partizioni.

Valore restituito

N/D

Esempio

In questo esempio viene comunicato al database che la tabella github_events deve essere distribuita tramite hash nella colonna 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

Questa funzione ha la stessa interfaccia e lo stesso scopo di create_distributed_function, ma non blocca le scritture durante la distribuzione delle tabelle.

Tuttavia, create_distributed_table_concurrently presenta alcune limitazioni:

Non è possibile usare la funzione in un blocco di transazioni, il che significa che è possibile distribuire una sola tabella alla volta. È tuttavia possibile usare la funzione nelle tabelle partizionate in tempo.
Non è possibile usare create_distributed_table_concurrently quando la tabella fa riferimento a una chiave esterna o fa riferimento a un'altra tabella locale. Tuttavia, le chiavi esterne per fare riferimento alle tabelle funzionano ed è possibile creare chiavi esterne ad altre tabelle distribuite al termine della distribuzione delle tabelle.
Se non si ha una chiave primaria o un'identità di replica nella tabella, i comandi di aggiornamento ed eliminazione avranno esito negativo durante la distribuzione della tabella a causa delle limitazioni della replica logica.

truncate_local_data_after_distributing_table

Troncare tutte le righe locali dopo la distribuzione di una tabella e impedire che i vincoli non riescano a causa di record locali obsoleti. Il troncamento si propaga alle tabelle con una chiave esterna per la tabella designata. Se le tabelle di riferimento non sono distribuite, il troncamento non viene consentito fino a quando non sono, per proteggere l'integrità referenziale:

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

Il troncamento dei dati delle tabelle del nodo coordinatore locale è sicuro per le tabelle distribuite perché le relative righe, se presenti, vengono copiate nei nodi di lavoro durante la distribuzione.

Argomenti

table_name: nome della tabella distribuita la cui controparte locale nel nodo coordinatore deve essere troncata.

Valore restituito

N/D

Esempio

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

create_reference_table

La funzione create_reference_table() viene utilizzata per definire una tabella di riferimento o dimensione di piccole dimensioni. Questa funzione accetta un nome di tabella e crea una tabella distribuita con una sola partizione, replicata in ogni nodo di lavoro.

Argomenti

table_name: nome della piccola dimensione o della tabella di riferimento che deve essere distribuita.

Valore restituito

N/D

Esempio

Questo esempio informa il database che la tabella nazione deve essere definita come tabella di riferimento

SELECT create_reference_table('nation');

citus_add_local_table_to_metadata

Aggiunge una tabella Postgres locale nei metadati Citus. Un caso d'uso importante per questa funzione consiste nel rendere accessibili le tabelle locali nel coordinatore da qualsiasi nodo del cluster. I dati associati alla tabella locale rimangono sul coordinatore. Solo lo schema e i metadati vengono inviati ai ruoli di lavoro.

L'aggiunta di tabelle locali ai metadati comporta un costo leggero. Quando si aggiunge la tabella, Citus deve tenere traccia della tabella di partizione. Le tabelle locali aggiunte ai metadati ereditano le stesse limitazioni delle tabelle di riferimento.

Quando si annulla la distribuzione della tabella, Citus rimuove le tabelle locali risultanti dai metadati, eliminando tali limitazioni in tali tabelle.

Argomenti

table_name: nome della tabella nel coordinatore da aggiungere ai metadati Citus.

cascade_via_foreign_keys: (facoltativo) Quando questo argomento è impostato su "true", citus_add_local_table_to_metadata aggiunge automaticamente altre tabelle che si trovano in una relazione di chiave esterna con una tabella specificata in metadati. Prestare attenzione a questo parametro, perché può influire potenzialmente su molte tabelle.

Valore restituito

N/D

Esempio

Questo esempio informa il database che la tabella nazione deve essere definita come tabella locale coordinatore, accessibile da qualsiasi nodo:

SELECT citus_add_local_table_to_metadata('nation');

alter_distributed_table

La funzione alter_distributed_table() può essere usata per modificare la colonna di distribuzione, il numero di partizioni o le proprietà di condivisione di una tabella distribuita.

Argomenti

table_name: nome della tabella che verrà modificata.

distribution_column: (Facoltativo) Nome della nuova colonna di distribuzione.

shard_count: (facoltativo) Il nuovo numero di partizioni.

colocate_with: (facoltativo) Tabella con cui verrà inserita la tabella distribuita corrente. I valori possibili sono default, none per avviare un nuovo gruppo di condivisione o il nome di un'altra tabella con cui eseguire la colocazione. Vedere colocation della tabella.

cascade_to_colocated: (facoltativo) Quando questo argomento è impostato su "true" shard_count e colocate_with le modifiche verranno applicate anche a tutte le tabelle precedentemente raggruppate con la tabella e la condivisione della condivisione verrà mantenuta. Se è "false", la corilevazione corrente di questa tabella verrà interrotta.

Valore restituito

N/D

Esempio

-- change distribution column
SELECT alter_distributed_table('github_events', distribution_column:='event_id');

-- change shard count of all tables in colocation group
SELECT alter_distributed_table('github_events', shard_count:=6, cascade_to_colocated:=true);

-- change colocation
SELECT alter_distributed_table('github_events', colocate_with:='another_table');

update_distributed_table_colocation

La funzione update_distributed_table_colocation() viene usata per aggiornare la corilevazione di una tabella distribuita. Questa funzione può essere usata anche per interrompere la corilevazione di una tabella distribuita. Azure Cosmos DB per PostgreSQL unisce in modo implicito due tabelle se la colonna di distribuzione è lo stesso tipo, può essere utile se le tabelle sono correlate e eseguiranno alcuni join. Se le tabelle A e B sono raggruppate e la tabella A viene ribilanciata, anche la tabella B verrà ribilanciata. Se la tabella B non ha un'identità di replica, il ribilanciamento avrà esito negativo. Pertanto, questa funzione può essere utile interrompendo la corilevazione implicita in questo caso.

Questa funzione non sposta fisicamente i dati.

Argomenti

table_name: nome della condivisione della tabella di cui verrà aggiornata.

colocate_with: tabella con cui deve essere inserita la tabella.

Se si desidera interrompere la corilevazione di una tabella, è necessario specificare colocate_with => 'none'.

Valore restituito

N/D

Esempio

Questo esempio mostra che la condivisione della tabella A viene aggiornata come condivisione della tabella B.

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

Si supponga che la tabella A e la tabella B siano collegate in modo implicito(possibilmente implicito), se si vuole interrompere la condivisione:

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

Si supponga ora che la tabella A, la tabella B, la tabella C e la tabella D siano raggruppate e si vuole raggruppare la tabella A e la tabella B e la tabella C e la tabella D:

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

Se si dispone di una tabella distribuita hash denominata none e si vuole aggiornarne la condivisione, è possibile eseguire le operazioni seguenti:

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

undistribute_table

La funzione undistribute_table() annulla l'azione di create_distributed_table o create_reference_table. Undistributing sposta tutti i dati dalle partizioni in una tabella locale nel nodo coordinatore (presupponendo che i dati possano essere inseriti), quindi elimina le partizioni.

Azure Cosmos DB per PostgreSQL non annulla la distribuzione delle tabelle a cui fanno riferimento chiavi esterne, a meno che l'argomento cascade_via_foreign_keys non sia impostato su true. Se questo argomento è false (o omesso), è necessario eliminare manualmente i vincoli di chiave esterna che causano errori prima di annullare la distribuzione.

Argomenti

table_name: nome della tabella distribuita o di riferimento da annullare.

cascade_via_foreign_keys: (facoltativo) Quando questo argomento è impostato su "true", undistribute_table annulla anche l'distribuzione di tutte le tabelle correlate a table_name tramite chiavi esterne. Prestare attenzione a questo parametro, perché può influire potenzialmente su molte tabelle.

Valore restituito

N/D

Esempio

In questo esempio viene distribuita una github_events tabella e quindi annullata la distribuzione.

-- first distribute the table
SELECT create_distributed_table('github_events', 'repo_id');

-- undo that and make it local again
SELECT undistribute_table('github_events');

create_distributed_function

Propaga una funzione dal nodo coordinatore ai ruoli di lavoro e la contrassegna per l'esecuzione distribuita. Quando viene chiamata una funzione distribuita nel coordinatore, Azure Cosmos DB per PostgreSQL usa il valore di "argomento di distribuzione" per selezionare un nodo di lavoro per eseguire la funzione. L'esecuzione della funzione sui ruoli di lavoro aumenta il parallelismo e può avvicinare il codice ai dati nelle partizioni per ridurre la latenza.

Il percorso di ricerca Postgres non viene propagato dal coordinatore ai ruoli di lavoro durante l'esecuzione della funzione distribuita, quindi il codice della funzione distribuita deve qualificare completamente i nomi degli oggetti di database. Inoltre, gli avvisi generati dalle funzioni non verranno visualizzati all'utente.

Argomenti

function_name: nome della funzione da distribuire. Il nome deve includere i tipi di parametro della funzione tra parentesi, perché più funzioni possono avere lo stesso nome in PostgreSQL. Ad esempio, 'foo(int)' è diverso da 'foo(int, text)'.

distribution_arg_name: (facoltativo) Nome dell'argomento da distribuire. Per praticità (o se gli argomenti della funzione non hanno nomi), è consentito un segnaposto posizionale, ad esempio '$1'. Se questo parametro non viene specificato, la funzione denominata da function_name viene semplicemente creata nei ruoli di lavoro. Se i nodi di lavoro vengono aggiunti in futuro, anche la funzione verrà creata automaticamente.

colocate_with: (facoltativo) Quando la funzione distribuita legge o scrive in una tabella distribuita (o, più in generale, un gruppo di condivisione), assicurarsi di denominare tale tabella usando il colocate_with parametro . Ogni chiamata della funzione verrà quindi eseguita nel nodo di lavoro contenente partizioni pertinenti.

Valore restituito

N/D

Esempio

-- an example function which updates a hypothetical
-- event_responses table which itself is distributed by event_id
CREATE OR REPLACE FUNCTION
  register_for_event(p_event_id int, p_user_id int)
RETURNS void LANGUAGE plpgsql AS $fn$
BEGIN
  INSERT INTO event_responses VALUES ($1, $2, 'yes')
  ON CONFLICT (event_id, user_id)
  DO UPDATE SET response = EXCLUDED.response;
END;
$fn$;

-- distribute the function to workers, using the p_event_id argument
-- to determine which shard each invocation affects, and explicitly
-- colocating with event_responses which the function updates
SELECT create_distributed_function(
  'register_for_event(int, int)', 'p_event_id',
  colocate_with := 'event_responses'
);

alter_columnar_table_set

La funzione alter_columnar_table_set() modifica le impostazioni in una tabella a colonne. La chiamata a questa funzione in una tabella non a colonne restituisce un errore. Tutti gli argomenti ad eccezione del nome della tabella sono facoltativi.

Per visualizzare le opzioni correnti per tutte le tabelle a colonne, vedere questa tabella:

SELECT * FROM columnar.options;

I valori predefiniti per le impostazioni a colonne per le tabelle appena create possono essere sottoposti a override con queste schede di interfaccia utente:

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

Argomenti

table_name: nome della tabella a colonne.

chunk_row_count: (facoltativo) Numero massimo di righe per blocco per i dati appena inseriti. I blocchi esistenti di dati non verranno modificati e potrebbero avere più righe di questo valore massimo. Il valore predefinito è 10000.

stripe_row_count: (facoltativo) Numero massimo di righe per striping per i dati appena inseriti. Le strisce esistenti di dati non verranno modificate e potrebbero avere più righe di questo valore massimo. Il valore predefinito è 150000.

compression: (Facoltativo) [none|pglz|zstd|lz4|lz4hc] Tipo di compressione per i dati appena inseriti. I dati esistenti non verranno ricompressi o decompressi. Il valore predefinito e suggerito è zstd (se il supporto è stato compilato in).

compression_level: (Facoltativo) Le impostazioni valide sono da 1 a 19. Se il metodo di compressione non supporta il livello scelto, verrà selezionato il livello più vicino.

Valore restituito

N/D

Esempio

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

alter_table_set_access_method

La funzione alter_table_set_access_method() modifica il metodo di accesso di una tabella, ad esempio heap o columnar.

Argomenti

table_name: nome della tabella il cui metodo di accesso cambierà.

access_method: nome del nuovo metodo di accesso.

Valore restituito

N/D

Esempio

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

create_time_partitions

La funzione create_time_partitions() crea partizioni di un determinato intervallo per coprire un determinato intervallo di tempo.

Argomenti

table_name: (regclass) tabella per cui creare nuove partizioni. La tabella deve essere partizionata in una colonna, di tipo data, timestamp o timestamptz.

partition_interval: intervallo di tempo, ad esempio '2 hours', o '1 month', da usare quando si impostano intervalli in nuove partizioni.

end_at: (timestamptz) creare partizioni fino a questo momento. L'ultima partizione conterrà il punto end_at e non verranno create partizioni successive.

start_from: (timestamptz, facoltativo) selezionare la prima partizione in modo che contenga il punto start_from. Il valore predefinito è now().

Valore restituito

True se è necessario creare nuove partizioni, false se sono già presenti.

Esempio

-- create a year's worth of monthly partitions
-- in table foo, starting from the current time

SELECT create_time_partitions(
  table_name         := 'foo',
  partition_interval := '1 month',
  end_at             := now() + '12 months'
);

drop_old_time_partitions

La funzione drop_old_time_partitions() rimuove tutte le partizioni i cui intervalli rientrano prima di un determinato timestamp. Oltre a usare questa funzione, è possibile prendere in considerazione alter_old_partitions_set_access_method per comprimere le partizioni precedenti con l'archiviazione a colonne.

Argomenti

table_name: (regclass) tabella per cui rimuovere le partizioni. La tabella deve essere partizionata in una colonna, di tipo data, timestamp o timestamptz.

older_than: (timestamptz) eliminare le partizioni il cui intervallo superiore è minore o uguale a older_than.

Valore restituito

N/D

Esempio

-- 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 un caso d'uso timeeries, le tabelle vengono spesso partizionate in base al tempo e le partizioni precedenti vengono compresse in una risorsa di archiviazione a colonne di sola lettura.

Argomenti

parent_table_name: (regclass) tabella per cui modificare le partizioni. La tabella deve essere partizionata in una colonna, di tipo data, timestamp o timestamptz.

older_than: (timestamptz) modificare le partizioni il cui intervallo superiore è minore o uguale a older_than.

new_access_method: (nome) 'heap' per l'archiviazione basata su righe o 'columnar' per l'archiviazione a colonne.

Valore restituito

N/D

Esempio

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

Metadati/Informazioni di configurazione

get_shard_id_for_distribution_column

Azure Cosmos DB per PostgreSQL assegna ogni riga di una tabella distribuita a una partizione in base al valore della colonna di distribuzione della riga e al metodo di distribuzione della tabella. Nella maggior parte dei casi, il mapping preciso è un dettaglio di basso livello che l'amministratore del database può ignorare. Tuttavia, può essere utile determinare la partizione di una riga, per le attività di manutenzione manuale del database o solo per soddisfare curiosità. La get_shard_id_for_distribution_column funzione fornisce queste informazioni per le tabelle di riferimento, distribuite a intervalli e distribuite con hash. Non funziona per la distribuzione di accodamento.

Argomenti

table_name: tabella distribuita.

distribution_value: valore della colonna di distribuzione.

Valore restituito

L'ID partizione Azure Cosmos DB per PostgreSQL viene associato al valore della colonna di distribuzione per la tabella specificata.

Esempio

SELECT get_shard_id_for_distribution_column('my_table', 4);

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

column_to_column_name

Converte la partkey colonna di in un nome di pg_dist_partition colonna testuale. La traduzione è utile per determinare la colonna di distribuzione di una tabella distribuita.

Per una discussione più dettagliata, vedere Scelta di una colonna di distribuzione.

Argomenti

table_name: tabella distribuita.

column_var_text: valore di partkey nella pg_dist_partition tabella.

Valore restituito

Nome della colonna di table_namedistribuzione.

Esempio

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

Output:

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

citus_relation_size

Ottenere lo spazio su disco usato da tutte le partizioni della tabella distribuita specificata. Lo spazio su disco include le dimensioni della "fork principale", ma esclude la mappa di visibilità e la mappa spazio disponibile per le partizioni.

Argomenti

logicalrelid: nome di una tabella distribuita.

Valore restituito

Dimensioni in byte come bigint.

Esempio

SELECT pg_size_pretty(citus_relation_size('github_events'));

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

citus_table_size

Ottiene lo spazio su disco usato da tutte le partizioni della tabella distribuita specificata, esclusi gli indici (ma inclusi TOAST, mappa spazio disponibile e mappa di visibilità).

Argomenti

logicalrelid: nome di una tabella distribuita.

Valore restituito

Dimensioni in byte come bigint.

Esempio

SELECT pg_size_pretty(citus_table_size('github_events'));

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

citus_total_relation_size

Ottiene lo spazio su disco totale usato da tutte le partizioni della tabella distribuita specificata, inclusi tutti gli indici e i dati TOAST.

Argomenti

logicalrelid: nome di una tabella distribuita.

Valore restituito

Dimensioni in byte come bigint.

Esempio

SELECT pg_size_pretty(citus_total_relation_size('github_events'));

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

citus_stat_statements_reset

Rimuove tutte le righe dalla citus_stat_statements. Questa funzione funziona in modo indipendente da pg_stat_statements_reset(). Per reimpostare tutte le statistiche, chiamare entrambe le funzioni.

Argomenti

N/D

Valore restituito

None

citus_get_active_worker_nodes

La funzione citus_get_active_worker_nodes() restituisce un elenco di nomi host di lavoro attivi e numeri di porta.

Argomenti

N/D

Valore restituito

Elenco di tuple in cui ogni tupla contiene le informazioni seguenti:

node_name: nome DNS del nodo di lavoro

node_port: porta sul nodo di lavoro in cui il server di database è in ascolto

Esempio

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

(3 rows)

Gestione e ripristino del cluster

master_copy_shard_placement

Se non è possibile aggiornare un posizionamento di partizioni durante un comando di modifica o un'operazione DDL, viene contrassegnato come inattivo. La funzione master_copy_shard_placement può quindi essere chiamata per ripristinare una posizione di partizione inattiva usando i dati di un posizionamento integro.

Per ripristinare una partizione, la funzione elimina prima di tutto il posizionamento della partizione non integra e la ricrea usando lo schema nel coordinatore. Dopo aver creato il posizionamento della partizione, la funzione copia i dati dal posizionamento integro e aggiorna i metadati per contrassegnare il posizionamento della nuova partizione come integro. Questa funzione garantisce che la partizione venga protetta da eventuali modifiche simultanee durante il ripristino.

Argomenti

shard_id: ID della partizione da ripristinare.

source_node_name: nome DNS del nodo in cui è presente il posizionamento della partizione integra ("nodo di origine").

source_node_port: porta nel nodo del ruolo di lavoro di origine in cui il server di database è in ascolto.

target_node_name: nome DNS del nodo in cui è presente il posizionamento di partizioni non valido ("nodo di destinazione").

target_node_port: porta nel nodo del ruolo di lavoro di destinazione in cui il server di database è in ascolto.

Valore restituito

N/D

Esempio

L'esempio seguente consente di ripristinare una posizione di partizione inattiva della partizione 12345, presente nel server di database in esecuzione su 'bad_host' sulla porta 5432. Per ripristinarlo, userà i dati di un posizionamento partizioni integro presente nel server in esecuzione su "good_host" sulla porta 5432.

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

master_move_shard_placement

Questa funzione sposta una determinata partizione (e le partizioni con cui si è posizionato) da un nodo a un altro. Viene in genere usato indirettamente durante il ribilanciamento delle partizioni anziché essere chiamato direttamente da un amministratore di database.

Esistono due modi per spostare i dati: blocco o non blocco. L'approccio di blocco indica che durante lo spostamento di tutte le modifiche alla partizione vengono sospese. Il secondo modo, che evita il blocco delle scritture di partizioni, si basa sulla replica logica di Postgres 10.

Dopo un'operazione di spostamento riuscita, le partizioni nel nodo di origine vengono eliminate. Se lo spostamento ha esito negativo in qualsiasi punto, questa funzione genera un errore e lascia invariati i nodi di origine e di destinazione.

Argomenti

shard_id: ID della partizione da spostare.

source_node_name: nome DNS del nodo in cui è presente il posizionamento della partizione integra ("nodo di origine").

source_node_port: porta nel nodo del ruolo di lavoro di origine in cui il server di database è in ascolto.

target_node_name: nome DNS del nodo in cui è presente il posizionamento di partizioni non valido ("nodo di destinazione").

target_node_port: porta nel nodo del ruolo di lavoro di destinazione in cui il server di database è in ascolto.

shard_transfer_mode: (facoltativo) Specificare il metodo di replica, se usare la replica logica PostgreSQL o un comando COPY tra ruoli di lavoro. I valori possibili sono:

auto: richiedere l'identità di replica se è possibile eseguire la replica logica, altrimenti usare il comportamento legacy , ad esempio per il ripristino della partizione, PostgreSQL 9.6. Questo è il valore predefinito.

force_logical: usare la replica logica anche se la tabella non ha un'identità di replica. Tutte le istruzioni di aggiornamento/eliminazione simultanee alla tabella avranno esito negativo durante la replica.

block_writes: usare COPY (scritture bloccanti) per le tabelle che non contengono la chiave primaria o l'identità di replica.

Valore restituito

N/D

Esempio

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

rebalance_table_shards

La funzione rebalance_table_shards() sposta le partizioni della tabella specificata per distribuirle uniformemente tra i ruoli di lavoro. La funzione calcola innanzitutto l'elenco di spostamenti che deve eseguire per assicurarsi che il cluster sia bilanciato entro la soglia specificata. Sposta quindi i posizionamenti delle partizioni uno per uno dal nodo di origine al nodo di destinazione e aggiorna i metadati della partizione corrispondenti in modo da riflettere lo spostamento.

A ogni partizione viene assegnato un costo quando si determina se le partizioni sono "distribuite in modo uniforme". Per impostazione predefinita, ogni partizione ha lo stesso costo (valore 1), quindi la distribuzione per equalizzare il costo tra i ruoli di lavoro è uguale a quella di equalizzare il numero di partizioni in ogni partizione. La strategia di costo costante è denominata "by_shard_count" ed è la strategia di ribilanciamento predefinita.

La strategia "by_shard_count" è appropriata in queste circostanze:

Le partizioni sono approssimativamente le stesse dimensioni
Le partizioni ottengono approssimativamente la stessa quantità di traffico
I nodi di lavoro hanno tutte le stesse dimensioni/tipo
Le partizioni non sono state aggiunte a determinati ruoli di lavoro

Se uno di questi presupposti non si tiene, il ribilanciamento "by_shard_count" può comportare un piano non valido.

La strategia di ribilanciamento predefinita è "by_disk_size". È sempre possibile personalizzare la strategia usando il rebalance_strategy parametro .

È consigliabile chiamare get_rebalance_table_shards_plan prima di eseguire rebalance_table_shards, per visualizzare e verificare le azioni da eseguire.

Argomenti

table_name: (facoltativo) Nome della tabella le cui partizioni devono essere ribilanciate. Se NULL, ribilanciare tutti i gruppi di condivisione esistenti.

threshold: (Facoltativo) Numero float compreso tra 0,0 e 1,0 che indica il rapporto massimo di differenza tra l'utilizzo medio dei nodi. Se ad esempio si specifica 0,1, il ribilanciamento della partizione tenterà di bilanciare tutti i nodi in modo che contengano lo stesso numero di partizioni ±10%. In particolare, il ribilanciatore di partizioni tenterà di convergere l'utilizzo di tutti i nodi di lavoro alla (1 - soglia) * average_utilization ... (1

threshold) * intervallo di average_utilization.

max_shard_moves: (facoltativo) Numero massimo di partizioni da spostare.

excluded_shard_list: (facoltativo) Identificatori di partizioni che non devono essere spostati durante l'operazione di ribilanciamento.

shard_transfer_mode: (facoltativo) Specificare il metodo di replica, se usare la replica logica PostgreSQL o un comando COPY tra ruoli di lavoro. I valori possibili sono:

auto: richiedere l'identità di replica se è possibile eseguire la replica logica, altrimenti usare il comportamento legacy , ad esempio per il ripristino della partizione, PostgreSQL 9.6. Questo è il valore predefinito.

force_logical: usare la replica logica anche se la tabella non ha un'identità di replica. Tutte le istruzioni di aggiornamento/eliminazione simultanee alla tabella avranno esito negativo durante la replica.

block_writes: usare COPY (scritture bloccanti) per le tabelle che non contengono la chiave primaria o l'identità di replica.

drain_only: (facoltativo) Se true, spostare le partizioni dai nodi di lavoro che hanno shouldhaveshards impostato su false in pg_dist_node; non spostare altre partizioni.

rebalance_strategy: (facoltativo) il nome di una strategia in pg_dist_rebalance_strategy. Se questo argomento viene omesso, la funzione sceglie la strategia predefinita, come indicato nella tabella.

Valore restituito

N/D

Esempio

L'esempio seguente tenterà di ribilanciare le partizioni della tabella github_events entro la soglia predefinita.

SELECT rebalance_table_shards('github_events');

Questo esempio di utilizzo tenterà di ribilanciare la tabella github_events senza spostare partizioni con ID 1 e 2.

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

get_rebalance_table_shards_plan

Restituisce gli spostamenti di partizioni pianificati di rebalance_table_shards senza eseguirli. Sebbene sia improbabile, get_rebalance_table_shards_plan può restituire un piano leggermente diverso da quello che verrà eseguita da una chiamata rebalance_table_shards con gli stessi argomenti. Non vengono eseguite contemporaneamente, quindi i fatti relativi al cluster, ad esempio lo spazio su disco, possono essere diversi tra le chiamate.

Argomenti

Gli stessi argomenti di rebalance_table_shards: relazione, soglia, max_shard_moves, excluded_shard_list e drain_only. Vedere la documentazione di tale funzione per il significato degli argomenti.

Valore restituito

Tuple contenenti queste colonne:

table_name: tabella le cui partizioni si spostano
shardid: la partizione in questione
shard_size: dimensioni in byte
sourcename: nome host del nodo di origine
sourceport: porta del nodo di origine
targetname: nome host del nodo di destinazione
targetport: porta del nodo di destinazione

get_rebalance_progress

Una volta avviato un ribilanciamento della partizione, la get_rebalance_progress() funzione elenca lo stato di avanzamento di ogni partizione interessata. Monitora gli spostamenti pianificati ed eseguiti da rebalance_table_shards().

Argomenti

N/D

Valore restituito

Tuple contenenti queste colonne:

sessionid: PID Postgres del monitor di ribilanciamento
table_name: tabella le cui partizioni vengono spostate
shardid: la partizione in questione
shard_size: dimensioni in byte
sourcename: nome host del nodo di origine
sourceport: porta del nodo di origine
targetname: nome host del nodo di destinazione
targetport: porta del nodo di destinazione
progress: 0 = in attesa di spostamento; 1 = spostamento; 2 = completato

Esempio

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

Aggiungere una riga a pg_dist_rebalance_strategy .

Argomenti

Per altre informazioni su questi argomenti, vedere i valori di colonna corrispondenti in pg_dist_rebalance_strategy.

name: identificatore per la nuova strategia

shard_cost_function: identifica la funzione usata per determinare il "costo" di ogni partizione

node_capacity_function: identifica la funzione per misurare la capacità del nodo

shard_allowed_on_node_function: identifica la funzione che determina quali partizioni possono essere posizionate nei nodi

default_threshold: una soglia a virgola mobile che ottimizza il modo in cui il costo cumulativo della partizione deve essere bilanciato tra i nodi

minimum_threshold: (facoltativo) una colonna di protezione che contiene il valore minimo consentito per l'argomento soglia di rebalance_table_shards(). Il valore predefinito è 0

Valore restituito

N/D

citus_set_default_rebalance_strategy

Aggiornare la tabella pg_dist_rebalance_strategy , modificando la strategia denominata dal relativo argomento in modo che sia l'impostazione predefinita scelta quando si ribilanciano le partizioni.

Argomenti

name: nome della strategia in pg_dist_rebalance_strategy

Valore restituito

N/D

Esempio

SELECT citus_set_default_rebalance_strategy('by_disk_size');

citus_remote_connection_stats

La funzione citus_remote_connection_stats() mostra il numero di connessioni attive a ogni nodo remoto.

Argomenti

N/D

Esempio

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

Questa funzione crea una nuova partizione per contenere righe con un singolo valore specifico nella colonna di distribuzione. È particolarmente utile per il caso d'uso multi-tenant, in cui un tenant di grandi dimensioni può essere posizionato da solo nella propria partizione e infine nel proprio nodo fisico.

Argomenti

table_name: nome della tabella per ottenere una nuova partizione.

tenant_id: valore della colonna di distribuzione che verrà assegnata alla nuova partizione.

cascade_option: (facoltativo) Se impostato su "CASCADE", isola anche una partizione da tutte le tabelle del gruppo di condivisione della tabella corrente.

Valore restituito

shard_id: la funzione restituisce l'ID univoco assegnato alla partizione appena creata.

Esempi

Creare una nuova partizione per contenere gli elementi riga per il tenant 135:

SELECT isolate_tenant_to_new_shard('lineitem', 135);

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

Passaggi successivi

Molte delle funzioni di questo articolo modificano le tabelle dei metadati di sistema
I parametri del server personalizzano il comportamento di alcune funzioni

Share via

Funzioni di Azure Cosmos DB per PostgreSQL

DDL tabella e partizione

citus_schema_distribute

Argomenti

Valore restituito

Esempio

citus_schema_undistribute

Argomenti

Valore restituito

Esempio

create_distributed_table

Argomenti

Valore restituito

Esempio

create_distributed_table_concurrently

truncate_local_data_after_distributing_table

Argomenti

Valore restituito

Esempio

create_reference_table

Argomenti

Valore restituito

Esempio

citus_add_local_table_to_metadata

Argomenti

Valore restituito

Esempio

alter_distributed_table

Argomenti

Valore restituito

Esempio

update_distributed_table_colocation

Argomenti

Valore restituito

Esempio

undistribute_table

Argomenti

Valore restituito

Esempio

create_distributed_function

Argomenti

Valore restituito

Esempio

alter_columnar_table_set

Argomenti

Valore restituito

Esempio

alter_table_set_access_method

Argomenti

Valore restituito

Esempio

create_time_partitions

Argomenti

Valore restituito

Esempio

drop_old_time_partitions

Argomenti

Valore restituito

Esempio

alter_old_partitions_set_access_method

Argomenti

Valore restituito

Esempio

Metadati/Informazioni di configurazione

get_shard_id_for_distribution_column

Argomenti

Valore restituito

Esempio

column_to_column_name

Argomenti

Valore restituito

Esempio

citus_relation_size

Argomenti

Valore restituito

Esempio

citus_table_size

Argomenti

Valore restituito