xmltext ( text ) → xml

Функция xmltext возвращает XML-значение с единственным текстовым узлом, содержимое которого соответствует входному аргументу. Предопределенные сущности, такие как амперсанд (&), левая и правая угловые скобки (< >) и кавычки (""), экранируются.

Пример:

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

xmlcomment ( text ) → xml

Функция xmlcomment создает XML-значение, содержащее XML-комментарий с указанным текстом в качестве содержимого. Данный текст не может содержать «--» или заканчиваться на «-», в противном случае полученная конструкция не будет являться допустимым XML-комментарием. Если аргумент равен NULL, результатом также будет NULL.

Пример:

SELECT xmlcomment('hello');

  xmlcomment
--------------
 

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

Функция xmlconcat объединяет список отдельных XML-значений для создания единого значения, представляющего собой фрагмент XML-содержимого. Значения NULL пропускаются; результат принимает значение NULL только в том случае, если среди аргументов нет значений, отличных от NULL.

Пример:

SELECT xmlconcat('', 'foo');

      xmlconcat
----------------------
 foo

Декларации XML, при их наличии, объединяются следующим образом. Если все значения аргументов имеют одинаковую декларацию версии XML, эта версия используется в итоговом результате; в противном случае версия не указывается. Если все значения аргументов имеют значение в объявлении standalone «yes», то данное значение используется в результате. Если все значения аргументов имеют значение в декларации standalone и по крайней мере одно из них имеет значение «no», то в результате используется именно это значение. В противном случае итоговый результат не будет содержать декларации standalone. Если определено, что для результата требуется декларация standalone, но декларация версии отсутствует, будет использована декларация с версией 1.0, поскольку спецификация XML требует, чтобы декларация XML обязательно содержала номер версии. Объявления кодировки во всех случаях игнорируются и удаляются.

Пример:

SELECT xmlconcat('', '');

             xmlconcat
-----------------------------------
 

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

xmlelement выражение формирует XML-элемент с заданным именем, атрибутами и содержимым. name и attname элементы, указанные в описании синтаксиса, являются простыми идентификаторами, а не значениями. attvalue и content элементы представляют собой выражения, которые могут возвращать любые Digital Q.DataBase тип данных. Аргументы, указанные внутри XMLATTRIBUTES формируют атрибуты XML-элемента; content значения объединяются для формирования его содержимого.

Примеры:

SELECT xmlelement(name foo);

 xmlelement
------------
 

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

    xmlelement
------------------
 

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

             xmlelement
-------------------------------------
 content

Имена элементов и атрибутов, не являющиеся допустимыми именами XML, экранируются путем замены недопустимых символов последовательностью _xHHHH_, где HHHH — шестнадцатеричный код символа в кодировке Unicode. Например:

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

            xmlelement
----------------------------------
 

Явное имя атрибута указывать не обязательно, если значение атрибута является ссылкой на столбец; в этом случае в качестве имени атрибута по умолчанию будет использовано имя столбца. В остальных случаях атрибуту необходимо присвоить явное имя. Таким образом, следующий пример является допустимым:

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

Однако данные примеры не являются допустимыми:

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

Содержимое элемента, если оно указано, будет отформатировано в соответствии с его типом данных. Если само содержимое относится к типу xml, становится возможным построение сложных XML-документов. Например:

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

                  xmlelement
----------------------------------------------
 

Содержимое других типов будет преобразовано в синтаксически корректные символьные данные XML. В частности, это означает, что символы <, >, и & будут преобразованы в XML-сущности. Двоичные данные (тип данных bytea) будут представлены в кодировке base64 или hex в зависимости от значения параметра конфигурации xmlbinary. Ожидается, что логика обработки отдельных типов данных будет развиваться для приведения сопоставлений PostgreSQL в соответствие со спецификациями стандарта языка SQL:2006 и более поздних версий, как указано в Раздел 8.4.3.1.3.

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

xmlforest выражение формирует XML-лес (последовательность элементов), используя указанные имена и содержимое. Аналогично функции xmlelement, каждый name должен представлять собой простой идентификатор, в то время как content выражения могут относиться к любому типу данных.

Примеры:

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

          xmlforest
------------------------------
 abc123


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

                                xmlforest
------------------------------------​ -----------------------------------
 pg_authid​rolname
 pg_authid​rolsuper
 ...

Как показано во втором примере, имя элемента может быть опущено, если значение содержимого является ссылкой на столбец; в этом случае имя столбца используется по умолчанию. В противном случае имя должно быть указано явно.

