他のバージョンの文書 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

F.23. ltree

本モジュールは階層ツリーを模擬した構造に格納されたデータのラベルを表現する ltreeデータ型を実装します。 ラベルツリー全体を検索する高度な機能を提供します。

このモジュールはtrustedと見なされます。つまり、現在のデータベースに対してCREATE権限を持つ非スーパーユーザがインストールできます。

F.23.1. 定義

ラベルは、アルファベット文字とアンダースコア(例えばCロケールではA-Za-z0-9_文字が許されます。)の並びです。 ラベルの長さは256文字未満でなければなりません。

例えば42Personal_Servicesです。

ラベル経路は、例えばL1.L2.L3のようなドットで区切られた0個以上のラベルの並びであり、階層ツリーのルートから特定のノードまでの経路を表します。 ラベル経路の長さは65535ラベルを超えることはできません。

例:'Top.Countries.Europe.Russia'

ltreeモジュールは以下の複数のデータ型を提供します。

  • ltreeはラベル経路を格納します。

  • lqueryは、ltree値に一致する正規表現のようなパターンを表現します。 単一の単語は経路内のラベルに一致します。 スター記号(*)は0個以上のラベルに一致します。 ドットでつなげることで、ラベル経路全体に一致するパターンを形作ることができます。 以下に例を示します。

    
    foo         正確にfooというラベル経路に一致します。
    *.foo.*     fooというラベルを含むラベル経路すべてに一致します。
    *.foo       fooというラベルで終わるラベル経路すべてに一致します。
    

    スター記号と単一の単語のどちらも一致可能なラベル数を制限するために量指定を行うことができます。

    
    *{n}        正確にn個のラベルに一致します。
    *{n,}       少なくともn個のラベルに一致します。
    *{n,m}      少なくともn個に一致し、多くてもm個を超えないラベルに一致します。
    *{,m}       最大m個のラベルに一致します。つまりと次と同じです。*{0,m}
    foo{n,m}    少なくともn個に一致し、多くてもm個を超えないfooに一致します。
    foo{,}      ゼロを含む任意の数のfooに一致します。
    

    明示的な量指定子が存在しなければ、スター記号に対するデフォルトは任意の数のラベルに一致(つまり{,})である一方、非スター項目に対するデフォルトは正確に1回(つまり{1})です。

    単なる正確な一致以上の一致を行うために、スターでないlquery項目の終端に記述できる複数の修飾子が存在します。

    
    @           大文字小文字を区別しない一致。例えばa@Aに一致します。
    *           この接頭辞を持つすべてのラベルに一致。例えばfoo*foobarに一致します。
    %           最初のアンダースコアで区切られた単語に一致。
    

    %の動作は多少複雑です。 ラベル全体ではなく単語一致を試みます。 例えばfoo_bar%foo_bar_bazに一致しますがfoo_barbazに一致しません。 *と組み合わせる場合、接頭辞一致が各単語ごとに適用されます。 例えばfoo_bar%*foo1_bar2_bazに一致しますが、foo1_br2_bazに一致しません。

    また、項目のいずれかに一致させるために|(論理和)で区切って、修飾子が付いているかもしれない複数の非スター項目を記述することもできます。 さらに、非スターグループ先頭に! (否定)を記述して選択肢のいずれにも一致しないすべてのラベルに一致させることもできます。 もしあれば、量指定子はグループの最後になります。これはグループ全体として一致する数を意味します(すなわち、一致するラベルの数、または、選択肢のいずれにも一致しない数です)。

    以下に注釈付きのlqueryの例を示します。

    Top.*{0,2}.sport*@.!football|tennis{1,}.Russ*|Spain
    a.  b.     c.      d.                   e.
    

    この問い合わせは以下のようなラベルに一致します。

    1. Topラベルから始まる。

    2. 次いで0から2個のラベルを持つ。

    3. 直後にsport接頭辞(大文字小文字の区別無)から始まるラベルを持つ。

    4. そして、footballにもtennisにも一致しない1つ以上のラベルを持つ。

    5. Russから始まる、または、正確にSpainに一致するラベルで終わる。

  • ltxtqueryltree値に対する全文検索のようなパターンを表します。 ltxtquery値は、おそらく最後に@*%修飾子を持った単語からなります。 修飾子の意味はlqueryと同じです。 単語は& (論理積)、| (論理和)、! (否定)、括弧を組み合わせることが可能です。 主なlqueryとの違いは、ltxtqueryはラベル経路上の位置を考慮せずに単語に一致することです。

    ltxtqueryの例を示します。

    Europe & Russia*@ & !Transportation
    

    これはEuropeラベルとRussia(大文字小文字の区別無)から始まるラベルを含む経路に一致します。 しかし、Transportationラベルを含む経路は一致しません。 経路内の単語の位置は重要ではありません。 また、%が使用された場合、位置に関係なく、単語をラベル内のアンダースコアで区切られた何らかの単語に一致させることができます。

