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