xmltext ( text ) → xml

Cette fonction xmltext renvoie une valeur XML avec un seul nœud de texte contenant l'argument d'entrée comme contenu. Les entités prédéfinies comme l'esperluette (&), les chevrons gauche et droit (< >), et les guillemets ("") sont échappées.

Exemple :

SELECT xmltext('< foo & bar >');
         xmltext
-------------------------
 &lt; foo &amp; bar &gt;

xmlcomment ( text ) → xml
   

La fonction xmlcomment crée une valeur XML contenant un commentaire XML avec le texte spécifié comme contenu. Le texte ne peut pas contenir « -- » ou se terminer avec un « - », sinon la construction résultante serait un commentaire XML invalide. Si l'argument est NULL, le résultat est NULL.

Example:

SELECT xmlcomment('hello');

  xmlcomment
--------------
 <!--hello-->
    

xmlconcat ( xml [, ...] ) → xml
  

La fonction xmlconcat concatène une liste de valeurs XML individuelles pour créer une seule valeur contenant un fragment de contenu XML. Les valeurs NULL sont omises. Le résultat est NULL si tous les arguments sont NULL.

Example:

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

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

Les déclarations XML sont combinées ainsi. Si toutes les valeurs des arguments ont la même déclaration de version XML, cette version est utilisée comme résultat. Sinon, aucune version n'est utilisée. Si toutes les valeurs des arguments ont une valeur de déclarationl standalone à « yes », alors cette valeur est utilisée dans le résultat. Si toutes les valeurs d'agument ont une valeur de déclaration standalone et qu'au moins une de ces valeurs est « no », alors cette valeur est utilisée dans le résultat. Dans tous les autres cas, le résultat n'aura pas de déclaration standalone. Si le résultat nécessite une déclaration standalone, mais par de déclaration version, une déclaration version 1.0 sera utilisée car XML requiert qu'une déclaration XML contiennent une déclaration de version. Les déclarations d'encodage sont ignorés et supprimés dans tous les cas.

Example:

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

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

xmlelement ( NAME name [, XMLATTRIBUTES ( attvalue [ AS attname ] [, ...] ) ] [, content [, ...]] ) → xml
   

L'expression xmlelement produit un élément XML avec le nom, les attributs et le contenu donnés. Les éléments name et attname affichés dans la syntaxe sont de simples identifiants, et non pas des valeurs. Les éléments attvalue et content sont des expressions, qui peuvent être de n'importe quel type de données PostgreSQL. Les arguments dans XMLATTRIBUTES génèrent les attributs de l'élément XML ; les valeurs content sont concaténées pour former son contenu.

Examples:

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éments et d'attributs qui ne sont pas des noms XML valides sont échappés en remplaçant les caractères problématiques par la séquence _xHHHH_, où HHHH est le point code Unicode du caractère dans sa notation hexadécimale. Par exemple :

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

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

Un nom d'attribut explicite n'a pas besoin d'être spécifié si la valeur de l'attribut est une référence de colonne, auquel cas le nom de la colonne sera utilisé comme nom d'attribut par défaut. Dans les autres cas, l'attribut doit se voir donner 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 ces exemples ne le sont pas :

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

Le contenu d'un élément, si indiqué, sera formaté suivant ton 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 sera formaté en une donnée caractère XML valide. Ceci signifie en particulier que les caractères <, >, et & seront convertis en entités. Les données binaires (type de données bytea) seront représentées dans un encodage base64 ou hex, suivant la configuration du paramètre xmlbinary. Le comportement particulier pour les types de données individuels devrait évoluer pour aligner les correspondances PostgreSQL avec ceux spécifiés dans SQL:2006 et ultérieurs, comme discuté dans Section D.3.1.3.

xmlforest ( content [ AS name ] [, ...] ) → xml
 

L'expression xmlforest produit une forêt (séquence) XML d'éléments en utilisant les noms et le contenu donnés. Quant à xmlelement, chaque name doit être un simple identifiant, alors que les expressions content peuvent avoir n'importe quel type de données.

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 deuxième exemple, le nom de l'élément peut être omis si la valeur contenue est une référence de colonne, auquel cas le nom de l'élément est utilisé par défaut. Sinon un nom doit être spécifié.

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

Notez que les forêts XML ne sont pas des documents XML valides si elles consistent de plus d'un élément, donc il pourrait être utile d'envelopper les expressions xmlforest dans xmlelement.

xmlpi ( NAME name [, content ] ) → xml
 

L'instruction xmlpi crée une instruction de traitement XML. Quant à xmlelement, name doit être un simple identifiant, alors que l'expression content peut contenir tout type de données. Si présent, content 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} ] ) → xml
  

