ThothII/docs/contracts/catalog-schema-snapshot.md

Catalog schema snapshot RPC

Il percorso preferito per un binding rest_api espone al catalogo un'unica fotografia tipizzata dello schema:

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.

{
  "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:

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.