Имена элементов, не являющиеся допустимыми именами XML, экранируются так же, как и в случае xmlelement выше. Аналогичным образом данные содержимого экранируются для формирования допустимого XML-содержимого, если только они уже не имеют тип xml.

Обратите внимание, что конструкции XML forest не являются корректными XML-документами, если они состоят более чем из одного элемента, поэтому может быть целесообразно обернуть xmlforest выражения в xmlelement.

xmlpi ( NAME name [, content ] ) → xml

xmlpi выражение создает инструкцию по обработке XML. Что касается xmlelement, the name должен представлять собой простой идентификатор, в то время как content выражение может иметь любой тип данных. content, если он присутствует, не должен содержать последовательность символов ?>.

Пример:

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

            xmlpi
-----------------------------
 

xmlroot ( xml, VERSION {text|NO VALUE} [, STANDALONE {YES|NO|NO VALUE} ] ) → xml

xmlroot Данное выражение изменяет свойства корневого узла XML-значения. Если версия указана, она заменяет значение в объявлении версии корневого узла; если указан параметр standalone, он заменяет значение в объявлении standalone корневого узла.

SELECT xmlroot(xmlparse(document 'abc'),
               version '1.0', standalone yes);

                xmlroot
----------------------------------------
 
 abc

xmlagg ( xml ) → xml

Функция xmlagg в отличие от других описанных здесь функций, является агрегатной функцией. Она объединяет входные значения, передаваемые в вызов агрегатной функции, подобно тому как это делает xmlconcat , за исключением того, что объединение выполняется для значений в разных строках, а не для разных выражений в одной строке. См. Раздел 2.6.21 дополнительные сведения об агрегатных функциях.

Пример:

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

Для определения порядка объединения к ORDER BY вызову агрегатной функции может быть добавлено предложение ORDER BY, как описано в Раздел 2.1.2.7. Например:

SELECT xmlagg(x ORDER BY y DESC) FROM test;
        xmlagg
----------------------
 abc

Следующий нестандартный подход рекомендовался в предыдущих версиях и все еще может быть полезен в определенных случаях:

SELECT xmlagg(x) FROM (SELECT * FROM test ORDER BY y DESC) AS tab;
        xmlagg
----------------------
 abc

xml IS DOCUMENT → boolean

Выражение IS DOCUMENT возвращает значение true, если XML-значение аргумента является полноценным XML-документом, false, если оно таковым не является (то есть представляет собой фрагмент содержимого), или null, если аргумент имеет значение null. См. Раздел 2.5.13 о различиях между документами и фрагментами содержимого.

xml IS NOT DOCUMENT → boolean

Выражение IS NOT DOCUMENT возвращает значение false, если XML-значение аргумента является полноценным XML-документом, true, если оно таковым не является (то есть представляет собой фрагмент содержимого), или null, если аргумент имеет значение null.

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

Функция xmlexists вычисляет выражение XPath 1.0 (первый аргумент), используя переданное XML-значение в качестве контекстного элемента. Данная функция возвращает false, если результатом вычисления является пустой набор узлов, и true, если результатом является любое другое значение. Данная функция возвращает null, если какой-либо из её аргументов имеет значение null. Значение, отличное от null, передаваемое в качестве элемента контекста, должно представлять собой XML-документ, а не фрагмент содержимого или иное значение, не относящееся к XML.

Пример:

SELECT xmlexists('//town[text() = ''Toronto'']' PASSING BY VALUE 'TorontoOttawa');

 xmlexists
------------
 t
(1 строка)

BY REF и BY VALUE предложения допускаются в Digital Q.DataBase, но игнорируются, как описано в Раздел 8.4.3.2.

В стандарте языка SQL функция xmlexists функция вычисляет значение выражения на языке XML Query, однако Digital Q.DataBase допускает использование только выражений XPath 1.0, как описано в Раздел 8.4.3.1.

xml_is_well_formed ( text ) → boolean
xml_is_well_formed_document ( text ) → boolean
xml_is_well_formed_content ( text ) → boolean

Данные функции проверяют, представляет ли text строка корректно сформированный XML-код, возвращая результат логического типа. xml_is_well_formed_document выполняет проверку на корректность формирования документа, в то время как xml_is_well_formed_content выполняет проверку на корректность формирования содержимого. xml_is_well_formed выполняет первое действие, если xmloption параметр конфигурации принимает значение DOCUMENT, и второе, если он установлен в значение CONTENT. Это означает, что данная функция xml_is_well_formed полезна для проверки возможности приведения значения к типу xml , тогда как две другие функции позволяют проверить, будут ли соответствующие варианты функции XMLPARSE выполнены успешно.

