xml2 — функции запросов XPath и преобразований XSLT

примечание

Эта страница переведена при помощи нейросети GigaChat.

Модуль xml2 обеспечивает поддержку запросов XPath и трансформации XSLT.

Уведомление о повреждении

Начиная с версии PostgreSQL 8.3, в ядро сервера включены функции для работы с XML, основанные на стандарте SQL/XML. Эти функции охватывают проверку синтаксиса XML и выполнение запросов XPath, но API существенно отличается от предыдущих решений. Предполагается, что в будущих версиях PostgreSQL модуль будет исключен в пользу нового API, поэтому рекомендуется пересмотреть приложения с учетом нововведений. Если выяснится, что какие-либо функции модуля недоступны в достаточной степени через новый API, пожалуйста, сообщите о проблеме на почту pgsql-hackers@lists.postgresql.org, чтобы специалисты смогли устранить недостаток.

Описание функций

Таблица «Функции xml2» демонстрирует набор функций, предоставляемых этим модулем. Данные функции обеспечивают базовую обработку XML и выполнение запросов XPath.

Функции xml2

Функция	Описание
`xml_valid` (`document` text) → boolean	Анализирует указанный документ и возвращает `true`, если документ является правильно сформированным XML. (Примечание: это псевдоним для стандартной функции PostgreSQL `xml_is_well_formed()`. Название `xml_valid()` технически неверно, поскольку допустимость и правильность имеют разные значения в XML.)
`xpath_string` (`document` text, `query` text) → text	Вычисляет запрос XPath в предоставленном документе и преобразует результат в тип `text`.
`xpath_number` (`document` text, `query` text) → real	Вычисляет запрос XPath в предоставленном документе и преобразует результат в тип `real`.
`xpath_bool` (`document` text, `query` text) → boolean	Оценивает запрос XPath на предоставленном документе и преобразует результат в тип `boolean`.
`xpath_nodeset` (`document` text, `query` text, `toptag` text, `itemtag` text) → text	Оценивает запрос на документе и оборачивает результат в XML-теги. Если результат множественный, вывод будет выглядеть так: <toptag> <itemtag>Value 1 which could be an XML fragment</itemtag> <itemtag>Value 2....</itemtag> </toptag> Если `toptag` или `itemtag` — пустая строка, соответствующий тег пропускается.
`xpath_nodeset` (`document` text, `query` text, `itemtag` text) → text	Как предыдущая форма функции, но результат пропускает тег `toptag`.
`xpath_nodeset` (`document` text, `query` text) → text	Как предыдущая форма функции, но результат пропускает оба тега.
`xpath_list` (`document` text, `query` text, `separator` text) → text	Оценивает запрос в документе и возвращает несколько значений, разделенных указанным разделителем, например `Value 1, Value 2, Value 3`, если `separator` равен `,`.
`xpath_list` (`document` text, `query` text) → text	Обертка предыдущей формы функции, использующей `,` в качестве разделителя.

xpath_table

xpath_table(text key, text document, text relation, text xpaths, text criteria) returns setof record

Функция xpath_table представляет собой табличную функцию, которая вычисляет набор запросов XPath для коллекции документов и возвращает результаты в виде таблицы. Первый столбец результата содержит поле первичного ключа исходной таблицы документов, что позволяет удобно использовать полученный набор в операциях объединений. Параметры функции описаны в таблице «Параметры xpath_table».

Параметры функции xpath_table

Параметры xpath_table