L'expression xmlroot altère les propriétés du nœud racine d'une valeur XML. Si une version est spécifié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 ) → xml
   

La fonction xmlagg est, contrairement aux autres fonctions décrites ici, une fonction d'agrégat. Elle concatène les valeurs en entrée à l'appel de fonction d'agrégat, tout comme le fait xmlconcat, sauf que la concaténation survient au travers des lignes plutôt qu'au travers des expressions dans une seule ligne. Voir Section 9.21 pour l'information supplémentaire 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é à 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 recommendée dans les versions précédentes et pourrait toujours être utile dans des cas spécifiques :

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

xml IS DOCUMENT → boolean
    

L'expression IS DOCUMENT renvoie true si la valeur de l'argument XML est un document XML propre, false si elle ne l'est pas (c'est-à-dire un fragment de contenu), ou null si l'argument est null. Voir Section 8.13 sur la différence entre les documents et les fragments de contenu.

xml IS NOT DOCUMENT → boolean
    

L'expression IS NOT DOCUMENT renvoie false si la valeur de l'argument XML est un document XML propre, true si elle ne l'est pas (c'est-à-dire un fragment de contenu), ou null si l'argument est null.

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

La fonction xmlexists évalue une expression XPath 1.0 (le premier argument), avec la valeur XML passée comme son élément de contexte. La fonction renvoie false si le résultat de cette évaluation renvoie un ensemble de nœud vide, true si elle renvoie toute autre valeur. La fonction renvoie null si un argument vaut null. Une valeur non null passée comme élément de contexte doit être un document XML, et non pas un fragment de contenu ou une valeur non XML.

Example:

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 dans PostgreSQL, mais sont ignorées comme indiqué 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 ) → boolean
xml_is_well_formed_document ( text ) → boolean
xml_is_well_formed_content ( text ) → boolean
     

Ces fonctions vérifient si une chaîne de type text représente un XML bien formé, renvoyant 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 que c'est une contenu bien formé. xml_is_well_formed fait le premier si le paramètre de configuration xmloption est configuré à DOCUMENT, et le deuxième s'il est configuré à CONTENT. Ceci signifie que xml_is_well_formed est utile pour voir si une simple conversion vers le type xml réussira, alors que les deux autres fonctions sont utiles pour voir si les variantes correspondantes de XMLPARSE réussira.

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 une vérification de correspondance sur les espaces de nom.

xpath ( xpath text, xml xml [, nsarray text[] ] ) → xml[]
      

La fonction xpath évalue l'expression XPath 1.0 indiquée dans xpath (sous la forme d'une donnée de type text) avec la valeur XML de type xml. Elle renvoie des valeurs XML correspondant à l'ensemble de nœuds produits par l'expression XPath. Si l'expression XPath renvoie une valeur scalaire plutôt qu'un ensemble de nœuds, un tableau d'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 d'espaces de nom. Ce tableau devrait être un tableau de text à deux dimensions avec la longueur du deuxième axe égale à 2 (cela devrait être un tableau de tableaux, chacun des deux contenant exactement deux éléments). Le premier élément de chaque entrée de tableau est le nom de l'espace de noms (alias), le second est l'URI de l'espace de noms. Il n'est pas requis que les alias fournis dans ce tableau soient identiques à ceux utilisés dans le document XML lui-même (en d'autres termes, dans le document XML et dans le contexte de la fonction xpath function context, les alias sont local).

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 les espaces de noms par défaut (anonymes), faire ceci :

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 text, xml xml [, nsarray text[] ] ) → boolean
       

La fonction xpath_exists est une forme spécialisée de la fonction xpath. Au lieu de renvoyer les valeurs XML individuelles satisfaisant l'expression XPath 1.0, cette fonction renvoie un booléen indiquant si la requête était satisfaite ou non (spécifiquement s'il produit une valeur autre qu'un ensemble vide de nœuds). Cette fonction est équivalente au prédicat XMLEXISTS, sauf qu'il offre aussi du support pour l'argument de correspondance d'espaces de noms.

Example:

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 }
            [, ...]
) → setof record
        

L'expression xmltable produit une table basée sur une valeur XML, un filtre XPath pour extraire les lignes et un ensemble de définition de colonnes. Bien que cela ressemble syntaxiquement à une fonction, il peut aussi apparaître comme une table dans la clause FROM de la requête.

La clause XMLNAMESPACES optionnelle donne une liste, séparée par des virgules, des définitions d'espaces de nom, où chaque namespace_uri est une expression text et chaque namespace_name est un simple identifiant. Elle spécifie les espaces de nom XML utilisés dans le document et leur alias. La spécification d'un espace de nom par défaut n'est actuellement pas supportée.

