4. Mai 2015

APEX_JSON ohne APEX: JSON erzeugen mit SQL und PL/SQL

Dieses Blog Posting dreht sich um ein PL/SQL-Paket, welches mit APEX 5.0 eingeführt wurde, welches aber auch für Nicht-APEX-Entwickler sehr interessant ist: APEX_JSON. Dieses Paket enthält JSON-Unterstützung für PL/SQL-Programmierer - JSON lässt sich damit sowohl parsen und auslesen als auch erzeugen. Erstellt man sich damit eigene Funktionen, so kommt die JSON-Unterstützung auch in die SQL-Welt. APEX_JSON ist zwar Teil von APEX 5.0 (und wird auch mit diesem zusammen installiert), die Nutzung erfolgt aber komplett losgelöst von APEX selbst; man kann es auch ohne APEX verwenden. Für den SQL und PL/SQL Entwickler bieten sich damit zwei Anwendungsfelder für APEX_JSON:
  • JSON kann nun auch in Datenbankversionen vor 12.1.0.2 geparst werden. Ab 12.1.0.2 empfehle ich aber dringend den Einsatz der nativen JSON-Unterstützung - die SQL/JSON-Funktionen wie JSON_VALUE, JSON_QUERY oder JSON_TABLE sind direkt im Datenbankkern implementiert und dürften damit effizienter sein, als eine PL/SQL-Lösung. Wer aber noch 11.2 oder 12.1.0.1 einsetzen muss, findet in APEX_JSON eine Alternative.
  • Das native Erzeugen von JSON mit SQL anhand von Tabellendaten geht auch mit 12.1.0.2 noch nicht; dieses Feature ist zwar geplant, aber eben noch nicht da. Hier kann APEX_JSON ebenfalls Abhilfe leisten.
In diesem Blog-Posting werde ich daher zeigen, wie man JSON mit APEX_JSON aus Tabellendaten generieren kann. Wie man JSON mit APEX_JSON ausliest, bleibt dem nächsten Posting vorbehalten. Wir starten (wie immer) einfach: Es soll ein JSON aus der wohlbekannten Tabelle EMP erzeugt werden. Für den Anfang reicht die Spalte ENAME. Der Code mit APEX_JSON sieht in etwa wie folgt aus.
declare
  l_json clob;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, 2);
  apex_json.open_object();
  apex_json.open_array('emp');
  for i in (select ename from emp) loop
    apex_json.open_object();
    apex_json.write('ename', i.ename);
    apex_json.close_object;
  end loop;
  apex_json.close_array;
  apex_json.close_object;
  dbms_output.put_line(apex_json.get_clob_output);
end;
Als Ergebnis kommt heraus ...
{
  "emp":[
    { "ename":"SMITH" }
   ,{ "ename":"ALLEN" }
   ,{ "ename":"WARD" }
   ,{ "ename":"JONES" }

:

   ,{ "ename":"FORD" }
   ,{ "ename":"MILLER" }
  ]
}
Zu Beginn wird mit INITIALIZE_CLOB_OUTPUT festlegt, dass das generierte JSON in einen CLOB geschrieben werden soll (alternative steht für den APEX-Entwickler der HTP-Buffer bereit). INITIALIZE_CLOB_OUTPUT nimmt drei Parameter entgegen. Die ersten beiden Parameter benötigt APEX_JSON zum Erzeugen des temporären CLOBs - sie werden analog zu DBMS_LOB.CREATETEMPORARY genutzt. Der dritte Parameter legt fest, welche Einrückung für die JSON-Hierarchie verwendet werden soll.
Natürlich kann man auch komplexere JSON-Hierarchien generieren; man muss die Aufrufe von OPEN_OBJECT und OPEN_ARRAY nur entsprechend schachteln. Das folgende PL/SQL generiert JSON mit einer Hierarchieebene für die Tabellen DEPT und EMP.
declare
  l_json clob;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, 2);
  apex_json.open_object();
  apex_json.open_array('dept');
  for i in (select * from dept) loop
    apex_json.open_object();
    apex_json.write('deptno', i.deptno);
    apex_json.write('dname',  i.dname);
    apex_json.open_array('emp');
    for e in (select * from emp where deptno = i.deptno) loop
      apex_json.open_object();
      apex_json.write('empno', e.empno);
      apex_json.write('ename', e.ename);
      apex_json.write('sal',   e.sal);
      apex_json.close_object;
    end loop;
    apex_json.close_array;
    apex_json.close_object;
  end loop;
  apex_json.close_array;
  apex_json.close_object;
  dbms_output.put_line(apex_json.get_clob_output);
