JSON-Arrays gezielt aktualisieren

Veröffentlicht am 18.10.2026 · Verfasst von Veysi Guenay

Wenn eine Anwendung einem JSON-Dokument einen Eintrag hinzufügen soll, wird häufig das ganze Dokument geladen, im Anwendungscode verändert und zurückgeschrieben. Oracle SQL bietet mit JSON_TRANSFORM eine Alternative: Die Datenbank führt gezielte Änderungen am Dokument aus. Der Operator APPEND hängt Werte an ein Array an – direkt innerhalb eines SQL-Updates.

1. Element an ein vorhandenes Array anhängen

Angenommen, eine Bestellzeile enthält ein Array ereignisse. Ein neues Ereignis lässt sich so ergänzen:

UPDATE bestellungen
SET dokument = json_transform(
  dokument,
  APPEND '$.ereignisse' = 'VERSANDT'
)
WHERE bestell_id = :bestell_id;

Der Wert wird am Ende des Arrays eingefügt. Mehrere Transformationen können in einem Aufruf aufeinander folgen; jede arbeitet auf dem Ergebnis der vorherigen. So lassen sich beispielsweise Status und Zeitstempel gemeinsam aktualisieren, ohne JSON-String-Verkettungen in PL/SQL oder der Anwendung zu bauen.

2. Fehlendes Feld und falscher JSON-Typ bewusst behandeln

Standardmäßig führt APPEND zu einem Fehler, wenn das Zielfeld fehlt oder kein Array ist. Das ist oft sinnvoll: Ein unerwartetes Schema soll nicht stillschweigend übergangen werden. Wenn ein fehlendes Feld fachlich als leeres Array behandelt werden darf, kann CREATE ON MISSING das Array beim Anhängen anlegen:

UPDATE bestellungen
SET dokument = json_transform(
  dokument,
  APPEND '$.ereignisse' = 'VERSANDT'
    CREATE ON MISSING
)
WHERE bestell_id = :bestell_id;

Für einen vorhandenen, aber falsch typisierten Wert gibt es separat ON MISMATCH-Handler. CREATE ON MISMATCH behandelt den bisherigen Wert als einzelnes Arrayelement. Das kann bei gemischten Altdaten hilfreich sein, verändert aber deren Struktur. Verwenden Sie es daher nur, wenn genau dieses Verhalten fachlich gewollt ist; andernfalls sollte der Fehler sichtbar bleiben und die Datenqualität bereinigt werden.

3. Idempotenz und parallele Änderungen berücksichtigen

APPEND hängt bei jedem erfolgreichen Aufruf einen weiteren Wert an. Wird ein Job nach einem Timeout erneut gestartet, kann derselbe Eintrag doppelt vorkommen. Wenn Wiederholungen möglich sind, speichern Sie eine eindeutige Ereignis-ID und prüfen Sie Duplikate gezielt oder verwenden Sie eine Mengenoperation wie ADD_SET, falls die Array-Semantik tatsächlich einer Menge entspricht.

Transformationen innerhalb eines einzelnen Aufrufs sind atomar: Scheitert eine Operation, werden die anderen Änderungen dieses Aufrufs ebenfalls nicht angewendet. Das ersetzt aber keine Transaktionsplanung über mehrere Tabellen oder Requests. Achten Sie auf eine präzise WHERE-Bedingung und testen Sie parallele Updates auf dieselbe Zeile.

4. Praxischeck für den Produktivbetrieb

1. JSON-Spalte, unterstütztes Datenbankrelease und gültige Dokumente im Zielbestand verifizieren.
2. Festlegen, ob fehlendes Feld und Typabweichung Fehler oder erlaubte Reparaturfälle sind.
3. Wiederholte Requests und doppelte Arraywerte berücksichtigen; gegebenenfalls Ereignis-IDs nutzen.
4. Änderung zunächst in einer Testumgebung mit repräsentativen Dokumentgrößen messen.
5. Betroffene Zeilen begrenzen und Transaktionsumfang sowie Fehlerbehandlung der Anwendung prüfen.

Fazit

JSON_TRANSFORM macht partielle JSON-Änderungen zu einer SQL-Aufgabe und hält die Mutation nah an den gespeicherten Daten. APPEND ist einfach, aber seine Handler definieren wichtige Datenqualitätsregeln. Wer fehlende Felder, falsche Typen und Retry-Verhalten bewusst behandelt, kann JSON-Dokumente gezielter und nachvollziehbarer pflegen.

Weiterführend: Oracles JSON Developer’s Guide zu JSON_TRANSFORM und die Referenz zum APPEND-Operator.