Примеры:

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

SELECT xml_is_well_formed('');
 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('bar');
 xml_is_well_formed_document
-----------------------------
 t
(1 строка)

SELECT xml_is_well_formed_document('bar');
 xml_is_well_formed_document
-----------------------------
 f
(1 строка)

Последний пример показывает, что выполняемые проверки включают контроль корректности сопоставления пространств имен.

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

Функция xpath вычисляет выражение XPath 1.0 xpath (переданное в виде текста) относительно XML-значения xml. Данная функция возвращает массив XML-значений, соответствующих набору узлов, сформированному выражением XPath. Если выражение XPath возвращает скалярное значение вместо набора узлов, возвращается массив, содержащий один элемент.

Второй аргумент должен быть корректно сформированным XML-документом. В частности, он должен содержать ровно один корневой элемент.

Необязательный третий аргумент этой функции представляет собой массив сопоставлений пространств имен. Данный массив должен быть двумерным text массивом, в котором длина второй оси равна 2 (то есть это должен быть массив массивов, каждый из которых состоит ровно из 2 элементов). Первым элементом каждой записи массива является имя (псевдоним) пространства имен, вторым — URI пространства имен. Не обязательно, чтобы псевдонимы, указанные в данном массиве, совпадали с псевдонимами, используемыми в самом XML-документе (иными словами, как в XML-документе, так и в xpath контексте функции псевдонимы local).

Пример:

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

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

Для работы с пространствами имен по умолчанию (анонимными) можно использовать следующий подход:

SELECT xpath('//mydefns:b/text()', 'test',
             ARRAY[ARRAY['mydefns', 'http://example.com']]);

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

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

Функция xpath_exists представляет собой специализированную форму xpath функции. Вместо возврата отдельных XML-значений, соответствующих выражению XPath 1.0, данная функция возвращает логическое значение, указывающее, был ли удовлетворен запрос (в частности, сформировал ли он какой-либо результат, отличный от пустого набора узлов). Эта функция эквивалентна XMLEXISTS предикату, за исключением того, что она также поддерживает аргумент сопоставления пространств имен.

Пример:

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

 xpath_exists
--------------
 t
(1 строка)

XMLTABLE (
    [ XMLNAMESPACES ( namespace_uri AS namespace_name [, ...] ), ]
    row_expression PASSING [BY {REF|VALUE}] document_expression [BY {REF|VALUE}]
    COLUMNS name { тип [PATH column_expression] [DEFAULT default_expression] [NOT NULL | NULL]
                  | FOR ORDINALITY }
            [, ...]
) → setof record

xmltable Выражение XMLTABLE формирует таблицу на основе XML-значения, XPath-фильтра для извлечения строк и набора определений столбцов. Хотя синтаксически данная конструкция напоминает функцию, она может присутствовать в запросе только в качестве таблицы в FROM предложении.

Необязательное XMLNAMESPACES предложение XMLNAMESPACES содержит разделенный запятыми список определений пространств имен, где каждое namespace_uri является text выражение и каждый namespace_name являются простым идентификатором. Данное предложение определяет используемые в документе пространства имен XML и их псевдонимы. Спецификация пространства имен по умолчанию в настоящее время не поддерживается.

Обязательный row_expression аргумент row_expression представляет собой выражение XPath 1.0 (заданное в виде text), которое вычисляется с передачей XML-значения document_expression в качестве контекстного элемента для получения набора XML-узлов. Именно эти узлы выражение XMLTABLE xmltable преобразует в выходные строки. Строки не будут сформированы, если выражение document_expression имеет значение null или если row_expression возвращает пустой набор узлов или любое значение, отличное от набора узлов.

document_expression предоставляет контекстный элемент для row_expression. Данный аргумент должен представлять собой синтаксически корректный XML-документ; фрагменты и леса документов не принимаются. Данный BY REF и BY VALUE предложения принимаются, но игнорируются, как описано в Раздел 8.4.3.2.

В стандарте языка SQL функция xmltable функция вычисляет выражения на языке XML Query, однако Digital Q.DataBase допускает использование только выражений XPath 1.0, как описано в Раздел 8.4.3.1.