注意:ltxtqueryではシンボルの間に空白を入れることができますが、ltreelqueryではできません。

F.23.2. 演算子と関数

ltree型は、通常の比較演算子=<><><=>=を持ちます。 比較では、ツリーの巡回順でソートされ、ノードの子要素はラベルテキストでソートされます。 さらに、表 F.13に示す特殊な演算子が使用可能です。

表F.13 ltree演算子

演算子

説明

ltree @> ltreeboolean

左辺の引数が右辺の祖先要素(か同じ)かどうか。

ltree <@ ltreeboolean

左辺の引数が右辺の子孫要素(か同じ)かどうか。

ltree ~ lqueryboolean

lquery ~ ltreeboolean

ltreelqueryに一致するかどうか。

ltree ? lquery[]boolean

lquery[] ? ltreeboolean

ltreeが配列内のいずれかのlqueryに一致するかどうか。

ltree @ ltxtqueryboolean

ltxtquery @ ltreeboolean

ltreeltxtqueryに一致するかどうか。

ltree || ltreeltree

ltree経路を連結します。

ltree || textltree

text || ltreeltree

テキストをltreeに変換し、連結します。

ltree[] @> ltreeboolean

ltree <@ ltree[]boolean

配列にltreeの祖先要素が含まれるかどうか。

ltree[] <@ ltreeboolean

ltree @> ltree[]boolean

配列にltreeの子孫要素が含まれるかどうか。

ltree[] ~ lqueryboolean

lquery ~ ltree[]boolean

配列にlqueryに一致する経路が含まれるかどうか。

ltree[] ? lquery[]boolean

lquery[] ? ltree[]boolean

ltree配列にいずれかのlqueryに一致する経路が含まれるかどうか。

ltree[] @ ltxtqueryboolean

ltxtquery @ ltree[]boolean

配列にltxtqueryに一致する経路が含まれるかどうか。

ltree[] ?@> ltreeltree

ltreeの祖先要素となる配列内の最初の要素を、存在しなければNULLを返します。

ltree[] ?<@ ltreeltree

ltreeの子孫要素となる配列内の最初の要素を、存在しなければNULLを返します。

ltree[] ?~ lqueryltree

lqueryに一致する配列内の最初の要素を、存在しなければNULLを返します。

ltree[] ?@ ltxtqueryltree

ltxtqueryに一致する配列内の最初の要素を、存在しなければNULLを返します。


演算子<@@>@~には類似の演算子^<@^@>^@^~があります。 後者はインデックスを使用しない点を除き、同一です。 後者は試験の際にだけ役に立ちます。

使用可能な関数を表 F.14に示します。

表F.14 ltree関数

関数

説明

subltree ( ltree, start integer, end integer ) → ltree

start位置からend-1位置までのltreeの部分経路を返します(位置は0から始まります)。

subltree('Top.Child1.Child2', 1, 2)Child1

subpath ( ltree, offset integer, len integer ) → ltree

offset位置からlen個のltreeの部分経路を返します。 offsetが負の場合、部分経路は経路の終端から数えた位置から始まります。 lenが負の場合、経路の終端から指定個のラベルを除きます。

subpath('Top.Child1.Child2', 0, 2)Top.Child1

subpath ( ltree, offset integer ) → ltree

