バージョンごとのドキュメント一覧

F.48. xml2 — XPath問い合わせとXSLT機能 #

<title>xml2 &mdash; XPath querying and XSLT functionality</title>

The <filename>xml2</filename> module provides XPath querying and XSLT functionality. xml2モジュールはXPath問い合わせとXSLT機能を提供します。

F.48.1. 廃止予定の可能性についてのお知らせ #

<title>Deprecation Notice</title>

From <productname>PostgreSQL</productname> 8.3 on, there is XML-related functionality based on the SQL/XML standard in the core server. That functionality covers XML syntax checking and XPath queries, which is what this module does, and more, but the API is not at all compatible. It is planned that this module will be removed in a future version of PostgreSQL in favor of the newer standard API, so you are encouraged to try converting your applications. If you find that some of the functionality of this module is not available in an adequate form with the newer API, please explain your issue to <email>pgsql-hackers@lists.postgresql.org</email> so that the deficiency can be addressed. PostgreSQL 8.3から、SQL/XML標準に基づくXML関連の機能はコアサーバ内に存在します。 その機能は、XML構文検査、XPath問い合わせなど本モジュールが行なうことと同等のこととそれ以上のことを範囲としますが、APIには互換性はありません。 新しい標準APIのため、本モジュールは今後のバージョンのPostgreSQLで削除される予定ですので、アプリケーションの変換が推奨されています。 本モジュールの機能に新しいAPIに適用できないものがあることが分かった場合、その不足に取り組むことができるようににその問題を表明してください。

F.48.2. 関数の説明 #

<title>Description of Functions</title>

<xref linkend="xml2-functions-table"/> shows the functions provided by this module. These functions provide straightforward XML parsing and XPath queries. 表 F.35に本モジュールで提供する関数を示します。 これらの関数は簡単なXML解析とXPath問い合わせを提供します。

表F.35 xml2関数

<title><filename>xml2</filename> Functions</title>

Function 関数

Description 説明

xml_valid ( document text ) → boolean

Parses the given document and returns true if the document is well-formed XML. (Note: this is an alias for the standard PostgreSQL function <function>xml_is_well_formed()</function>. The name <function>xml_valid()</function> is technically incorrect since validity and well-formedness have different meanings in XML.) 与えられた文書を解析し、文書が整形式のXMLであれば真を返します。 (注意:これは標準のPostgreSQL関数xml_is_well_formed()の別名です。 XMLでは整形と検証が異なる意味を持つため、xml_valid()と言う名前は技術的には正しくありません。)

xpath_string ( document text, query text ) → text

Evaluates the XPath query on the supplied document, and casts the result to <type>text</type>. 与えられた文書に対するXPath問い合わせを評価し、結果をtextにキャストします。

xpath_number ( document text, query text ) → real

Evaluates the XPath query on the supplied document, and casts the result to <type>real</type>. 与えられた文書に対するXPath問い合わせを評価し、結果をrealにキャストします。

xpath_bool ( document text, query text ) → boolean

Evaluates the XPath query on the supplied document, and casts the result to <type>boolean</type>. 与えられた文書に対するXPath問い合わせを評価し、結果をbooleanにキャストします。

xpath_nodeset ( document text, query text, toptag text, itemtag text ) → text

Evaluates the query on the document and wraps the result in XML tags. If the result is multivalued, the output will look like: 文書に対する問い合わせを評価し、XMLタグ内に結果を包みます。 結果が複数の値であれば、出力は以下のようになります。

<toptag>
<itemtag>Value 1 which could be an XML fragment</itemtag>
<itemtag>Value 2....</itemtag>
</toptag>

If either <parameter>toptag</parameter> or <parameter>itemtag</parameter> is an empty string, the relevant tag is omitted. toptagまたはitemtagが空文字だった場合、対応するタグは省略されます。

xpath_nodeset ( document text, query text, itemtag text ) → text

Like <function>xpath_nodeset(document, query, toptag, itemtag)</function> but result omits <parameter>toptag</parameter>. xpath_nodeset(document, query, toptag, itemtag)と同様ですが、結果はtoptagを省きます。