Обязательный COLUMNS предложение определяет столбцы, которые будут сформированы в выходной таблице. Формат указан в описании синтаксиса выше. Для каждого столбца требуется указать имя и тип данных (если только не FOR ORDINALITY указано, и в этом случае тип integer подразумевается неявно). Предложения path, default и nullability являются необязательными.

Столбец, помеченный ключевым словом FOR ORDINALITY заполняется номерами строк, начиная с 1, в порядке извлечения узлов из row_expressionрезультирующего набора узлов. Как максимум один столбец может быть помечен как FOR ORDINALITY.

column_expression для столбца является выражением XPath 1.0, которое вычисляется для каждой строки, где текущий узел из row_expression результата выступает в качестве контекстного элемента для поиска значения столбца. Если column_expression не указано, то имя столбца используется в качестве неявного пути.

Если выражение XPath для столбца возвращает значение, не относящееся к типу XML (в стандарте XPath 1.0 это ограничено типами string, boolean или double), а столбец имеет тип Digital Q.DataBase, отличный от xml, то значение столбца будет установлено путём присвоения строкового представления этого значения типу данных Digital Q.DataBase. (Если значение является логическим, его строковое представление принимается за 1 или 0 , если категория типа выходного столбца является числовой, в противном случае — true или false.)

Если выражение XPath для столбца возвращает непустое множество XML-узлов, а указанный для столбца тип данных Digital Q.DataBase — xml, то столбцу будет присвоен результат выражения в исходном виде, если он представлен в форме документа или содержимого. ^[8]

Результат, отличный от XML, при назначении xml выходной столбец формирует содержимое, представляющее собой один текстовый узел со строковым значением результата. Результат в формате XML, присваиваемый столбцу любого другого типа, не может содержать более одного узла, иначе будет выдана ошибка. Если имеется ровно один узел, значение столбца будет установлено так же, как при присваивании строкового значения узла (согласно определению для XPath 1.0 строка функции) к соответствующему типу Digital Q.DataBase.

Строковое значение XML-элемента представляет собой конкатенацию (в порядке следования документа) всех текстовых узлов, содержащихся в данном элементе и его потомках. Строковое значение элемента, не имеющего текстовых узлов-потомков, является пустой строкой (не NULL). Любые xsi:nil атрибуты игнорируются. Обратите внимание, что состоящий только из пробельных символов text() узел между двумя нетекстовыми элементами сохраняется, а ведущие пробелы в text() узле не удаляются. Для изучения правил, определяющих строковые значения других типов XML-узлов и значений, не относящихся к XML, можно обратиться к функции языка XPath 1.0 строка function may be consulted for the rules defining the string value of other XML node types and non-XML values.

Представленные здесь правила преобразования не во всем идентичны правилам стандарта SQL, как обсуждается в Раздел 8.4.3.1.3.

Если выражение пути возвращает пустой набор узлов (как правило, при отсутствии совпадений) для данной строки, столбцу будет присвоено значение NULL, если не задано default_expression указано; используется значение, полученное в результате вычисления этого выражения.

A default_expression, а не вычисляется немедленно при вызове функции xmltable вызывается и вычисляется каждый раз, когда для столбца требуется значение по умолчанию. Если выражение определяется как стабильное (stable) или постоянное (immutable), повторное вычисление может быть пропущено. Это означает, что можно успешно использовать изменчивые функции (volatile), такие как nextval в default_expression.

Столбцы могут быть помечены как NOT NULL. Если column_expression для NOT NULL столбца не найдено соответствий и отсутствует DEFAULT или если значение default_expression также вычисляется как null, возвращается ошибка.

Примеры:

CREATE TABLE xmldata AS SELECT
xml $$

  
    AU
    Australia
  
  
    JP
    Japan
    Shinzo Abe
    145935
  
  
    SG
    Singapore
    697
  

$$ 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

В приведённом ниже примере демонстрируется конкатенация нескольких узлов text(), использование имени столбца в качестве фильтра XPath, а также обработка пробельных символов, XML-комментариев и инструкций по обработке:

CREATE TABLE xmlelements AS SELECT
xml $$
  
     Привет2a2   bbbxxxCC  
  
$$ AS data;

SELECT xmltable.*
  FROM xmlelements, XMLTABLE('/root' PASSING data COLUMNS element text);
         элемент
-------------------------
   Привет2a2   bbbxxxCC

В следующем примере иллюстрируется, каким образом XMLNAMESPACES данное предложение может использоваться для указания списка пространств имен, применяемых как в документе XML, так и в выражениях XPath:

WITH xmldata(data) AS (VALUES ('

 
 
 
'::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)