xmlcomment(text)
      

La fonction xmlcomment crée une valeur XML contenant un commentaire XML avec, comme contenu, le texte indiqué. Le texte ne peut pas contenir « -- » ou se terminer par un « - », de sorte que la construction résultante représente un commentaire XML valide. Si l'argument est NULL, le résultat est NULL.

Exemple :

SELECT xmlcomment('bonjour');

  xmlcomment
--------------
 <!--bonjour-->
       

 xmlconcat(xml[, ...])
     

La fonction xmlconcat concatène une liste de valeurs XML individuelles pour créer une valeur simple contenant un fragment de contenu XML. Les valeurs NULL sont omises ; le résultat est NULL seulement s'il n'y a pas d'arguments non NULL.

Exemple :

SELECT xmlconcat('<abc/>', '<bar>foo</bar>');

      xmlconcat
----------------------
 <abc/><bar>foo</bar>

Les déclarations XML, si elles sont présentes, sont combinées comme suit. Si toutes les valeurs en argument ont la même déclaration de version XML, cette version est utilisée dans le résultat. Sinon aucune version n'est utilisée. Si toutes les valeurs en argument ont la valeur de déclaration « standalone » à « yes », alors cette valeur est utilisée dans le résultat. Si toutes les valeurs en argument ont une valeur de déclaration « standalone » et qu'au moins l'une d'entre elles est « no », alors cette valeur est utilisée dans le résultat. Sinon le résultat n'a aucune déclaration « standalone ». Si le résultat nécessite une déclaration « standalone » sans déclaration de version, une déclaration de version 1.0 est utilisée, car le standard XML impose qu'une déclaration XML contienne une déclaration de version. Les déclarations d'encodage sont ignorées et supprimées dans tous les cas.

Exemple :

SELECT xmlconcat('<?xml version="1.1"?><foo/>', '<?xml version="1.1" standalone="no"?><bar/>');

             xmlconcat
-----------------------------------
 <?xml version="1.1"?><foo/><bar/>

 xmlelement(name nom [, xmlattributes(valeur [AS nom_attribut] [, ... ])] [, contenu, ...])
      

L'expression xmlelement produit un élément XML avec le nom, les attributs et le contenu donnés.

Exemples :

SELECT xmlelement(name foo);

 xmlelement
------------
 <foo/>

SELECT xmlelement(name foo, xmlattributes('xyz' as bar));

    xmlelement
------------------
 <foo bar="xyz"/>

SELECT xmlelement(name foo, xmlattributes(current_date as bar), 'cont', 'ent');

             xmlelement
-------------------------------------
 <foo bar="2007-01-26">content</foo>

Les noms d'élément et d'attribut qui ne sont pas des noms XML valides sont modifiés en remplaçant les caractères indésirables par une séquence _xHHHH_, où HHHH est le codage Unicode du caractère en notation hexadécimal. Par exemple :

SELECT xmlelement(name "foo$bar", xmlattributes('xyz' as "a&b"));

            xmlelement
----------------------------------
 <foo_x0024_bar a_x0026_b="xyz"/>

Un nom explicite d'attribut n'a pas besoin d'être indiqué si la valeur de l'attribut est la référence d'une colonne, auquel cas le nom de la colonne est utilisé comme nom de l'attribut par défaut. Dans tous les autres cas, l'attribut doit avoir un nom explicite. Donc, cet exemple est valide :

CREATE TABLE test (a xml, b xml);
SELECT xmlelement(name test, xmlattributes(a, b)) FROM test;
       

Mais ceux-ci ne le sont pas :

SELECT xmlelement(name test, xmlattributes('constant'), a, b) FROM test;
SELECT xmlelement(name test, xmlattributes(func(a, b))) FROM test;
       

Si le contenu de l'élément est précisé, il est formaté en fonction du type de données. Si le contenu est lui-même de type xml, des documents XML complexes peuvent être construits. Par exemple :

SELECT xmlelement(name foo, xmlattributes('xyz' as bar),
                            xmlelement(name abc),
                            xmlcomment('test'),
                            xmlelement(name xyz));

                  xmlelement
----------------------------------------------
 <foo bar="xyz"><abc/><!--test--><xyz/></foo>
      

Le contenu des autres types est formaté avec des données XML valides. Cela signifie en particulier que les caractères <, >, et & sont convertis en entités. Les données binaires (type bytea) sont représentées dans un encodage base64 ou hexadécimal, suivant la configuration du paramètre xmlbinary. Le comportement particulier pour les types de données individuels devrait évoluer pour aligner PostgreSQL avec les correspondances indiquées dans SQL:2006 et ultérieurs, comme discuté dans Section D.3.1.3.

 xmlforest(contenu [AS nom] [, ...])
    