xpath_nodeset ( document text, query text ) → text

Like <function>xpath_nodeset(document, query, toptag, itemtag)</function> but result omits both tags. xpath_nodeset(document, query, toptag, itemtag)と同様ですが、結果は両方のタグを省きます。

xpath_list ( document text, query text, separator text ) → text

Evaluates the query on the document and returns multiple values separated by the specified separator, for example <literal>Value 1,Value 2,Value 3</literal> if <parameter>separator</parameter> is <literal>,</literal>. 文書に対する問い合わせを評価し、複数の値を指定した区切り文字で区切って返します。 例えば、separator,ならばValue 1,Value 2,Value 3となります。

xpath_list ( document text, query text ) → text

This is a wrapper for the above function that uses <literal>,</literal> as the separator. これは、,を区切り文字として使用する、上の関数のラッパーです。


F.48.3. xpath_table #

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

<function>xpath_table</function> is a table function that evaluates a set of XPath queries on each of a set of documents and returns the results as a table. The primary key field from the original document table is returned as the first column of the result so that the result set can readily be used in joins. The parameters are described in <xref linkend="xml2-xpath-table-parameters"/>. xpath_tableは各文書集合に対するXPath問い合わせ集合を評価し、結果をテーブルとして返すテーブル関数です。 元文書テーブルの主キーフィールドが結果の第一列として返されますので、結果セットを容易に結合で使用することができます。 パラメータについては表 F.36で説明します。

表F.36 xpath_tableのパラメータ

<title><function>xpath_table</function> Parameters</title>
パラメータ説明
key

the name of the <quote>key</quote> field &mdash; this is just a field to be used as the first column of the output table, i.e., it identifies the record from which each output row came (see note below about multiple values) keyフィールドの名前です。 これは、出力テーブルの第一列として使用される単なるフィールドです。 つまり、これは各出力行の出現元を識別するレコードです。 (後述の複数値に関する注記を参照してください。)

document

the name of the field containing the XML document XML文書を含むフィールドの名前です。

relation

the name of the table or view containing the documents 文書を含むテーブルまたはビューの名前です。

xpaths

one or more XPath expressions, separated by <literal>|</literal> |で区切られた、1つ以上のXPath式です。

criteria

the contents of the WHERE clause. This cannot be omitted, so use <literal>true</literal> or <literal>1=1</literal> if you want to process all the rows in the relation WHERE句の内容です。 これは省略することができません。 リレーション内の全行を処理したい場合はtrueまたは1=1を使用してください。


These parameters (except the XPath strings) are just substituted into a plain SQL SELECT statement, so you have some flexibility &mdash; the statement is (XPath文字列を除く)これらのパラメータは普通のSQL SELECT 文に単純に置換されます。 このため、多少の柔軟性があります。

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

so those parameters can be <emphasis>anything</emphasis> valid in those particular locations. The result from this SELECT needs to return exactly two columns (which it will unless you try to list multiple fields for key or document). Beware that this simplistic approach requires that you validate any user-supplied values to avoid SQL injection attacks. 文は上の通りですので、これらのパラメータにはそれぞれの場所で有効なものであれば何でもよいわけです。 このSELECTの結果は正確に2つの列を返さなければなりません(キーまたは文書に対して複数のフィールドを列挙させようとしない限りです)。 この簡略された手法では、SQLインジェクション攻撃を防ぐためにユーザから与えられた値をすべて検証しなければならないことに注意してください。

The function has to be used in a <literal>FROM</literal> expression, with an <literal>AS</literal> clause to specify the output columns; for example この関数は、出力列を指定するためのAS句を付けたFROM式内で使用されなければなりません。 以下に例を示します。

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);

The <literal>AS</literal> clause defines the names and types of the columns in the output table. The first is the <quote>key</quote> field and the rest correspond to the XPath queries. If there are more XPath queries than result columns, the extra queries will be ignored. If there are more result columns than XPath queries, the extra columns will be NULL. このAS句は、出力テーブルの列名とその型を定義します。 先頭がkeyフィールド、残りがXPath問い合わせに対応します。 結果列より多くのXPath問い合わせが存在する場合、余った問い合わせは無視されます。 XPath問い合わせより多くの結果列が存在する場合は余った列はNULLになります。