offset位置から経路の終端までのltreeの部分経路を返します。 offsetが負の場合、部分経路は経路の終端から数えた位置から始まります。

subpath('Top.Child1.Child2', 1)Child1.Child2

nlevel ( ltree ) → integer

経路内のラベル数を返します。

nlevel('Top.Child1.Child2')3

index ( a ltree, b ltree ) → integer

a内でbが最初に出現する位置を、存在しなければ-1を返します。

index('0.1.2.3.5.4.5.6.8.5.6.8', '5.6')6

index ( a ltree, b ltree, offset integer ) → integer

a内でbが最初に出現する位置を、存在しなければ-1を返します。 検索はoffsetから始まります。負のoffsetは経路終端から-offsetラベルから検索を始めることを意味します。

index('0.1.2.3.5.4.5.6.8.5.6.8', '5.6', -4)9

text2ltree ( text ) → ltree

textltreeにキャストします。

ltree2text ( ltree ) → text

ltreetextにキャストします。

lca ( ltree [, ltree [, ... ]] ) → ltree

経路で共通する最長接頭辞を計算します(最大8個の引数をサポートします)。

lca('1.2.3', '1.2.3.4.5.6')1.2

lca ( ltree[] ) → ltree

配列内の経路で共通する最長接頭辞を計算します。

lca(array['1.2.3'::ltree,'1.2.3.4'])1.2


F.23.3. インデックス

ltreeは、以下で示された演算子を高速化できる、複数種類のインデックスをサポートします。

  • ltreeに対するB-treeインデックス:<<==>=>

  • ltreeに対するGiSTインデックス(gist_ltree_ops演算子クラス): <<==>=>@><@@~?

    gist_ltree_ops GiST演算子クラスは経路ラベルの集合をビットマップ署名として近似します。 オプションの整数パラメータsiglenは、署名の長さをバイト単位で決定します。 デフォルトの署名の長さは8バイトです。 長さは、int整列(ほとんどのマシンで4バイト)の正の倍数であり、最大で2024であることが必要です。 長い署名では、インデックスはより大きくなってしまいますが、(インデックスのより小さな部分とより少ないヒープページを走査することで)検索がより正確になります。

    デフォルトの署名の長さが8バイトのインデックスを作成する例。

    CREATE INDEX path_gist_idx ON test USING GIST (path);
    

    署名の長さが100バイトのインデックスを作成する例。

    CREATE INDEX path_gist_idx ON test USING GIST (path gist_ltree_ops(siglen=100));
    
  • ltree[]に対するGiSTインデックス(gist__ltree_ops演算子クラス):ltree[] <@ ltreeltree @> ltree[]@~?

    gist__ltree_ops GiST演算子クラスはgist_ltree_opsと同じように動作しますが、署名の長さをパラメータとして取ります。 gist__ltree_opsでのsiglenのデフォルトの値は28バイトです。

    デフォルトの署名の長さが28バイトのインデックスを作成する例。

    CREATE INDEX path_gist_idx ON test USING GIST (array_path);
    

    署名の長さが100バイトのインデックスを作成する例。

    CREATE INDEX path_gist_idx ON test USING GIST (array_path gist__ltree_ops(siglen=100));
    

    注意:この種類のインデックスは非可逆です。

F.23.4. 例

この例は、後述のデータを使用します(ソース配布内のcontrib/ltree/ltreetest.sqlファイルでも利用可能です)。

CREATE TABLE test (path ltree);
INSERT INTO test VALUES ('Top');
INSERT INTO test VALUES ('Top.Science');
INSERT INTO test VALUES ('Top.Science.Astronomy');
INSERT INTO test VALUES ('Top.Science.Astronomy.Astrophysics');
INSERT INTO test VALUES ('Top.Science.Astronomy.Cosmology');
INSERT INTO test VALUES ('Top.Hobbies');
INSERT INTO test VALUES ('Top.Hobbies.Amateurs_Astronomy');
INSERT INTO test VALUES ('Top.Collections');
INSERT INTO test VALUES ('Top.Collections.Pictures');
INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy');
INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Stars');
INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Galaxies');
INSERT INTO test VALUES ('Top.Collections.Pictures.Astronomy.Astronauts');
CREATE INDEX path_gist_idx ON test USING GIST (path);
CREATE INDEX path_idx ON test USING BTREE (path);