L'argument requis row_expression est une expression XPath 1.0 (donné sous la forme d'un text) qui est évaluée, passant la valeur XML document_expression sous la forme d'un élément de contexte, pour obtenir un ensemble de nœuds XML. Ces nœuds sont ce que xmltable transforme des lignes en sortie. Aucune ligne ne sera produite si document_expression est NULL, ou si row_expression produit un ensemble vide de nœuds ou tout autre valeur qu'un ensemble de nœuds.

document_expression fournit l'élément de contexte pour row_expression. Cela 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 discuté dans Section D.3.2.

Dans le standard SQL, la fonction xmltable évalue des expressions dans le langage XML Query, mais PostgreSQL autorise seulement les expressions XPath 1.0, comme discutées dans Section D.3.1.

La clause requise COLUMNS spécifie les colonnes produites dans la table en sortie. Voir le résumé de la syntaxe ci-dessus pour le format. Un nom est requis pour chaque colonne, comme l'est un type de données (sauf si FOR ORDINALITY est spécifié, auquel cas le type integer est implicite). Les clauses de chemin, de valeur par défaut et de nullabilité sont optionnelles.

Une colonne marquée FOR ORDINALITY sera peuplée avec les numéros de lignes, commençant par 1, dans l'ordre des nœuds récupérés à partir de l'ensemble de nœuds résultats de row_expression. Au plus une colonne sera marquée FOR ORDINALITY.

Le column_expression pour un 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, pour trouver la valeur de la colonne. Si aucune column_expression n'est donnée, alors le nom de la colonne est utilisé comme un chemin implicite.

Si une expression XPath de colonne renvoie une valeur non XML (qui est limitée à une chaîne, un booléen ou un double en XPath 1.0) et la colonne a un type type autre que xml, la colonne sera configurée ainsi en affectant la représentation textuelle de la valeur vers le type PostgreSQL. (Si la valeur est un booléen, sa représentation textuelle est comprise comme 1 ou 0 si la catégorie du type de la colonne en sortie est numérique, sinon true ou false.)

Si l'expression XPath d'une colonne renvoie un ensemble non vide de nœuds XML et si le type PostgreSQL de la colonne est xml, la colonne sera affectée au résultat exact de l'expression s'il est de forme document ou contenu. ^[8]

Un résultat non XML affecté à une colonne xml en sortie produit du contenu, un nœud texte simple avec la valeur chaîne du résultat. Un résultat XML affecté à une colonne de tout autre type pourrait ne pas avoir plus d'un nœud, sinon une erreur est levée. S'il y a exactement un nœud, la colonne sera configurée d'après son affectation de la valeur textuelle du nœud (comme défini pour la fonction string XPath 1.0) du type PostgreSQL.

La valeur de chaîne d'un élément XML est la concaténation, dans l'ordre du document, de tous les nœuds texte contenus dans cet élément et ses descendants. La valeur de chaîne d'un élément sans nœuds texte descendants est une chaîne vide (non NULL). Tous les attributs xsi:nil sont ignorés. Notez que le nœud text() avec uniquement des espaces blancs entre deux éléments non-texte est préservé et que l'espace blanc au début du nœud text() n'est pas aplati. La fonction XPath 1.0 string peut être consultée pour les règles définissant la valeur de chaîne 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 ceux du standard SQL, comme discuté dans Section D.3.1.3.

Si l'expression de chemin renvoie un ensemble vide de nœuds (typiquement quand cela ne correspond pas) pour une ligne donnée, la colonne sera configurée à NULL, sauf si une default_expression est indiquée ; alors la valeur résultant de l'évaluation d'une expression est utilisée.

Une default_expression, plutôt qu'être évaluée immédiatement quand xmltable est appelée, est évaluée chaque fois qu'une valeur par défaut est nécessaire pour la colonne. Si l'expression qualifie comme stable ou immuable, l'évaluation de répétition peut être ignorée. Ceci signifie que vous pouvez utiliser utilement les fonctions volatiles comme nextval dans default_expression.

Les colonnes peuvent être marquées NOT NULL. Si column_expression pour une colonne NOT NULL ne correspond à rien et qu'il n'y a ni valeur par défaut (DEFAULT) ni default_expression, elle s'évalue à NULL, une erreur est rapportée.

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 une concaténation de plusieurs nœuds text(), une utilisation du nom de colonne en tant que filtre XPath, et le traitement des espaces blancs, 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é pour spécifier une liste d'espaces de noms utilisée dans le document XML ainsi 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)