end;
/

{
  "dept":[
    {
      "deptno":10
     ,"dname":"ACCOUNTING"
     ,"emp":[
        {
          "empno":7782
         ,"ename":"CLARK"
         ,"sal":2450
        }
       ,{
          "empno":7839
         ,"ename":"KING"

:

   ,{
      "deptno":40
     ,"dname":"OPERATIONS"
     ,"emp":[
      ]
    }
  ]
}
Achtet als Entwickler darauf, die OPEN_OBJECT und OPEN_ARRAY Aufrufe korrekt zu schachteln und mit CLOSE_OBJECT und CLOSE_ARRAY-Aufrufen zu schließen. APEX_JSON stellt das nicht sicher, wenn also ein CLOSE_OBJECT-Aufruf fehlt, bekommt Ihr eine ungültige JSON-Struktur. APEX_JSON bietet euch die Prozedur CLOSE_ALL an, die man am besten als letztes aufruft; diese schließt alle noch offenen Objekte und Arrays - und euer JSON ist syntaktisch korrekt.
Das bedeutet aber, dass die JSON-Hierarchie immer in einer PL/SQL-Prozedur oder einem anonymen Block "programmiert" werden muss. Die Frage ist, ob man da nicht etwas automatisieren kann - und in der Tat gibt es eine Variante von APEX_JSON.WRITE, die einen Cursor entgegennimmt. Die probieren wir gleich mal aus: Wir bauen eine SQL-Funktion, die einen beliebigen Cursor entgegennimmt und daraus JSON generiert.
create or replace function make_json(
  p_cursor in sys_refcursor,
  p_root   in varchar2 default 'query',
  p_indent in number default 2
) return clob 
is
  l_json   clob;
  l_cursor sys_refcursor := p_cursor;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, p_indent);
  apex_json.open_object();
  apex_json.write(p_root, l_cursor);
  apex_json.close_object;
  return apex_json.get_clob_output;
end make_json;
/
sho err
Verwendet wird die Funktion wie folgt ...
SQL select make_json(cursor(select * from emp)) as json_clob from dual;

JSON_CLOB
--------------------------------------------------------------------------------
{
  "query":  [
    {
      "EMPNO":7369
     ,"ENAME":"SMITH"
     ,"JOB":"CLERK"
     ,"MGR":7902
     ,"HIREDATE":"1980-12-17T00:00:00Z"
     ,"SAL":800
     ,"DEPTNO":20
    }
   ,{

:

     ,"SAL":1300
     ,"DEPTNO":10
    }
  ]
}
In diese Funktion könnt Ihr nun jede beliebige Query hineingeben; es wird immer ein JSON mit korrekten Attributnamen generiert. Allerdings ist die Struktur des generierten JSON - ebenso wie das Ergebnis einer SQL-Query - immer flach. Manchmal wird aber JSON mit Hierarchie gebraucht - muss man nun wieder programmieren ...?
Interessanterweise gibt es eine Version von APEX_JSON.WRITE, die einen XMLTYPE entgegennimmt. Ginge es nur darum, das XML so, wie es ist, ins JSON einzubauen, könnte man auch mit der APEX_JSON.WRITE-Variante arbeiten, die einen CLOB entgegennimmt. Wenn es aber eine eigene Variante für XMLTYPE gibt, muss mehr dahinterstecken. Probieren wir das mal aus, indem wir eine kleine Objektstruktur als XMLTYPE modellieren und daraus JSON erzeugen ...
declare
  l_json clob;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, 2);
  apex_json.open_object('xml');
  apex_json.write(xmltype(
'<r>
  <c1>Test</c1>
  <c2>Test2</c2>
  <c3>
    <object>
      <a1>A1</a1>
      <a2>A2</a2>
    </object>
  </c3>
</r>'));
  apex_json.close_object;
  dbms_output.put_line(apex_json.get_clob_output);
end;
/

"xml":{
  {"c1":"Test","c2":"Test2","c3":{"object":{"a1":"A1","a2":"A2"}}}
}
APEX_JSON interpretiert den XMLTYPE ganz offensichtlich - und versucht, die XML-Struktur in JSON nachzubilden. Das kann man sich für unsere obige Funktion MAKE_JSON zunutze machen. Angenommen, wir erstellen eine XML-View auf die Tabelle EMP (dazu kann man die seit langem verfügbaren SQL/XML Funktionen hernehmen) ...
create or replace view empxml as 
select 
  empno, 
  xmlelement(
    "EMP",
    xmlelement("ENAME", ename), 
    xmlelement("SAL", ename), 
    xmlelement("MGR_TO", (
      select 
        xmlagg(
          xmlelement("EMP", 
            xmlelement("ENAME", d.ename)
          )
        )
        from emp d 
        where d.mgr = e.empno
      )
    ) 
  ) as xml from emp e
/
Die View lässt sich ganz normal selektieren ...
SQL> select empno, xmlserialize(document xml indent size=2)  xml from empxml e;

     EMPNO XML
---------- ----------------------------------------
      7369 <EMP>
             <ENAME>SMITH</ENAME>
             <SAL>SMITH</SAL>
             <MGR_TO/>
           </EMP>

      7566 <EMP>
             <ENAME>JONES</ENAME>
             <SAL>JONES</SAL>
             <MGR_TO>
               <EMP>
                 <ENAME>SCOTT</ENAME>
               </EMP>
               <EMP>
                 <ENAME>FORD</ENAME>
               </EMP>
             </MGR_TO>
           </EMP>
Gibt man das SELECT auf diese View nun als Cursor in die MAKE_JSON-Funktion, so bekommen wir JSON mit Hierarchie - und das ohne die Hierarchie in PL/SQL explizit zu programmieren ...
SQL> select make_json(cursor(select empno, xml emp from empxml)) from dual;

MAKE_JSON(CURSOR(SELECTEMPNO,XMLEMPFROMEMPXML))
--------------------------------------------------------------------------------
{
  "query":  [
    {
      "EMPNO":7369
     ,"EMP":{"ENAME":"SMITH","SAL":"SMITH","MGR_TO":null}
    }
   ,{
      "EMPNO":7566
     ,"EMP":{"ENAME":"JONES","SAL":"JONES","MGR_TO":[{"ENAME":"SCOTT"},{"ENAME": "FORD"}]}
    }
:

}
Was die XML-Struktur angeht, ist APEX_JSON sehr empfindlich: Angenommen, es soll ein Array mit Objekten, die je mehrere Attribute haben, generiert werden. Dann sollte in der generierten XML-Struktur jedes Objekt nochmals von einem XML-Tag umgeben sein - ist das nicht der Fall, so generiert APEX_JSON unter Umständen eine andere Struktur. Hier muss man einfach ein wenig experimentieren.
Das mit APEX 5.0 eingeführte PL/SQL-Paket APEX_JSON eignet sich auch außerhalb von APEX sehr gut, um JSON aus SQL und PL/SQL heraus zu generieren. Die zu erzeugende JSON-Struktur kann mit PL/SQL-Aufrufen "programmiert" werden. Darüber hinaus bietet APEX_JSON die Möglichkeit an, JSON anhand eines Cursors zu erzeugen; alle Attributnamen werden dann aus den Tabellenspalten abgeleitet. Selektiert dieser Cursor XML-Dokumente als XMLTYPE, so leitet APEX_JSON die JSON-Strukturen aus dem XML ab - komplexe, hierarchische JSON-Strukturen lassen sich so auch ohne PL/SQL-Programmierung erzeugen: Es braucht nur eine generische SQL-Funktion, welche einen Cursor entgegennimmt und ein CLOB zurückliefert.
This Blog Posting is about a PL/SQL package, which has recently been introduced with APEX 5.0, and which is very interesting also for non-APEX Developers: APEX_JSON. This package is based upon the very popular PL/JSON package and provides PL/SQL support for parsing and generating JSON. By building own SQL functions, APEX_JSON functionality can be brought to the SQL layer as well (if you are interested in this, read on). SQL and PL/SQL developers can find two very nice use-cases for APEX_JSON - outside of APEX:
  • JSON can now be parsed also in pre-12.1.0.2 databases. In 12.1.0.2 and higher, I'd recommand to use the new native SQL/JSON functions. JSON_VALUE, JSON_QUERY or JSON_TABLE have been implemented at SQL level, within the database kernel, and should therefore be more efficient than a PL/SQL solution. But those who need to implement JSON parsing on 11.2 or 12.1.0.1, can now use APEX_JSON very nicely for their requirements.
  • Generating JSON from SQL query results or table data is still not possible with SQL alone - even with 12.1.0.2. Until this feature arrives, we can do this kind of work with APEX_JSON.
So, in this blog posting, I'll show how JSON can be generated from table data using APEX_JSON - but at the SQL and PL/SQL layer - without APEX. The next posting will then be about parsing JSON with APEX_JSON. Let's start easy (as always): We want to generate JSON from the well known table EMP and for this first example, the ENAME column is sufficient.
declare
  l_json clob;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, 2);
  apex_json.open_object();
  apex_json.open_array('emp');
  for i in (select ename from emp) loop
    apex_json.open_object();
    apex_json.write('ename', i.ename);
    apex_json.close_object;
  end loop;
  apex_json.close_array;
  apex_json.close_object;
  dbms_output.put_line(apex_json.get_clob_output);
end;
The result of this PL/SQL block is ...
{
  "emp":[
    { "ename":"SMITH" }
   ,{ "ename":"ALLEN" }
   ,{ "ename":"WARD" }
   ,{ "ename":"JONES" }

:

   ,{ "ename":"FORD" }
   ,{ "ename":"MILLER" }
  ]
}
At the beginning, we initialize the JSON generator with INITIALIZE_CLOB_OUTPUT. So, the JSON output will be written to a (temporary) CLOB. Within APEX, there is also the alternative to write the output to the HTP buffer. INITIALIZE_CLOB_OUTPUT takes three parameters. The first two are being used to construct the internal temporary LOB, usage is the same as in DBMS_LOB.CREATETEMPORARY. The third parameter determines the indentation for the JSON hierarchy.
Of course, APEX_JSON also allows to create more complex JSON hierarchies. It's all about the nesting of OPEN_OBJECT and OPEN_ARRAY calls. So, the following example generates "nested JSON" for the tables DEPT and EMP.
declare
  l_json clob;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, 2);
  apex_json.open_object();
  apex_json.open_array('dept');
  for i in (select * from dept) loop
    apex_json.open_object();
    apex_json.write('deptno', i.deptno);
    apex_json.write('dname',  i.dname);
    apex_json.open_array('emp');
    for e in (select * from emp where deptno = i.deptno) loop
      apex_json.open_object();
      apex_json.write('empno', e.empno);
      apex_json.write('ename', e.ename);
      apex_json.write('sal',   e.sal);
      apex_json.close_object;
    end loop;
    apex_json.close_array;
    apex_json.close_object;
  end loop;
  apex_json.close_array;
  apex_json.close_object;
  dbms_output.put_line(apex_json.get_clob_output);
end;
/

{
  "dept":[
    {
      "deptno":10
     ,"dname":"ACCOUNTING"
     ,"emp":[
        {
          "empno":7782
         ,"ename":"CLARK"
         ,"sal":2450
        }
       ,{
          "empno":7839
         ,"ename":"KING"

:

   ,{
      "deptno":40
     ,"dname":"OPERATIONS"
     ,"emp":[
      ]
    }
  ]
}
Note, that you as the developer are responsible for the correct nesting of your OPEN_OBJECT and OPEN_ARRAY calls and that you have to call CLOSE_OBJECT and CLOSE_ARRAY repectively. Opening an object or an array without closing it leads to a wrong or invalid JSON structure. APEX_JSON provides the CLOSE_ALL procedure, which is best being called at the end of your procedure; it will prevent generating JSON with objects unclosed.
It seems that the JSON hierarchy always has to be "coded" with PL/SQL calls in a procedure or an anonymous block. In practice, we often need something more "automagically": We want to provide a query - and the generator does the rest. For this purpose, one overloading of APEX_JSON.WRITE takes a cursor as parameter. Let's try this out: We build a generic SQL function, taking a Cursor as its parameter and generating JSON from that cursor with APEX_JSON.
create or replace function make_json(
  p_cursor in sys_refcursor,
  p_root   in varchar2 default 'query',
  p_indent in number default 2
) return clob 
is
  l_json   clob;
  l_cursor sys_refcursor := p_cursor;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, p_indent);
  apex_json.open_object();
  apex_json.write(p_root, l_cursor);
  apex_json.close_object;
  return apex_json.get_clob_output;
end make_json;
/
sho err
This function can be used as follows ...
SQL select make_json(cursor(select * from emp)) as json_clob from dual;

JSON_CLOB
--------------------------------------------------------------------------------
{
  "query":  [
    {
      "EMPNO":7369
     ,"ENAME":"SMITH"
     ,"JOB":"CLERK"
     ,"MGR":7902
     ,"HIREDATE":"1980-12-17T00:00:00Z"
     ,"SAL":800
     ,"DEPTNO":20
    }
   ,{

:

     ,"SAL":1300
     ,"DEPTNO":10
    }
  ]
}
Now we have a function which can take any SQL query to generate JSON from its results. And we can use this query in the SQL layer - no PL/SQL needed from here on. With this function you should be able to take out a large amount of PL/SQL "JSON generator" code. This function does it all.
The JSON structure coming out of this function will always be as flat as a SQL query result is. In some cases, more complex JSON with a hierarchy is needed - does that mean we have to write PL/SQL code again ...?
Interestingly, there is another overloading of APEX_JSON.WRITE. This one takes XMLTYPE as its parameter, and its purpose is not to simply embed XML to the JSON output (the CLOB variant does this). This function can do more - and to explore how it works, again, a simple example is needed: Let's model a simple object structure as XMLTYPE and pass this to APEX_JSON.WRITE.
declare
  l_json clob;
begin
  apex_json.initialize_clob_output(DBMS_LOB.CALL, true, 2);
  apex_json.open_object('xml');
  apex_json.write(xmltype(
'<r>
  <c1>Test</c1>
  <c2>Test2</c2>
  <c3>
    <object>
      <a1>A1</a1>
      <a2>A2</a2>
    </object>
  </c3>
</r>'));
  apex_json.close_object;
  dbms_output.put_line(apex_json.get_clob_output);
end;
/

"xml":{
  {"c1":"Test","c2":"Test2","c3":{"object":{"a1":"A1","a2":"A2"}}}
}
APEX_JSON examines the XMLTYPE and tries to rebuild the XML structure in the JSON output. We can use this for the above MAKE_JSON function - the cursor needs to select an XMLTYPE column, then. Thus, we now create a more complex XML structure for the data within the EMP table. We use the SQL/XML functions to generate XML and encapsulate the SQL query in a view.
create or replace view empxml as 
select 
  empno, 
  xmlelement(
    "EMP",
    xmlelement("ENAME", ename), 
    xmlelement("SAL", ename), 
    xmlelement("MGR_TO", (
      select 
        xmlagg(
          xmlelement("EMP", 
            xmlelement("ENAME", d.ename)
          )
        )
        from emp d 
        where d.mgr = e.empno
      )
    ) 
  ) as xml from emp e
/
The view can be selected ...
SQL> select empno, xmlserialize(document xml indent size=2)  xml from empxml e;

     EMPNO XML
---------- ----------------------------------------
      7369 <EMP>
             <ENAME>SMITH</ENAME>
             <SAL>SMITH</SAL>
             <MGR_TO/>
           </EMP>

      7566 <EMP>
             <ENAME>JONES</ENAME>
             <SAL>JONES</SAL>
             <MGR_TO>
               <EMP>
                 <ENAME>SCOTT</ENAME>
               </EMP>
               <EMP>
                 <ENAME>FORD</ENAME>
               </EMP>
             </MGR_TO>
           </EMP>
Passing this query to the MAKE_JSON function leads to a JSON result with a hierarchy according to the structure of the XMLTYPE column XML. We generated JSON with a hierarchy, but we did not hard-code it with PL/SQL calls.
SQL> select make_json(cursor(select empno, xml emp from empxml)) from dual;

MAKE_JSON(CURSOR(SELECTEMPNO,XMLEMPFROMEMPXML))
--------------------------------------------------------------------------------
{
  "query":  [
    {
      "EMPNO":7369
     ,"EMP":{"ENAME":"SMITH","SAL":"SMITH","MGR_TO":null}
    }
   ,{
      "EMPNO":7566
     ,"EMP":{"ENAME":"JONES","SAL":"JONES","MGR_TO":[{"ENAME":"SCOTT"},{"ENAME": "FORD"}]}
    }
:

}
APEX_JSON seems to be a but picky regarding the XML structure; for instance, objects with multiple attributes should be encapsulated with an XML tag; if this is missing, you'll not get the right JSON structure. You might need to experiment a bit ...
Summarized, I think that the new APEX_JSON package introduced with APEX 5.0, is very usable outside of APEX as well. The SQL and PL/SQL programmer finds a nice solution for their "Generating JSON" needs. The option to generate JSON from a cursor allows very generic solutions - one PL/SQL procedure is able to generate JSON from multiple tables - always with correct attributes. Bringing XMLTYPE into the game even allows generic solutions with complex hierarchys. A simple SQL function taking a cursor and returning a CLOB brings all this functionality to the SQL layer.

Kommentare:

chrisonoracle hat gesagt…

Hallo Carsten,

make_json ist eine sehr gute Idee!

Der Grund für write(XMLType) ist übrigens, daß es von write(sys_refcursor) intern verwendet wird, wenn die Query Objekt-Typen oder Cursor enthält. Dann läuft man nämlich mit reinem DBMS_SQL in Bugs bzw. Limitierungen rein. XMLType hat praktischerweise einen Constructor, der einen Cursor entgegennimmt. APEX_JSON erzeugt dann mit XSLT aus dem XMLType die JSON-Ausgabe.

LG,
Christian

Carsten Czarski hat gesagt…

Hi Christian,

beim Erstellen des Blog-Posting ist mir übrigens aufgefallen, dass beim WRITE mit einem XMLTYPE das Indent nicht berücksichtigt wird ... ist aber nicht besonders kritisch ...

Beste Grüße

Carsten

Beliebte Postings