Notice that this example defines the <structname>page_count</structname> result column as an integer. The function deals internally with string representations, so when you say you want an integer in the output, it will take the string representation of the XPath result and use PostgreSQL input functions to transform it into an integer (or whatever type the <type>AS</type> clause requests). An error will result if it can't do this &mdash; for example if the result is empty &mdash; so you may wish to just stick to <type>text</type> as the column type if you think your data has any problems. この例でpage_count結果列が整数として定義されていることに注意してください。 関数は内部的に文字列表現で扱います。 このため、出力内で整数で扱いたいと言っている時、XPath結果の文字列表現を取り出し、整数(またはAS句で要求した任意の型)に変換するためにPostgreSQLの入力関数を使用します。 例えば結果が空など、変換できない場合はエラーになります。 ですので、データに何らかの問題があると考えられる場合、列型としてtextに限定する方がよいかもしれません。

The calling <command>SELECT</command> statement doesn't necessarily have to be just <literal>SELECT *</literal> &mdash; it can reference the output columns by name or join them to other tables. The function produces a virtual table with which you can perform any operation you wish (e.g., aggregation, joining, sorting etc.). So we could also have: 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;

as a more complicated example. Of course, you could wrap all of this in a view for convenience. 当然ながら、簡便にするためにこれをすべてビューとして包み隠すことができます。

F.48.3.1. 複数値の結果 #

<title>Multivalued Results</title>

The <function>xpath_table</function> function assumes that the results of each XPath query might be multivalued, so the number of rows returned by the function may not be the same as the number of input documents. The first row returned contains the first result from each query, the second row the second result from each query. If one of the queries has fewer values than the others, null values will be returned instead. xpath_table関数は各XPath問い合わせの結果が複数の値を持つ可能性があることを前提としています。 このため、この関数が返す行数は入力文書の数と同じにならない可能性があります。 返される最初の行には各問い合わせの最初の結果が、2番目の行には各問い合わせの2番目の結果が含まれます。 問い合わせの1つが他よりも少ない値を持つ場合は代わりにNULL値が返されます。

In some cases, a user will know that a given XPath query will return only a single result (perhaps a unique document identifier) &mdash; if used alongside an XPath query returning multiple results, the single-valued result will appear only on the first row of the result. The solution to this is to use the key field as part of a join against a simpler XPath query. As an example: 指定した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

To get <literal>doc_num</literal> on every line, the solution is to use two invocations of <function>xpath_table</function> and join the results: 各行にdoc_numを付けるためには、2つの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)

F.48.4. XSLT関数 #

<title>XSLT Functions</title>

The following functions are available if libxslt is installed: libxsltがインストールされている場合、以下の関数を使用することができます。

F.48.4.1. xslt_process #

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

This function applies the XSL stylesheet to the document and returns the transformed result. The <literal>paramlist</literal> is a list of parameter assignments to be used in the transformation, specified in the form <literal>a=1,b=2</literal>. Note that the parameter parsing is very simple-minded: parameter values cannot contain commas! この関数はXSLスタイルシートを文書に適用し、変換した結果を返します。 paramlistは、a=1,b=2という形で指定された、変換で使用されるパラメータ代入式のリストです。 パラメータ解析はあまり熟考されたものではないことに注意してください。パラメータ値にカンマを入れることができません。

There is also a two-parameter version of <function>xslt_process</function> which does not pass any parameters to the transformation. また、変換用のパラメータを渡さない、2つのパラメータを取るバージョンのxslt_processも存在します。

F.48.5. 作者 #

<title>Author</title>

John Gray

Development of this module was sponsored by Torchbox Ltd. (www.torchbox.com). It has the same BSD license as PostgreSQL. 本モジュールの開発はTorchbox Ltd. (www.torchbox.com)が後援しました。 PostgreSQLと同じBSDライセンスです。