L'expression xmlforest produit un arbre XML (autrement dit une séquence) d'éléments utilisant les noms et le contenu donnés.

Exemples :

SELECT xmlforest('abc' AS foo, 123 AS bar);

          xmlforest
------------------------------
 <foo>abc</foo><bar>123</bar>


SELECT xmlforest(table_name, column_name)
FROM information_schema.columns
WHERE table_schema = 'pg_catalog';

                                         xmlforest
-------------------------------------------------------------------------------------------
 <table_name>pg_authid</table_name><column_name>rolname</column_name>
 <table_name>pg_authid</table_name><column_name>rolsuper</column_name>
 ...

Comme indiqué dans le second exemple, le nom de l'élément peut être omis si la valeur du contenu est une référence de colonne, auquel cas le nom de la colonne est utilisé par défaut. Sinon, un nom doit être indiqué.

Les noms d'éléments qui ne sont pas des noms XML valides sont échappés comme indiqué pour xmlelement ci-dessus. De façon similaire, les données de contenu sont échappées pour rendre le contenu XML valide, sauf s'il est déjà de type xml.

Les arbres XML ne sont pas des documents XML valides s'ils sont constitués de plus d'un élément. Il peut donc s'avérer utile d'emballer les expressions xmlforest dans xmlelement.

 xmlpi(name target [, content])
     

L'expression xmlpi crée une instruction de traitement XML. Le contenu, si présent, ne doit pas contenir la séquence de caractères ?>.

Exemple :

SELECT xmlpi(name php, 'echo "hello world";');

            xmlpi
-----------------------------
 <?php echo "hello world";?>

 xmlroot(xml, version text | no value [, standalone yes|no|no value])
      

L'expression xmlroot modifie les propriétés du nœud racine d'une valeur XML. Si une version est indiquée, elle remplace la valeur dans la déclaration de version du nœud racine. Si un paramètre « standalone » est spécifié, il remplace la valeur dans la déclaration « standalone » du nœud racine.

SELECT xmlroot(xmlparse(document '<?xml version="1.1"?><content>abc</content>'),
               version '1.0', standalone yes);

                xmlroot
----------------------------------------
 <?xml version="1.0" standalone="yes"?>
 <content>abc</content>

xmlagg(xml)
       

La fonction xmlagg est, à la différence des fonctions décrites ici, une fonction d'agrégat. Elle concatène les valeurs en entrée pour les passer en argument à la fonction d'agrégat, comme le fait la fonction xmlconcat, sauf que la concaténation survient entre les lignes plutôt qu'entre les expressions d'une même ligne. Voir Section 9.20 pour plus d'informations sur les fonctions d'agrégat.

Exemple :

CREATE TABLE test (y int, x xml);
INSERT INTO test VALUES (1, '<foo>abc</foo>');
INSERT INTO test VALUES (2, '<bar/>');
SELECT xmlagg(x) FROM test;
        xmlagg
----------------------
 <foo>abc</foo><bar/>

Pour déterminer l'ordre de la concaténation, une clause ORDER BY peut être ajoutée à l'appel de l'agrégat comme décrit dans Section 4.2.7. Par exemple :

SELECT xmlagg(x ORDER BY y DESC) FROM test;
        xmlagg
----------------------
 <bar/><foo>abc</foo>

L'approche non standard suivante était recommandée dans les versions précédentes et peut toujours être utile dans certains cas particuliers :

SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab;
        xmlagg
----------------------
 <bar/><foo>abc</foo>

xml IS DOCUMENT
        

L'expression IS DOCUMENT renvoie true si la valeur de l'argument XML est un document XML correct, false dans le cas contraire (c'est-à-dire qu'il s'agit d'un fragment de document) ou NULL si l'argument est NULL. Voir la Section 8.13 pour les différences entre documents et fragments de contenu.

             xml IS NOT DOCUMENT
        

L'expression IS NOT DOCUMENT renvoie false si la valeur XML est un document XML propre, true s'il ne l'est pas (ie, c'est un fragment de document) et NULL si l'argument est NULL.

XMLEXISTS(text PASSING [BY { REF | VALUE }] xml [BY { REF | VALUE }])
        

