89 lines
3.2 KiB
Markdown
89 lines
3.2 KiB
Markdown
# Catalog schema snapshot RPC
|
|
|
|
Il percorso preferito per un binding `rest_api` espone al catalogo un'unica fotografia tipizzata
|
|
dello schema:
|
|
|
|
```http
|
|
POST /rpc/schema_snapshot
|
|
Content-Type: application/json
|
|
|
|
{"schema_name":"datawarehouse"}
|
|
```
|
|
|
|
La risposta è un oggetto JSON con `schemaVersion: 1`, capability esplicite e tre collezioni. Una
|
|
capability non disponibile deve essere dichiarata `unavailable`: non deve essere simulata con una
|
|
lista vuota.
|
|
|
|
```json
|
|
{
|
|
"schemaVersion": 1,
|
|
"capabilities": {
|
|
"tables": "available",
|
|
"columns": "available",
|
|
"relationships": "available"
|
|
},
|
|
"tables": [
|
|
{ "name": "patients", "sourceComment": "Clinical patients" }
|
|
],
|
|
"columns": [
|
|
{
|
|
"tableName": "patients",
|
|
"name": "id",
|
|
"ordinalPosition": 1,
|
|
"dataType": "bigint",
|
|
"isNullable": false,
|
|
"defaultExpression": null,
|
|
"primaryKeyPosition": 1,
|
|
"sourceComment": "Patient identifier"
|
|
}
|
|
],
|
|
"relationships": [
|
|
{
|
|
"constraintName": "visits_patient_id_fkey",
|
|
"sourceTableName": "visits",
|
|
"targetTableName": "patients",
|
|
"updateRule": "NO ACTION",
|
|
"deleteRule": "CASCADE",
|
|
"deferrable": false,
|
|
"initiallyDeferred": false,
|
|
"columns": [
|
|
{ "position": 1, "sourceColumnName": "patient_id", "targetColumnName": "id" }
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Fallback compatibile tramite `run_query`
|
|
|
|
Se e soltanto se il server non espone `POST /rpc/schema_snapshot`, il catalogo può ottenere la
|
|
stessa fotografia mediante una singola istruzione read-only inviata all'RPC già esistente:
|
|
|
|
```http
|
|
POST /rpc/run_query
|
|
Content-Type: application/json
|
|
|
|
{"query_text":"WITH ... SELECT ..."}
|
|
```
|
|
|
|
La query è costruita dal catalogo, interroga soltanto il catalogo PostgreSQL dello schema
|
|
configurato e aggrega tabelle, colonne, primary key e foreign key nella stessa istruzione. Non sono
|
|
ammessi più round trip, query per tabella o assemblaggi client-side di osservazioni effettuate in
|
|
momenti diversi. Il nome schema deve essere validato come identificatore e quotato come valore SQL,
|
|
non interpolato come SQL libero.
|
|
|
|
`run_query` restituisce un array JSON di righe. Per questo fallback l'array deve contenere
|
|
esattamente una riga e quella riga deve essere esattamente l'oggetto snapshot v1 sopra descritto,
|
|
con `schemaVersion`, `capabilities`, `tables`, `columns` e `relationships`; campi mancanti,
|
|
aggiuntivi o di tipo diverso rendono invalida l'intera fotografia. La risposta non è un contratto
|
|
alternativo o più permissivo: cambia soltanto il trasporto della stessa snapshot stretta.
|
|
|
|
`position` e `primaryKeyPosition` sono uno-based. Le coppie ordinate permettono foreign key
|
|
composte. Il catalogo rifiuta l'intera fotografia se il JSON non rispetta il contratto o se la
|
|
capability richiesta dal tipo di sincronizzazione è `unavailable`; in entrambi i casi non applica
|
|
alcuna modifica. Il fallback viene tentato soltanto quando l'RPC preferito risulta assente, non per
|
|
nascondere una snapshot malformata o un errore operativo del server. Se anche `run_query` non è
|
|
disponibile, la query viene rifiutata, la risposta non contiene una singola snapshot v1 valida o una
|
|
capability richiesta è `unavailable`, il run fallisce senza aggiornamenti parziali e senza esporre
|
|
il corpo remoto.
|