これで、以下の階層を記述するデータが投入されたtestテーブルができます。

                        Top
                     /   |  \
             Science Hobbies Collections
                 /       |              \
        Astronomy   Amateurs_Astronomy Pictures
           /  \                            |
Astrophysics  Cosmology                Astronomy
                                        /  |    \
                                 Galaxies Stars Astronauts

継承を行うことができます。

ltreetest=> SELECT path FROM test WHERE path <@ 'Top.Science';
                path
------------------------------------
 Top.Science
 Top.Science.Astronomy
 Top.Science.Astronomy.Astrophysics
 Top.Science.Astronomy.Cosmology
(4 rows)

経路一致の例をいくつか示します。

ltreetest=> SELECT path FROM test WHERE path ~ '*.Astronomy.*';
                     path
-----------------------------------------------
 Top.Science.Astronomy
 Top.Science.Astronomy.Astrophysics
 Top.Science.Astronomy.Cosmology
 Top.Collections.Pictures.Astronomy
 Top.Collections.Pictures.Astronomy.Stars
 Top.Collections.Pictures.Astronomy.Galaxies
 Top.Collections.Pictures.Astronomy.Astronauts
(7 rows)

ltreetest=> SELECT path FROM test WHERE path ~ '*.!pictures@.Astronomy.*';
                path
------------------------------------
 Top.Science.Astronomy
 Top.Science.Astronomy.Astrophysics
 Top.Science.Astronomy.Cosmology
(3 rows)

全文検索の例をいくつか示します。

ltreetest=> SELECT path FROM test WHERE path @ 'Astro*% & !pictures@';
                path
------------------------------------
 Top.Science.Astronomy
 Top.Science.Astronomy.Astrophysics
 Top.Science.Astronomy.Cosmology
 Top.Hobbies.Amateurs_Astronomy
(4 rows)

ltreetest=> SELECT path FROM test WHERE path @ 'Astro* & !pictures@';
                path
------------------------------------
 Top.Science.Astronomy
 Top.Science.Astronomy.Astrophysics
 Top.Science.Astronomy.Cosmology
(3 rows)

関数を使用した経路構築の例です。

ltreetest=> SELECT subpath(path,0,2)||'Space'||subpath(path,2) FROM test WHERE path <@ 'Top.Science.Astronomy';
                 ?column?
------------------------------------------
 Top.Science.Space.Astronomy
 Top.Science.Space.Astronomy.Astrophysics
 Top.Science.Space.Astronomy.Cosmology
(3 rows)

経路内の位置にラベルを挿入するSQL関数を作成することで、これを簡略化することができます。

CREATE FUNCTION ins_label(ltree, int, text) RETURNS ltree
    AS 'select subpath($1,0,$2) || $3 || subpath($1,$2);'
    LANGUAGE SQL IMMUTABLE;

ltreetest=> SELECT ins_label(path,2,'Space') FROM test WHERE path <@ 'Top.Science.Astronomy';
                ins_label
------------------------------------------
 Top.Science.Space.Astronomy
 Top.Science.Space.Astronomy.Astrophysics
 Top.Science.Space.Astronomy.Cosmology
(3 rows)

F.23.5. 変換

ltree_plpython3u拡張は、PL/Python用のltree型の変換を実装します。 関数を作成するときにこの変換をインストールして指定していれば、ltreeの値はPythonのリストにマップされます。 (しかしながら、その逆は今のところサポートされていません。)

注意

変換の拡張はltreeと同じスキーマにインストールすることを強く勧めます。 さもないと、変換の拡張のスキーマが悪意のあるユーザにより定義されたオブジェクトを含んでいた場合に、インストール時のセキュリティ問題になります。

F.23.6. 作者

開発はすべてTeodor Sigaev ()とOleg Bartunov ()によりなされました。 さらなる情報についてはhttp://www.sai.msu.su/~megera/postgres/gist/を参照してください。 作者は有用な議論を行ったEugeny Rodichevに感謝しています。 コメントや不具合報告を歓迎します。