La fonction xmlexists évalue une expression XPath 1.0 (le premier argument), avec la valeur XML fournie comme élément de contexte. La fonction renvoie false si le résultat de cette évaluation renvoie un ensemble vide, true si elle renvoie toute autre valeur. La fonction renvoie NULL si un des arguments est NULL. Une valeur non NULL fournie comme élément de contexte doit être un document XML, et non pas un fragment de contenu ou toute valeur qui n'est pas du XML.

Exemple :

SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY VALUE '<towns><town>Toronto</town><town>Ottawa</town></towns>');

 xmlexists
------------
 t
(1 row)

Les clauses BY REF et BY VALUE sont acceptées par PostgreSQL, mais elles sont ignorées, comme discuté dans Section D.3.2. Dans le standard SQL, la fonction xmlexists évalue une expression dans le langage XML Query, mais PostgreSQL autorise seulement une expression XPath 1.0, comme discuté dans Section D.3.1.

xml_is_well_formed(text)
xml_is_well_formed_document(text)
xml_is_well_formed_content(text)
         

Ces fonctions vérifient si la chaîne text est du XML bien formé et renvoient un résultat booléen. xml_is_well_formed_document vérifie si le document est bien formé alors que xml_is_well_formed_content vérifie si le contenu est bien formé. xml_is_well_formed est équivalent à xml_is_well_formed_document si le paramètre de configuration xmloption vaut DOCUMENT et est équivalent à xml_is_well_formed_content si le paramètre vaut CONTENT. Cela signifie que xml_is_well_formed est utile pour savoir si une conversion au type xml va réussir, alors que les deux autres sont utiles pour savoir si les variantes correspondantes de XMLPARSE vont réussir.

Exemples :

SET xmloption TO DOCUMENT;
SELECT xml_is_well_formed('<>');
 xml_is_well_formed
--------------------
 f
(1 row)

SELECT xml_is_well_formed('<abc/>');
 xml_is_well_formed
--------------------
 t
(1 row)

SET xmloption TO CONTENT;
SELECT xml_is_well_formed('abc');
 xml_is_well_formed
--------------------
 t
(1 row)

SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuff">bar</pg:foo>');
 xml_is_well_formed_document
-----------------------------
 t
(1 row)

SELECT xml_is_well_formed_document('<pg:foo xmlns:pg="http://postgresql.org/stuff">bar</my:foo>');
 xml_is_well_formed_document
-----------------------------
 f
(1 row)

Le dernier exemple montre que les vérifications incluent les correspondances d'espace de noms.

xpath(xpath, xml [, nsarray])
          

La fonction xpath évalue l'expression XPath 1.0 xpath (une valeur de type text) avec la valeur XML xml. Elle renvoie un tableau de valeurs XML correspondant à l'ensemble de nœuds produits par une expression XPath. Si l'expression XPath renvoie une valeur scalaire à la place d'un ensemble de nœuds, un tableau à un seul élément est renvoyé.

Le deuxième argument doit être un document XML bien formé. En particulier, il doit avoir un seul élément de nœud racine.

Le troisième argument (optionnel) de la fonction est un tableau de correspondances de namespace. Ce tableau text doit avoir deux dimensions dont la seconde a une longueur 2 (en fait, c'est un tableau de tableaux à exactement deux éléments). Le premier élément de chaque entrée du tableau est le nom du namespace (alias), le second étant l'URI du namespace. Il n'est pas requis que les alias fournis dans ce tableau soient les mêmes que ceux utilisés dans le document XML (autrement dit, que ce soit dans le contexte du document XML ou dans celui de la fonction xpath, les alias ont une vue locale).

Exemple :

SELECT xpath('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',
             ARRAY[ARRAY['my', 'http://example.com']]);

 xpath
--------
 {test}
(1 row)

Pour gérer des namespaces par défaut (anonymes), faites ainsi :

SELECT xpath('//mydefns:b/text()', '<a xmlns="http://example.com"><b>test</b></a>',
             ARRAY[ARRAY['mydefns', 'http://example.com']]);

 xpath
--------
 {test}
(1 row)

xpath_exists(xpath, xml [, nsarray])
           

La fonction xpath_exists est une forme spécialisée de la fonction xpath. Au lieu de renvoyer les valeurs XML individuelles qui satisfont l'expression XPath 1.0, cette fonction renvoie un booléen indiquant si la requête a été satisfaite ou non (spécifiquement, si elle a produit une valeur autre qu'un ensemble de nœuds non vide). Cette fonction est équivalente au prédicat XMLEXISTS, sauf qu'elle fonctionne aussi avec un argument de correspondance d'espace de nom.

Exemple :