Параметр	Описание
`key`	Имя поля, которое будет первым столбцом выходной таблицы и идентифицирует запись, из которой извлечена каждая строка результатов (см. примечание о нескольких значениях ниже).
`document`	Имя поля, содержащего XML-документ.
`relation`	Имя таблицы или представления, содержащего документы.
`xpaths`	Одно или несколько выражений XPath, разделенных символом `
`criteria`	Условие предложения WHERE. Нельзя пропустить, поэтому используйте `true` или `1=1`, если требуется обработать все строки отношения.

Эти параметры (за исключением строк XPath) подставляются непосредственно в обычный оператор SQL SELECT, что предоставляет определенную гибкость в составлении запроса:

SELECT <key>, <document> FROM <relation> WHERE <criteria>

То есть, параметры могут быть любыми допустимыми элементами в соответствующих частях запроса. Результатом такого SELECT должна быть ровно пара столбцов (этого гарантированно добьешься, если не перечислишь несколько полей для ключа или документа). Следует помнить, что подобный упрощенный подход требует обязательной проверки пользовательских данных для предотвращения атак SQL-инъекций.

Функция должна использоваться в секции FROM с ключевым словом AS, определяющим названия выходных столбцов. Например:

SELECT * FROM
xpath_table('article_id',
            'article_xml',
            'articles',
            '/article/author|/article/pages|/article/title',
            'date_entered > ''2003-01-01'' ')
AS t(article_id integer, author text, page_count integer, title text);

Предложение AS определяет имена и типы столбцов в результирующей таблице. Первым столбцом является поле «ключ», остальные соответствуют запросам XPath. Если запросов XPath больше, чем определено столбцов, лишние запросы игнорируются. Если результат содержит больше столбцов, чем запросов XPath, дополнительные столбцы примут значение NULL.

Обратите внимание, что в примере столбец результата page_count объявлен как целое число. Функция работает со строковыми представлениями, поэтому при объявлении целого числа она берет строковое значение результата XPath и преобразует его в нужное значение с помощью функций приведения PostgreSQL. Если строка пустая или недопустимая, может произойти ошибка, поэтому рекомендуется использовать тип text, если данные сомнительны.

Сам запрос SELECT не обязательно должен быть простым SELECT *. Он может обращаться к результатам по именам столбцов или объединять их с другими таблицами. Функция создает виртуальную таблицу, с которой можно выполнять любые операции, такие как агрегация, объединение, сортировка и т.д., например:

SELECT t.title, p.fullname, p.email
FROM xpath_table(
    'article_id', 'article_xml', 'articles',
    '/article/title|/article/author/@id',
    'xpath_string(article_xml,''/article/@date'') > ''2003-03-20'''
) AS t(article_id integer, title text, author_id integer),
tblPeopleInfo AS p
WHERE t.author_id = p.person_id;

Этот пример демонстрирует более сложную интеграцию. Разумеется, всю конструкцию можно заключить в представление для упрощения обращения.

Многозначные результаты

Функция xpath_table исходит из того, что каждый запрос XPath может возвращать несколько значений, поэтому количество строк в результатах может не совпадать с числом входных документов. Первая строка содержит первые результаты каждого запроса, вторая строка — вторые результаты и так далее. Если какой-то запрос возвращает меньшее количество значений, недостающие строки заполняются пустыми значениями.

В некоторых случаях известно, что запрос XPath вернет единственное значение (например, уникальный идентификатор документа). Если такой запрос используется вместе с запросом, возвращающим несколько результатов, одиночный результат появится только в первой строке итогового набора. Решением является включение ключевого поля в запрос как часть объединения с более простым запросом XPath. Например:

CREATE TABLE test (
    id int PRIMARY KEY,
    xml text
);

INSERT INTO test VALUES (1, '<doc num="C1">
<line num="L1"><a>1</a><b>2</b><c>3</c></line>
<line num="L2"><a>11</a><b>22</b><c>33</c></line>
</doc>');

INSERT INTO test VALUES (2, '<doc num="C2">
<line num="L1"><a>111</a><b>222</b><c>333</c></line>
<line num="L2"><a>111</a><b>222</b><c>333</c></line>
</doc>');

SELECT * FROM
  xpath_table('id','xml','test',
              '/doc/@num|/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c',
              'true')
  AS t(id int, doc_num varchar(10), line_num varchar(10), val1 int, val2 int, val3 int)
WHERE id = 1 ORDER BY doc_num, line_num

 id | doc_num | line_num | val1 | val2 | val3
----+---------+----------+------+------+------
  1 | C1      | L1       |    1 |    2 |    3
  1 |         | L2       |   11 |   22 |   33

Чтобы получить значение doc_num в каждой строке результата, можно вызвать функцию xpath_table дважды и соединить полученные результаты.

SELECT t.*,i.doc_num FROM
  xpath_table('id', 'xml', 'test',
              '/doc/line/@num|/doc/line/a|/doc/line/b|/doc/line/c',
              'true')
    AS t(id int, line_num varchar(10), val1 int, val2 int, val3 int),
  xpath_table('id', 'xml', 'test', '/doc/@num', 'true')
    AS i(id int, doc_num varchar(10))
WHERE i.id=t.id AND i.id=1
ORDER BY doc_num, line_num;

 id | line_num | val1 | val2 | val3 | doc_num
----+----------+------+------+------+---------
  1 | L1       |    1 |    2 |    3 | C1
  1 | L2       |   11 |   22 |   33 | C1
(2 rows)

Функции XSLT

Ниже описаны доступные функции, если установлен libxslt.

xslt_process

xslt_process(text document, text stylesheet, text paramlist) returns text

Функция применяет таблицу стилей XSL к документу и возвращает преобразованный результат. Параметр paramlist представляет собой список назначений параметров, используемых при преобразовании, в формате a=1,b=2. Обратите внимание, что синтаксический анализ параметров примитивен: значения параметров не могут содержать запятых!

Имеется также двухпараметрическая версия функции xslt_process, которая не передает никакие параметры для преобразования.

Уведомление о повреждении​

Описание функций​

xpath_table​

Параметры функции xpath_table​

Многозначные результаты​

Функции XSLT​

xslt_process​