SELECT xpath_exists('/my:a/text()', '<my:a xmlns:my="http://example.com">test</my:a>',
                     ARRAY[ARRAY['my', 'http://example.com']]);

 xpath_exists
--------------
 t
(1 row)

xmltable( [XMLNAMESPACES(namespace uri AS namespace name[, ...]), ]
          row_expression PASSING [BY { REF | VALUE }] document_expression [BY { REF | VALUE }]
          COLUMNS name { type [PATH column_expression] [DEFAULT default_expression] [NOT NULL | NULL]
                        | FOR ORDINALITY }
                   [, ...]
)
            

La fonction xmltable produit une table basée sur la valeur XML donnée, un filtre XPath pour extraire les lignes, ainsi qu'un ensemble de définitions de colonnes.

La clause facultative XMLNAMESPACES est une liste d'espaces de noms séparés par des virgules. Elle spécifie les espaces de noms utilisés dans le document et leurs alias. Une spécification d'espace de noms par défaut n'est pour le moment pas supportée.

L'argument row_expression requis est une expression XPath 1.0 qui est évaluée en passant document_expression comme élément de contexte pour obtenir un ensemble de nœuds XML. Ces nœuds sont ce que xmltable transforme en lignes de sortie. Aucune ligne ne sera produite si document_expression est NULL et si row_expression fournit un ensemble de nœuds vide ou toute autre valeur qu'un ensemble de nœuds.

document_expression fournit l'élément de contexte pour row_expression. Ce doit être un document XML bien formé ; les fragments/forêts ne sont pas acceptés. Les clauses BY REF et BY VALUE sont acceptées mais ignorées, comme indiqué dans Section D.3.2. Dans le standard SQL, la fonction xmltable évalue les expressions dans le langage XML Query, mais PostgreSQL autorise aussi les expressions XPath 1.0 comme indiqué dans Section D.3.1.

La clause obligatoire COLUMNS spécifie la liste de colonnes dans la table renvoyée. Chaque entrée décrit une colonne seule. Voir le résumé de la syntaxe ci-dessus pour le format. Le nom et le type sont obligatoires ; le chemin, valeur par défaut et la possibilité d'être NULL sont facultatifs.

Une colonne marquée FOR ORDINALITY sera remplie de numéros de ligne, en commençant à 1, dans l'ordre des nœuds retrouvés à partir de l'ensemble de nœuds résultats de row_expression. Pas plus d'une colonne ne peut être marquée comme FOR ORDINALITY.

Le paramètre column_expression pour une colonne est une expression XPath 1.0 qui est évaluée pour chaque ligne, avec le nœud courant provenant du résultat de row_expression comme son élément de contexte. Si aucune column_expression n'est fournie, alors le nom de colonne est utilisé comme un chemin implicite.

Si l'expression XPath d'une colonne renvoie une valeur qui n'est pas du XML (limitée à une chaîne, un booléen ou un nombre à virgule flottante en XPath 1.0) et que la colonne est d'un type PostgreSQL autre que xml, la colonne sera configurée comme si on lui affectait la représentation en chaîne de caractères de la valeur pour le type PostgreSQL. (Si la valeur est un booléen, sa représentation textuelle est supposée être 1 ou 0 si la catégorie type de la colonne en sortie est numérique et true ou false sinon.)

Si l'expression XPath d'une colonne renvoie un ensemble non vide de nœuds XML et que le type PostgreSQL de la colonne est xml, la colonne se verra affecter le résultat exact de l'expression, qu'elle soit de forme document ou contenu. ^[8]

Un résultat non-XML affecté à une colonne xml produit un contenu, un nœud texte simple avec la valeur de type chaîne de caractères du résultat. Un résultat XML affecté à une colonne d'un autre type pourrait ne pas avoir plus d'un nœud. Dans le cas contraire, une erreur est levée. S'il y a exactement un nœud, la colonne sera configurée en lui convertissant la valeur textuelle du nœud (comme défini dans la fonction string de XPath 1.0) vers le type PostgreSQL.

La valeur textuelle d'un élément XML est la concaténation dans l'ordre du document de tous les nœuds textes contenus dans cet élément et ses descendants. La valeur textuelle d'un élément sans nœuds textuels descendants est une chaîne vide (et non pas NULL). Tout attribut xsi:nil est ignoré. Veuillez noter que le nœud text() d'espaces non significatifs entre deux éléments non-texte est préservé, et que l'espace non significatif de départ d'un nœud text() n'est pas aplati. La fonction string XPath 1.0 pourrait être consultée pour les règles définissant la valeur textuelle des autres types de nœuds XML et des valeurs non-XML.

Les règles de conversion présentées ici ne sont pas exactement celles du standard SQL, comme discuté dans Section D.3.1.3.

Si l'expression du chemin renvoie un ensemble de nœuds vide (typiquement s'il n'y a pas de correspondance) pour une ligne donnée, la colonne sera configurée à NULL, sauf si une default_expression est indiquée. Dans ce cas, la valeur résultant de l'évaluation de cette expression est utilisée.

Les colonnes peuvent être marquées comme NOT NULL. Si column_expression pour une colonne NOT NULL n'a pas de correspondance et qu'il n'y a pas de DEFAULT ou que default_expression est aussi évaluée à NULL, une erreur est levée.

Plutôt qu'être évaluée immédiatement quand xmltable est appelé, une default_expression est évaluée à chaque fois qu'une valeur par défaut est ajoutée pour la colonne. Si l'expression est qualifiée stable ou immutable, la réévaluation peut être ignorée. Cela signifie que vous pouvez utiliser des fonctions volatiles telles que nextval dans default_expression.

Exemples:

CREATE TABLE xmldata AS SELECT
xml $$
<ROWS>
  <ROW id="1">
    <COUNTRY_ID>AU</COUNTRY_ID>
    <COUNTRY_NAME>Australia</COUNTRY_NAME>
  </ROW>
  <ROW id="5">
    <COUNTRY_ID>JP</COUNTRY_ID>
    <COUNTRY_NAME>Japan</COUNTRY_NAME>
    <PREMIER_NAME>Shinzo Abe</PREMIER_NAME>
    <SIZE unit="sq_mi">145935</SIZE>
  </ROW>
  <ROW id="6">
    <COUNTRY_ID>SG</COUNTRY_ID>
    <COUNTRY_NAME>Singapore</COUNTRY_NAME>
    <SIZE unit="sq_km">697</SIZE>
  </ROW>
</ROWS>
$$ AS data;

SELECT xmltable.*
  FROM xmldata,
       XMLTABLE('//ROWS/ROW'
                PASSING data
                COLUMNS id int PATH '@id',
                        ordinality FOR ORDINALITY,
                        "COUNTRY_NAME" text,
                        country_id text PATH 'COUNTRY_ID',
                        size_sq_km float PATH 'SIZE[@unit = "sq_km"]',
                        size_other text PATH
                             'concat(SIZE[@unit!="sq_km"], " ", SIZE[@unit!="sq_km"]/@unit)',
                        premier_name text PATH 'PREMIER_NAME' DEFAULT 'not specified') ;

 id | ordinality | COUNTRY_NAME | country_id | size_sq_km |  size_other  | premier_name
----+------------+--------------+------------+------------+--------------+---------------
  1 |          1 | Australia    | AU         |            |              | not specified
  5 |          2 | Japan        | JP         |            | 145935 sq_mi | Shinzo Abe
  6 |          3 | Singapore    | SG         |        697 |              | not specified

L'exemple suivant montre la concaténation de multiples nœuds text(), l'utilisation du nom de colonne comme un filtre XPath, ainsi que le traitement des espaces non significatifs, des commentaires XML et le traitement des instructions :

CREATE TABLE xmlelements AS SELECT
xml $$
  <root>
   <element>  Hello<!-- xyxxz -->2a2<?aaaaa?> <!--x-->  bbb<x>xxx</x>CC  </element>
            </root>
            $$ AS data;

            SELECT xmltable.*
            FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);

            element
            -------------------------
            Hello2a2   bbbxxxCC
            

L'exemple suivant illustre comment la clause XMLNAMESPACES peut être utilisée pour spécifier l'espace de nom par défaut, et une liste d'espaces de nom supplémentaire utilisés aussi bien dans le document XML que dans les expressions Xpath :

WITH xmldata(data) AS (VALUES ('
<example xmlns="http://example.com/myns" xmlns:B="http://example.com/b">
 <item foo="1" B:bar="2"/>
 <item foo="3" B:bar="4"/>
 <item foo="4" B:bar="5"/>
</example>'::xml)
)
SELECT xmltable.*
  FROM XMLTABLE(XMLNAMESPACES('http://example.com/myns' AS x,
                              'http://example.com/b' AS "B"),
             '/x:example/x:item'
                PASSING (SELECT data FROM xmldata)
                COLUMNS foo int PATH '@foo',
                  bar int PATH '@B:bar');
 foo | bar
-----+-----
   1 |   2
   3 |   4
   4 |   5
(3 rows)