定数

次の例のように、式を、Integer、Float、または String 型の定数にすることができます。

select 'positive' as polarity

この式は、ストリング定数 positive です。

列参照

次の例のように、式を列参照にすることができます。

create view Person as
select F.name as firstname, L.name as lastname
from FirstName F, LastName L
where FollowsTok(F.name, L.name, 0, 0);

このビューは、個人のフルネームとして解釈できるテキストを識別します (例えば、「Samuel Davis」や「Vicky Rosenberg」など)。 式 F.name および L.name は、それぞれ、ビュー F および L の名前列を返す列参照式です。 from ステートメントは、ビュー F と L をビュー FirstName と LastName のローカル名として定義します (この例では、有効な名と姓を定義しますが、表示されません)。

スカラー関数呼び出し

1 つ以上のスカラー関数呼び出しで式を構成できます。各スカラー関数呼び出しには、同様に定数、列参照、またはスカラー関数呼び出しのタイプの式である引数を含めることができます。 スカラー関数呼び出しは、組み込みのスカラー関数のいずれかにすることも、スカラー・ユーザー定義関数にすることもできます。 次の例を考えてみましょう：

create view FamilyMembers as
    select ToLowerCase(GetText(P.lastname)) as lastname, List( (GetText(P.firstname))) as firstnames
    from Person P
    group by GetText(P.lastname);

このビューは、同じ姓を持つ人をグループ化することによって、潜在的なファミリー・メンバーを識別します。姓を小文字として、すべての名前を出力します (例: lastname keaton, firstnames (Elyse, Alex, Diane))。 GetText 関数呼び出しの出力は、名前が小文字で表示される ToLowerCase 関数呼び出しの引数として使用されます。 この例の scalar 関数呼び出しの式は、ToLowerCase、(GetText(P.lastname)、ToLowerCase(GetText(P.firstname))、および GetText(P.lastname) です。

集約関数呼び出し

式を集約関数呼び出しにすることができます。 このタイプの式では、列参照タイプまたはスカラー関数呼び出しタイプの別の式を引数として取ることができます。 以下の例は、列参照タイプの式を持つ集約関数呼び出しです。

create view CountLastNames as
select Count(Person.lastname)
from Person;

この式はシンプルに Count(Person.lastname) という式であり、文書内の Person.lastname アノテーションの数をカウントします。 スカラー関数呼び出しタイプの式を持つ集約関数呼び出しの例は、名のリストを生成するための引数として List(GetText(P.firstname)) スカラー関数を取る List 集約関数を持つ GetText として前の例の中にあります。 集約関数呼び出しの式は、select ステートメントの select リストの式としてのみ使用できます。 集約関数呼び出しの式は、select ステートメントの extract リストで使用することも、スカラー関数呼び出しまたは集約関数呼び出しの引数として使用することもできません。

Documentビュー

AQL モジュール・レベルでは、Document ビューは、そのモジュールによってアノテーションが付けられている現在の文書を表す特殊ビューです。 複数のモジュールが 1 つの抽出プログラムを形成するように結合されると、すべてのモジュールの Document スキーマの重複のない和集合が、必要な Document ビューになります。 require document with columns ビューのスキーマを指定するには、Document ステートメントを使用します。 このステートメントがモジュールに存在しない場合、Document ビューに想定されるデフォルトのスキーマは、(text Text, label Text) です。

• テキスト

  現在の文書のテキストの内容。

• ラベル

  アノテーションが付けられている現行の文書のラベル。

キーワード Document は、Document ビューの ID として予約されており、実行中に自動的に取り込まれます。 したがって、同じ名前の別のビューまたは表を定義することはできません。 ただし、Document という語は、属性名および別名の ID として使用できます。

構文

module <module-name\>;

説明

• <module-name\>

  現行ファイルが<module-name\>という名前のモジュールの一部であることを宣言します。 モジュール名は単純な ID である必要があります。 二重引用符付き ID はモジュール名としては使用できません。

  モジュール内の各 AQL ファイルにはモジュール宣言が 1 つのみ必要です。この宣言は、各ファイルの最初のステートメントである必要があります。 この宣言は、モジュール名と同じ名前空間を確立します。 このモジュール内の AQL ファイルで宣言されたすべてのビュー (および辞書、表、関数などのその他のオブジェクト) は、この 1 つの名前空間内にあります。 この名前空間内のすべての AQL ファイルからアクセス可能です。

  モジュール <module-name\>の一部として宣言されるすべてのファイルは、この名前空間を適用するための<module-name\>という名前のフォルダー内にある必要があります。 このモジュール・フォルダー内の AQL ファイルの順序付けはありません。 AQL コンパイラーは、モジュールのすべての AQL ファイルを調べ、モジュール内で宣言されたすべてのビュー、辞書、表、および関数をコンパイルするための正しい順序を決定します。

使用上の注意

• 基礎となる AQL ファイルがモジュール (モジュラー AQL ファイル) の一部として検出されず、互換モードでコンパイルされる場合、このステートメントはサポートされません。
• ビュー間の循環依存関係は許可されません。
• AQL モジュールは、サブモジュールをサポートしません。
• 最上位モジュール・フォルダーのサブフォルダー内の AQL ファイルは無視されます。

例

例 1: サンプル・モジュール

次の例では、ビュー TheMentions は sample という名前のモジュールに属しています。

module sample;

create dictionary GetTheDict as ('The', 'the');

create view TheMentions as
  extract dictionary 'GetTheDict' on D.text as theMention
  from Document D;

構文

export view|dictionary|table|function <object-name\>;

説明

• view|dictionary|table|function

  エクスポートするオブジェクトのタイプを定義します。 オブジェクト・タイプは、ビュー、辞書、表、または関数にすることができます。

• <object-name\>

  エクスポートするオブジェクトの名前を定義します。 <object-name\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。

使用上の注意

• インポートされた AQL オブジェクトはいずれもエクスポートできません。 新しいビューを作成することによって、現行モジュール内のビューまたは表を再エクスポートする効果を出すことができます。

  select * from <imported_view_name_or_table_name>;
  

• 例に示されている export view ステートメントと output view ステートメントは、互いに別のものです。 つまり、出力ビューは、自動的に、エクスポートされたビューになることはなく、export ステートメントを使用して明示的にエクスポートする必要があります。 エクスポートされたビューは、自動的に出力ビューになることはなく、output view ステートメントを使用して明示的に出力する必要があります。 例では、export ステートメントで、インポートされたビューであるビュー PersonName.FirstName のエクスポートを試行しています。 この試行によりエラーが発生します。これは、開発者がその代わりに、インポートしたビューを新しいビューにコピーしてから、エクスポートする必要があることを意味します。

例

例 1: ビューおよび辞書を作成してから、それらを他のモジュールで使用できるようにエクスポートする

この例では、ビュー FirstName および NotFirstName を作成します。 ビュー FirstName は、FirstNamesDictionary 辞書に表示される名に関する情報を収集します。 もう 1 つのビューは、名を除外したときに残る名前を収集します。 2 つの辞書は、テキスト抽出を容易にするために必要です。 1 つの辞書には、検索する名がすべて含まれています。 2 つ目の辞書 LastNamesDictionary には、検索する姓が含まれています。 他のモジュールで使用できるように、FirstNamesDictionary 辞書がエクスポートされます。 FirstName ビューおよび NotFirstName ビューもエクスポートされ、例 2 のモジュール person などの他のモジュールでインポートして、使用することができます。

module personName;

create dictionary FirstNamesDictionary as
('Smith', 'John', 'Mary', 'Sam', 'George');

-- export dictionary statement

export dictionary FirstNamesDictionary;


create view FirstName as
  extract dictionary 'FirstNamesDictionary'
  on D.text as firstName
from Document D;

-- export view statement

export view FirstName;

create dictionary LastNamesDictionary as
('Stewart', 'Johnson', 'Smith', 'Hopkins', 'George');

create view NotFirstName as
  select F.firstName as notFirstName from FirstName F
  where ContainsDict('LastNamesDictionary', F.firstName);

-- export view statement

export view NotFirstName;

例 2: 使用するビューをインポートするが、不適切にエクスポートするとエラーが発生する

この例は、2 つのビューのインポートを示しています。 これらのビューは、例1内のモジュール personName からエクスポートされました。 モジュール担当者は、これらのビューをインポートして参照できるようになりました。 ただし、このモジュールで、インポートされた同じビュー (FirstName) のエクスポートを試行します。これにより、エラーが発生します。

module person;

-- Form 1

import view FirstName from module personName as PersonFirstName;

-- Form 2

import view NotFirstName from module personName;


-- ERROR
-- Reason: A view that is imported from one module
-- cannot be exported in the current module.
export view personName.FirstName;


output view PersonFirstName;

このコードのエラーの理由は、あるモジュールからインポートされたビューは、現行モジュールではエクスポートできないことです。 さらに、output view ステートメントで出力ビューを定義していない限り、エクスポートされたビューは、自動的に出力ビューになることはありません。

構文

import view|dictionary|table|function <object-name\>
     from module <module-name\> [as <alias\>];

説明

• view\|dictionary\|table\|function

  インポートする AQL オブジェクトのタイプを識別します。 オブジェクトのタイプは必須です。

• <object-name\>

  <object-name\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。

• <module-name\>

  <module-name\>は単純なIDでなければなりません。

• <alias\>

  この形式のインポート・ステートメント（alias importとも呼ばれる）は、指定されたAQLオブジェクトを<alias\>の名前で（元の名前ではなく）現行モジュールの名前空間にインポートします。 インポートされた要素は、非修飾別名、または現行モジュール名 (AQL オブジェクトがインポートされたモジュール) で修飾された別名を使用して参照できます。 alias import ステートメントは、修飾された元の名前ではなく、別名でのみ要素をインポートするため、originalModule.elementName を使用することはできません。

使用上の注意

• 別名を指定せずに import ステートメントを実行すると、指定された AQL オブジェクトが現行モジュールにインポートされます。 これにより、現在のモジュールで修飾名 <original\_module\_name\>.<object-name\>で定義されているAQLステートメントからAQLオブジェクトにアクセスできるようになります。

• import ステートメントは、現行モジュール以外のモジュールから AQL オブジェクトをインポートするためにのみ使用されます。 モジュールの AQL ファイルで宣言されたオブジェクトは、その同じモジュール内の他のすべての AQL ファイルで表示されます。 import ステートメントは、現行ファイルのコンテキストではなく、現行モジュールのコンテキストにオブジェクトを配置します。 したがって、モジュール A 内の 1.aql によってインポートされたビューは、追加の import ステートメントを必要とせずに、同じモジュール内の 2.aql に表示されます。

• すべての import ステートメントは、モジュール宣言の直後に指定する必要があり、他のすべてのタイプのステートメントよりも前に指定する必要があります。 任意のモジュールから明示的にエクスポートされた AQL オブジェクトのみが、別のモジュールにインポートできます。 この要件が順守されていない場合、コンパイル・エラーが発生します。

• import view ステートメントで、同じモジュール内 (現行ファイル内のみではなく) のいずれかの create view ステートメントまたはその他の import ステートメントとの名前競合が発生すると、コンパイル・エラーが発生します。 この制限は、ビューに加えて、他のオブジェクトの import に適用されます。

• AQL コンパイラーは、以前のバージョンの AQL で使用された命名規則に従います。

  • 1 つのモジュールに、同じ名前のビューと表を含めることはできません。
  • 表またはビューと同じ名前の辞書は許可されます。
  • 表、ビュー、または辞書と同じ名前の関数は許可されます。

• モジュール内の 1 つ以上の AQL ファイル内の異なる import ステートメントが、異なる AQL オブジェクトに同じ名前を付けると、コンパイル・エラーが発生します。

• モジュール内の AQL ファイルが、import view ステートメントを使用せずにモジュールの別のエクスポートされたビューを参照しようとすると、コンパイル・エラーが発生します。 同じことが、辞書、表、または関数に適用されます。

• モジュール内の 2 つの AQL ファイルが、別のモジュールから同じビュー X を 2 つの異なる別名 (例えば、A と B) でインポートすると、2 つの別名は同義語として扱われます。 この規則は、表、辞書、および関数にも適用されます。

例

例 1: 他のモジュールにインポートするためにエクスポートするビューの作成

この例では、FirstName および NotFirstName の 2 つのビューを作成します。 ビュー FirstName は、FirstNamesDictionary 辞書に表示される名に関する情報を収集します。 2 つ目のビューは、名を除外したときに残る名前を収集します。 2 つの辞書は、テキスト抽出を容易にするために必要です。 1 つの辞書には、検索する名がすべて含まれています。 2 つ目の辞書 LastNamesDictionary には、検索する姓が含まれています。 FirstName ビューおよび NotFirstName ビューがエクスポートされ、例 2 および 3 のモジュール person などの他のモジュールでインポートして、使用することができます。

module personName;

create dictionary FirstNamesDictionary as
('Smith', 'John', 'Mary', 'Sam', 'George');

create view FirstName as
extract dictionary 'FirstNamesDictionary'
on D.text as firstName
from Document D;

export view FirstName;

create dictionary LastNamesDictionary as
('Stewart', 'Johnson', 'Smith', 'Hopkins', 'George');

create view NotFirstName as
select F.firstName as notFirstName from FirstName F
where ContainsDict('LastNamesDictionary', F.firstName);

export view NotFirstName;

例 2: 別名インポートを使用したビュー FirstName のインポート

この例では、例1で作成され、エクスポートされたビューの1つをインポートします。 次に、PersonFirstNameビューが出力され、その結果を表示できるようになります。

サンプルの import ステートメントは、別名インポートと呼ばれます。 これにより、モジュールの修飾子なしで、ビュー FirstName が現行モジュール person の名前空間にインポートされます。 インポートされたビューには、別名 PersonFirstName を使用した場合のみアクセスできます。他の形式でアクセスすることはできません。 これは別名のみを使用してインポートされたため、例えば、インポートされたビューを personName.FirstName として参照することはできません。

module person;

`import view FirstName from module personName as PersonFirstName;`

output view PersonFirstName;

例 3: 別名インポートを使用しないビュー NotFirstname のインポート

このサンプルの import ステートメントは、修飾名 personName.NotFirstName (ビューの非修飾名ではない) を、現行モジュール person の名前空間にインポートします。 常に修飾名のみを使用して、インポートしたビューを参照します。 その他の参照モードには、コンパイラー・エラーとしてフラグが立てられます。

module person;

`import view NotFirstName from module personName;`


output view personName.NotFirstName;

構文

 import module <module-name\>;

説明

• <module-name\>

  インポートするモジュールを指定します。 <module-name\>は単純なIDでなければなりません。

使用上の注意

• import ステートメントは、現行モジュール以外のモジュールから AQL オブジェクトをインポートするためにのみ使用されます。

• すべての import ステートメントは、モジュール宣言の直後に指定する必要があり、他のすべてのタイプのステートメントよりも前に指定する必要があります。 任意のモジュールから明示的にエクスポートされた AQL オブジェクトのみが、別のモジュールにインポートできます。 この要件が順守されていない場合、コンパイル・エラーが発生します。

• import view ステートメントで、同じモジュール内 (現行ファイル内のみではなく) のいずれかの create view またはその他の import ステートメントとの名前競合が発生すると、コンパイル・エラーが発生します。 この制限は、ビューに加えて、他の AQL オブジェクトの import に適用されます。

• モジュール内の AQL ファイルが、import view ステートメントを使用せずにモジュールの別のエクスポートされたビューを参照しようとすると、コンパイル・エラーが発生します。 同じことが、辞書、表、または関数に適用されます。

• モジュール内の 2 つの AQL ファイルが、別のモジュールから同じビュー X を 2 つの異なる別名 (例えば、A と B) でインポートすると、2 つの別名は同義語として扱われます。 この規則は、表、辞書、および関数にも適用されます。

例

この例では、import ステートメントは、personName.FirstName と personName.NotFirstName の両方のエクスポートされたビューの修飾名をインポートします。 モジュール personName によってエクスポートされないビューは、import ステートメントの一部としてインポートされません。

• 例 1: FirstName と NotFirstName の両方のビューのインポート

  この例では、モジュール personName からエクスポートされたすべてのビューを示します。 ビュー FirstName および NotFirstName は、export ステートメントの例セクションで作成されました。

  module personOther;
  
  -- The following statement would import both views FirstName and NotFirstName.
  import module personName;
  

構文

 set default dictionary language as '<language codes\>';

説明

• <language codes\>

  明示的な with language as の指定なしで宣言された、モジュールの辞書のコンパイルおよびマッチングの言語を指定します。 <language codes\>のセットは、各言語コードの前後に空白文字を入れないコンマ区切りリストでなければなりません。 この要件を順守できないと、コンパイル・エラーが発生する可能性があります。

  このステートメントは、以下の辞書に影響します。

  • create dictionary ステートメントまたは create external dictionary ステートメントを使用して、そのステートメントで with language as 節を指定せずに、現行モジュールで明示的に宣言された辞書。
  • 外部ファイルからの辞書。
  • extract patternステートメントのパターン指定では、'string'型のアトム、および明示的なwith language as指定のない<'string' [match parameters]>型のアトム このステートメントがモジュール内にない場合、ランタイム・コンポーネントはデフォルトで、ドイツ語、スペイン語、英語、フランス語、イタリア語、および指定されていない言語 x の言語セットになります。 これはセット：[de,es,en,fr,it,x_unspecified]として定義されます。 モジュール内には、このステートメントのインスタンスは 1 つしか存在できません。

使用上の注意

• set default dictionary language ステートメントを更新して、抽出プログラムによってカバーされる言語の範囲を改善することができます。 言語を追加するこの機能によって、カスタマイズがさらに容易になり、既存の抽出プログラムを再利用しやすくなります。

例

例 1: 辞書項目のマッチングに使用する言語の指定

module Dictionaries;

-- Set the default dictionary matching language
--  for this module to English and French

set default dictionary language as 'en,fr';


/**
* Dictionary of English and French names. Because no language clause
* exists in dictionary definition, module level dictionary matching
* setting will be applied.
*/

create dictionary EnglishFrenchNames
from file 'en_fr_names.dict';

/**
* Dictionary of Italian names. Language clause in the dictionary
* definition will override the module level dictionary matching setting.
*/

create dictionary ItalianNames
with language as 'it'
as
(
'firstEntry','secondEntry'
);


/**
* View to extract pattern: Phone, followed by one to three tokens,
* followed by Email. Language clause at the atom level will override
* the module level dictionary setting.
*/

create view PhoneEmailPattern as
extract pattern <'Phone'[ with language as 'en']>
  <Token> {1,3} 'Email'
as match
from Document D;

output view PhoneEmailPattern;

構文

require document with columns  <columnName\> <columnType\>
     [and <columnName\> <columnType\>]*;

説明

• <columnName\>

  スキーマで使用される列の名前を指定します。 <columnName\>は属性IDであり、単純IDまたは二重引用符で囲んだIDです。

• <columnType\>

  Document ビューのスキーマで使用される列の型を指定します。 <columnType\>は、Integer、Float、Boolean、またはTextのいずれかのデータ型にすることができます。

• [ and <columnName\> <columnType\> ]*

  Document ビューのスキーマに対する、追加の列の名前と型を指定します。 これらは、<columnName\>および<columnType\>と同じ規則に従います。

以前のバージョンの AQL では、特殊ビュー Document のスキーマは、単一フィールド (text Text) または 2 つのフィールド (text text, label Text) で構成されるように事前定義されていました。 これらのスキーマ間の選択は、実行時に決定されていました。 require document with columns ステートメントを使用することにより、コンパイル時にデフォルトの入力文書スキーマをオーバーライドできます。

使用上の注意

• モジュラー AQL コードの場合、require document with columns ステートメントの有効範囲は、それが定義されているモジュールになります。
• AQL ファイルごとに 1 つの require document with columns ステートメントのみが許可されます。 単一モジュールまたは汎用モジュール内には、require document with columns ステートメントがある 1 つ以上の AQL ファイルを含めることも、含めないこともできます。 モジュール内のすべての AQL ファイルは、モジュール全体のレベルで require document with columns ステートメントをマージして、モジュール全体の require document with columns を形成します。 このステートメントは、そのモジュールの Document ビューのスキーマを定義します。 単一モジュールまたは汎用モジュール内に require ステートメントを含む AQL ファイルがない場合、モジュールでビュー Document のデフォルト・スキーマが使用されます。 このスキーマは、(text Text, label Text) の 2 つの列で構成されます。 モジュール内の少なくとも 1 つの AQL ファイルに 1 つの Document ステートメントがある場合、特殊ビュー require document with columns にデフォルトの列は設定されません。
• 複数のモジュールが 1 つの抽出プログラムを形成するように結合されると、抽出プログラム全体の Document ビューのスキーマは、各モジュールの Document スキーマの重複のない和集合によって定義されます。 複数の require document with columns ステートメントのいずれかの列の型の要件が、モジュール間で競合していることが検出されると、例外が発生します。 例えば、あるモジュールで型 Y の列 X を必要とし、一緒にロードされる別のモジュールで型 Z の列 X を必要とする場合などです。
• 提供された入力文書タプルに必要な列の一部が含まれていない場合、抽出プログラムを実行すると例外が発生します。 列がその対応する必須の型に準拠していない場合にも例外が発生します。
• モジュール内に require document with columns ステートメントが存在する場合、参照される特殊ビュー Document のすべての列が、require document with columns ステートメントの少なくとも 1 つで宣言される必要があります。 このステートメントは、同じモジュール内の別の AQL ファイルにあります。 ただし、そのようなすべての require document with columns ステートメントはモジュールのレベルでマージされ、モジュール全体の require document with columns ステートメントが形成されます。

例

例 1: 同様の列の型を使用した require document ステートメント

次の例は、同じ型の 4 つのフィールドを含む文書スキーマを定義しています。 この AQL サンプルでは、データ収集の各文書タプルに、文書スキーマに定義されている 4 つの列が含まれることを想定しています。

スキーマに準拠する文書の作成方法の詳細については、JSON 文書フォーマットを参照してください。

module person;

-- Require document statement with similar field types

require document with columns
  inputDocumentText Text
  and inputDocumentLabel Text
  and documentAuthor Text
  and documentCreationDate Text;

例 2: さまざまな列の型を使用した require document ステートメント

次のサンプルは、さまざまなフィールドの型の列を含む文書スキーマを定義しています。

module sample;

-- Require document statement with varying field types

require document with columns
  bookText Text
  and purchaseCount Integer
  and bookPrice Float
  and isBookPopular Boolean;

例 3: 文書スキーマのマージ

この例では、ファイル first.aql、last.aql、および socialsecurity.aql を使用する文書スキーマをマージする方法について説明します。

first.aql:
    module person;
    require document with columns firstName Text;


last.aql:
    module person;
    require document with columns lastName Text;


socialsecurity.aql
    module person;
    require document with columns lastName Text
        and socialSecurityNo Integer;

マージされたスキーマは (firstName Text, lastName Text, socialSecurityNo Integer) です。

構文

create view ステートメントには 3 つの形式があります。 最も単純な形式では、単一の select ステートメントまたは extract ステートメントのタプルで構成される論理ビューを定義します。 2 つ目の形式は、複数の select ステートメントまたは extract ステートメントのマルチセットの和集合から生じるタプルで構成されるビューを定義する、複数結合の形式です。 3 つ目の形式では、2 つの select ステートメントまたは extract ステートメントからのタプルの間の集合の差分を含む新しいビューを定義します。

create view <viewname\> as  <select or extract statement\>;

create view <viewname\> as  (<select or extract statement\>) union all (<select or extract statement\>)...;

create view <viewname\> as  (<select or extract statement\>) minus (<select or extract statement\>);

説明

• <viewname\>

  <viewname\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。 ピリオド文字を含めることはできません。

• <select or extract statement\>

  select ステートメントまたは extract ステートメントは、収容ビューのタプルを計算するために使用される出力を作成します。

使用上の注意

• ビュー名は、大／小文字を区別します。 例えば、Person、PERSON、および person は異なるビュー名です。
• 同じ AQL モジュール内の 2 つのビューが 1 つの名前を共有することはできません。共有すると、重複した状態になります。 ただし、2 つの異なるモジュールには、同じ名前の 2 つのビューが存在できます。これは、それぞれの完全修飾名が固有であるためです。
• デフォルトでは、create view ステートメントによって定義されたビューは、出力ビューとして指定されるまで非出力ビューです。
• select と extract の形式の union all ステートメントまたは minus ステートメントには、互換性のある出力スキーマが必要です。 2 つのスキーマは、列の数が同じで、列名が同じ順序で、互換性のあるデータ型の場合に、union または minus の操作に対応していると見なされます。
  • 同じデータ型のフィールドは、union または minus に対応しています。
  • Span と Text のデータ型は、union または minus に対応しています。 Span と Text の型の和集合の場合は、出力タイプは Span です。 ただし、Text 型のオブジェクトが自動的に Span 型に変換されることはありません。自動変換は、関数呼び出しで必要とされる場合にのみ行われます。
  • 基礎となるスカラー型に関係なく、2 つの ScalarLists は、union または minus に対応しています。

例

例 1: select ステートメントまたは extract ステートメントを使用したビューの作成

次の例では、ビュー Phone で、そのタプルを準備するために extract ステートメントが使用されています。 ビュー PhoneNumber で、select ステートメントを使用して、ビュー Phone から特定のフィールドを選択します。

create view Phone as extract
  regexes /\+?([1-9]\d{2}\)\d{3}-\d{4}/
  and /\+?[Xx]\.?\d{4,5}/
  on D.text as num
from Document D;

create view PhoneNumber as
select P.num as num, LeftContextTok(P.num, 3) as lc
from Phone P;

例 2: Union All ステートメントを使用したビューの作成

ビュー AllPhoneNums では、Phone と Extension のビューのタプルから、結合されたセットを準備します。 結合される 2 つのビューは、同じスキーマを持ちます。

create view Phone as
extract
    regex /\+?([1-9]\d{2}\)\d{3}-\d{4}/
    on D.text as match
from Document D;

create view Extension as
  extract
    regex /\+?[Xx]\.?\d{4,5}/
    on D.text as match
from Document D;

create view AllPhoneNums as
  (select P.match from Phone P)
union all
  (select E.match from Extension E);

例 3: Minus ステートメントを使用したビューの作成

次の例は、minus を使用して、タプルのセットから望ましくないタプルを除外する方法を示しています。

create view Organization as
  (select * from OrganizationCandidates)
minus
  (select * from InvalidOrganizations);

例 4: minus のスキーマの互換性

異なるターゲット・テキストに対するスパンが同じ型ではないことに注意することが重要です。 ストリング・リテラルを使用してこの違いを説明する以下の AQL の例を考えてみます。

create view OneString as
  select 'a string' as match
  from Document D;

create view TheSameString as
  select 'a string' as match
  from Document D;

create view Subtraction as
  (select R.match from OneString R)
minus
  (select R.match from TheSameString R);

出力は、予期される空のタプル・リストの出力ではなく、'a string' をフィールド値として持つレコードのセットです。

OneString ビューと TheSameString ビューの内容は同じように見えますが、実際のテキスト値には異なる基礎の AQL オブジェクトがあります。 OneString.match の型は「OneString.match に対する Span」です。 TheSameString.match の型は「TheSameString.match に対する Span」です。 フィールドの型は異なるため、比較の目的には適していません。

空のタプル・リストの必要な出力を取得するには、同じ型の値を比較する必要があります。 次の例では、互換性のある型を GetString() 操作に渡すために、minus 関数でスパン・オブジェクトをストリング・オブジェクトに変換しています。

create view Subtraction as
(select GetString(R.match) from OneString R)
minus
(select GetString(R.match) from TheSameString R);

AQL 文書による create view ステートメントの文書化

create view ステートメントの AQL 文書コメントには、次の情報が含まれます。

• ビューに関する一般的な説明
• ビュー内のすべての列名を表す @field

例

/**
* Extracts all spans that match a phone number pattern from
* the input documents. It uses a regular expression to match
* phone number patterns.
* @field num phone number
* @field lc 3 tokens to the left of phone number*/

create view PhoneNumber as
select P.num as num, LeftContextTok(P.num, 3) as lc
from
(
extract
    regexes /\+?([1-9]\d{2}\)\d{3}-\d{4}/ and /\+?[Xx]\.?\d{4,5}/
    on D.text as num
from Document D
) P;

構文

output view <view-name\> [as '<alias\>'];

説明

• <view-name\>

  出力されるビューの名前。これは、現行モジュールの名前空間で認識されているものです。 <view-name\>は、単純なIDまたは二重引用符で囲んだIDです。 組み込みビュー Document は出力できません。

• [as '<alias\>']*

  出力ビューの<alias\>名を定義します。 オプションの別名が指定されていない場合、ビューは以下の名前で出力されます。

  • モジュラーAQLでは、このビューは<module-name\>.<view-name\>という名前で出力されます。ここで、 <module-name\>は、ビューが最初に定義されたモジュールの名前です（ビューが出力されるモジュールとは異なる場合があります）。
  • AQL 1.4以前では、ビューはこの名前で出力されます。 <view-name\> output ... as <alias\>このステートメントは、さまざまなドメイン用に抽出プログラムをカスタマイズする場合に役立ちます。 出力ビューを定義するときに<alias\>名を使用すると、カスタマイズのさまざまな実装で出力名が確実に同一になります。

  <alias\>名を別のselectまたはexportステートメントで使用することはできません。 <alias\>は単一引用符で囲む必要があります。<alias\> 名にはピリオドを含めることができます。

使用上の注意

• AQL 抽出プログラムを実行すると、出力ビューとして定義されたビューごとに結果のタプルが計算されます。 非出力ビューのタプルも計算されますが、出力ビューの結果のタプルを計算するために必要である場合に限ります。
• モジュラー AQL では、output view ステートメントによって、そのモジュール名で修飾された完全修飾ビュー名で、ビューのタプルが出力されます。 ステートメント output view Person; の結果が personModule.Person ビューの出力である、以下の例を考えてみます。

module personModule;

create view Person as
  extract dictionary 'FamousPeopleDict' on D.text as match
  from Document D;

output view Person;

この動作は、ビューが定義されているモジュールまたはビューがインポートされるモジュールにビューが出力されるかどうかに関係なく、別名を持たないすべてのビュー出力に適用されます。別名インポートを使用してビューがインポートされた場合も同様です。 例えば、出力ビュー MyPerson では、この例の結果は、そのローカルの別名 personModule.Person ではなく、その元の修飾名 MyPerson で出力されるビューになります。

module employeeModule;

import view Person from module personModule as MyPerson;

output view MyPerson;

• output alias ステートメントは、アプリケーション・ドメインまたは入力文書の言語に応じて、同じタイプのエンティティーが複数の異なる実装を持つことができる抽出プログラムのライブラリーを作成する際に役立ちます。 出力ビューの定義時に別名を使用する主な利点は、出力ビュー間で一貫性のある命名になることです。 一貫性のある命名は、それぞれが意味的に同様のビューを出力する複数のモジュールを処理するときに、ユーザーのプログラム・ロジックで必要になります。 モジュラー AQL では、output view ステートメントで別名が使用されると、指定された別名でビューのタプルが出力されます。 例えば、次のコードは、別名 PersonAlias で結果を出力します。この別名はモジュールのプレフィックスで修飾されません。

module personModule;

create view Person as
  extract dictionary 'FamousPeopleDict' on D.text as match
  from Document D;

output view Person as 'PersonAlias';

例

次の例は、personModuleFrench と personModuleEnglish の 2 つのモジュールを含みます。 各モジュールは PersonNameFrench と PersonNameEnglish というビューを出力します。 類似のモジュールがあり、それぞれが個人名の抽出プログラムのセマンティック・バリアントであるビューを出力するとします。 これらのモジュールは、指定された入力言語のこのビューのカスタマイズで差異が生じるように、さまざまな言語用にカスタマイズされます。 最終的には、ユーザーは、処理されたモジュールに関係なく、要求された出力ビューの名前が PersonName であるモジュールをプログラムで使用できます。 言語、ドメイン、またはその他の目的用にカスタマイズされた各モジュールは、さまざまな結果をもたらすことが期待されるため、この予想は正常です。 これらのモジュールのコンシューマーは、基礎となるセマンティクスが似ているときに、さまざまな出力ビュー名に対応するようにプログラムのアルゴリズムを変更する必要はありません。

この例では、別名 PersonName が使用されているため、コンシューマーは、要求されたビュー名を変更する必要はありません。 ただし、処理されるモジュールによって結果が異なる場合があります。 例えば、この例では、結果として得られる一致は、フランス語ベース (例 1) および英語ベース (例 2) となります。

例 1: 結果として得られる一致がフランス語ベース

次の例では、ビュー PersonNameFrench を定義し、実装中立の別名 'PersonName' で出力します。

module personModuleFrench;

create dictionary FrenchNames as
  ('Jean', 'Pierre', 'Voltaire', 'Francois', 'Marie', 'Juliette');

create view PersonNameFrench as
  extract dictionary 'FrenchNames'
  on D.text as name
  from Document D;

output view PersonNameFrench as 'PersonName';

例 2: 結果として得られる一致が英語ベース

次の例では、ビュー PersonNameEnglish を定義し、実装中立の別名 'PersonName' で出力します。

module personModuleEnglish;

create dictionary EnglishNames as
  ('John', 'Peter', 'Andrew', 'Francis', 'Mary', 'Juliet');

create view PersonNameEnglish as
  extract dictionary 'EnglishNames'
  on D.text as name
  from Document D;

output view PersonNameEnglish as 'PersonName';

サンプル・モジュールのコンシューマーは、別名 'PersonName' を介して出力タプルにアクセスできます。 コンシューマーは、結果が取り出される実際のモジュールを知る必要はありません。

構文

extract <select list>,
  <extraction specification>
from <from list>
[having <having clause>]
[consolidate on <column> [using '<policy>']]
[limit <maximum number of output tuples for each document>];

説明

• <select list\>

  出力式のコンマ区切りリスト。 これらの出力式の結果は、抽出指定の評価によって生成されるタプルとともに、extract ステートメントの出力として返されます。 <select list\>の形式は、selectステートメントの<select list\>と同じです。

• <extraction specification\>

  <from list\>で定義されているビューからのすべてのタプルに抽出指定を適用します。 これは、extract ステートメントで指定された、対応する別名に従って、タプルの列を名前変更します。 次のいずれかの抽出指定を使用できます。

  • 正規表現
  • 辞書
  • 分割
  • ブロック
  • 品詞
  • シーケンス・パターン

• <from list\>

  フィーチャーの選択元のタプルのソースである、コンマ区切りリスト。 <from list\> の形式は、 selectステートメントの<from list\>の形式と類似しています。 ただし、extractステートメントにパターン指定がない場合は、<from list\>に単一のアイテムを含めることができます。

• [having <having clause\>]

  抽出された各出力タプルに適用されるフィルター述部（<having clause\>内）を指定します。 <having clause\>に指定されているフィールド名は、<select list\>に指定されているすべての別名を参照します。 この節はオプションです。

• [consolidate on <column\>[using '<policy\>' ]]

  統合<policy\>で定義されているように、オーバーラップするスパンの処理方法を定義します。 この指定では、<column\>はextractステートメントの一部である出力フィールドの名前でなければなりません。 この節はオプションです。

• [limit<maximum number of output tuples for each document\>]

  各文書の出力タプルの数を、指定された最大値に制限します。 この節はオプションです。

使用上の注意

extract ステートメントのセマンティクスは、以下のとおりです。

• 入力関係のそれぞれのタプルに対して抽出指定を評価します。 抽出によって生成される結果ごとに、抽出された値を含む出力タプルが、<select list\>で指定された元のタプルの列を含む出力タプルの列とともに生成されます。
• <select list\>および<extraction specification\>の一部として指定された別名に従って、出力タプルの列の名前を変更します。
• オプションの having 節内のすべての述部を、結果の出力タプルに適用します。
• オプションの consolidation 節に従い、述部を渡すタプルを統合して、その結果のタプルを出力に追加します。
• オプションの limit 節がある場合、ドキュメントごとに、指定されたタプル数に出力を限定します。

from ステートメントの extract pattern 節のセマンティクスは、パターン指定を持たない他の形式の extract ステートメントとは異なります。 <from list\>内の少なくと1つのビューに特定の文書のタプルが含まれていない場合、extractステートメントの出力は空になります。 入力ビュー内のタプルのすべての組み合わせのセットが空であるため、この出力は空です。

extract pattern ステートメントの特殊なケースでは、from 節は、パターン指定に関連する関係の名前を宣言するプレースホルダーです。 ステートメントのセマンティクスは、パターン指定によってのみ駆動されます。 特に、一部の入力ビューが空であっても、ステートメントの出力を空にならないようにすることができます。

例

例 1: 事前定義ビューからの電話番号の抽出

このサンプルの extract ステートメントは、事前定義ビュー Document によって表される入力テキストに対して、米国の電話番号の正規表現を評価します。 その後、出力は、文書ごとに識別される最初の 3 つの電話番号に制限されます。 having 節の中のフィールド名は、extract ステートメントの始めの別名を参照します。

create view PhoneNumbers as
  extract
    D.text as documentText,
    regex /\d{3}-\d{3}-\d{4}/ on D.text as phoneNumber
from Document D
having MatchesRegex(/\d{3}.*/, phoneNumber)
limit 3;

例 2: 大文字で始まる単語のブロックの抽出

この例では、extract ステートメントは、2 つから 3 つの大文字で始まる単語のブロックを識別します。 AQL では、ブロックはトークンの連続スパンを指します。この場合は 2 つから 3 つのトークンです。 また、この例では、統合ポリシーを使用して、タプルの出力セットから、より大きいブロックに含まれているブロックを除外します。

create view CapitalizedWord as
  extract
    regex /[A-Z][a-z]*/
            with flags 'CANON_EQ'
        on 1 token in D.text
        as word
from Document D;

create view TwoToThreeCapitalizedWords as
  extract blocks
  with count between 2 and 3
  and separation 0 tokens
  on CW.word as capswords
from CapitalizedWord CW
consolidate on capswords using 'ContainedWithin';

consolidate 節は、抽出ブロックの指定によって capswords フィールドに適用されます。 違いは、consolidation 節によって参照されるターゲット・フィールドが、extract ステートメントの出力フィールドであることです。 select ステートメントのターゲット・フィールドは、入力フィールドです。 この動作は、having 節の動作と似ています。

例 3: ビュー名としてのネストされた extract ステートメントまたは select ステートメント

extract ステートメントの入力ビューは、例 2 のようなビュー名でも、この例のようなネストした extract または select ステートメントでも可能です。

create view SampleExtract as
  extract
  regex /foo/ on E.foobar as foo
  from
    (extract regex /foobar/ on D.text as foobar
  from Document D) E;

例 4: select リストを使用したステートメントの抽出

この例では、パターンの一致を抽出します。同時に、入力ビューから複数の属性を選択します。

create view Person as
  extract.F.first as first, M.initial as middle, L.last as last
          pattern ('Mr.'|'Ms.'|'Miss')? (<F.first> <M.initial>? <L.last>)
                    return group 0 as reference
                    and group 1 as salutation
                    and group 2 as name
  from FirstName F, MiddleInitial M, LastName L;

• 正規表現 正規表現の抽出指定によって、入力テキスト内で、その正規表現に含まれている一致パターンを識別できます。
• 辞書 辞書の抽出指定によって、ストリングの辞書に含まれている入力テキストからストリングを抽出できます。
• 分割 分割の抽出指定によって、大きなスパンをより小さないくつかのスパンに分割できます。
• ブロック ブロックの抽出指定によって、入力テキスト内で連続スパンのブロックを識別できます。
• 品詞 品詞の抽出指定によって、入力テキスト内のさまざまな品詞の場所を特定できます。
• シーケンス・パターン パターンの抽出指定によって、入力文書と、その入力文書から抽出されたその他のスパンでパターン・マッチングを実行できます。

構文

regex[es] /<regex1>/
         [and /<regex2>/ and ... and /<regex n>/]
       [with flags '<flags string>']
on <token spec>] <name>.<column>
<grouping spec>

説明

• regex[es] /<regex1\>/

  抽出で使用される正規表現を指定します。 デフォルトで、AQL は正規表現として Perl 構文を使用します。つまり正規表現のリテラルは 2 つのスラッシュ文字 (//) で囲まれます。 正規表現のエスケープ・シーケンスは、他のエスケープ文字より優先されます。 AQL では SQL ストリング構文での正規表現を使用できるため、米国の電話番号の正規表現を以下の例のいずれかで表すことができます。

  /\d{3}-\d{5}/
  

  '\\d{3}-\\d{5}'
  

• [and /<regex2\>/ and ... and /<regex n\>/ ]

  抽出で使用される追加の正規表現をリストします。

• [with flags '<flags string\>']

  正規表現のマッチングを制御するフラグの組み合わせを指定します。 このパラメーターはオプションです。 これらのフラグは、Java™ 実装で定義されたフラグのサブセットに対応します。 フラグ・ストリングが指定されない場合、AQL はデフォルトで DOTALL フラグのみを使用します。

  複数のフラグを指定するには、| 文字でそれらを区切ります。 例えば、複数行マッチング、大/小文字が区別されないマッチング、および Unicode 大文字変換を指定するには 'MULTILINE|CASE_INSENSITIVE|UNICODE' というフラグ・ストリングを使用します。

• [<token spec\>]

  トークン境界でのみ正規表現をマッチさせるかどうかを指示します。

  ... [[between <number> and] <number> token[s] in] ...
  

  トークン制約は、指定のオプション部分です。 トークン制約を省略した場合、AQL は入力テキストのそれぞれの文字位置におけるオーバーラップしない最長のマッチを戻します。 トークン制約が存在する場合、extract ステートメントは、各トークン境界での (指定されたトークン数の範囲内の長さである) 最長のマッチを戻します。 戻されるそれぞれのマッチは、トークンの始まりで開始し、トークンの終わりで終了する必要があります。 複数のオーバーラップするマッチが存在する場合、extract ステートメントはそれらをすべて戻します。

  トークン境界の場所は、ドキュメントをトークン化するためにランタイム・コンポーネントがどのトークナイザーを使用しているかに応じて異なります。 標準のトークナイザーがエンジンで使用されている場合、トークンは、単語文字のシーケンスまたは 1 つの句読文字と定義されます。

  例えば、次のストリングを考えてみます。

  "The fish are pretty," said the boy.
  

  トークン境界は次の場所で識別されます。

  ["][The] [fish] [are] [pretty][,]["] [said] [the] [boy][.]
  

• <name\>.<column\>

  正規表現が適用されるビュー名および列名。

• <grouping spec\>

  正規表現でのキャプチャー・グループの処理方法を決定します。 キャプチャー・グループとは、元の式で括弧により識別される、正規表現マッチの領域です。 例えば、式 (fish)(cakes) には以下の 3 つのキャプチャー・グループがあります。

  • グループ 0 は全体のマッチ、つまり fishcakes です。
  • グループ 1 は fish です。
  • グループ 2 は cakes です。 構文の return 節でグループ ID を指定する場合、各グループ ID は、構文の extract regex 節の一部として指定されたそれぞれの正規表現内の有効なグループに対応している必要があります。

  グループ化指定の形式は次のとおりです。

  return
      group <number> as <name>
      [and group <number> as <name>]*
  

  グループ0（一致全体）のみを返すには、例1のように、より短い代替形式を使用できます。 この形式は、return group 0 as <name>と同じです。<name>は単純なIDまたは二重引用符で囲んだIDにすることができます。

使用上の注意

• 全般的に、AQL は Java 5 の正規表現実装と同じ機能をサポートします ([クラス・パターン: java.util.regex の説明を参照)。 ランタイム・コンポーネントには、Java の組み込み実装など、正規表現エンジンの実装がいくつか含まれています。 コンパイル時にオプティマイザーはそれぞれの正規表現を検査して、最も高速に式を実行できるエンジンを選択します。

• 代替的な実行エンジンのセマンティクスは、特定のごく稀なケースで微妙に異なる可能性があります。 特に、AQL は、代替が評価される順序を保証していません。

  例えば、extract ステートメントがテキスト「fisherman」に対して、正規表現 /fish|fisherman/ をマッチングするとします。 どの正規表現エンジンが内部的に使用されるかに応じて、「fish」または「fisherman」がこのステートメントでマッチする可能性があります。

• 以下のガイドラインに従うと、抽出プログラムをより高速に実行することができ、保守も容易になります。
  • 長い、複雑な正規表現を使用しないで、AQL ステートメントと結合されたより単純で短い正規表現を使用します。
  • 正規表現で先読みと戻り読みを不必要に使用しないでください。 抽出ステートメントの having 節に述部を追加することで、通常は同じ効果が得られます。
  • 可能な限り、トークン制約を正規表現の抽出指定で使用してください。

例

例 1: 標準の Unicode 等価を使用した一致の判別

この例では、名ではない大文字で始まる単語を検索する方法を示します。 一致を判別するために標準の Unicode 文字等価が使用されます。 フラグ‘CANON_EQ’の使用法と、その正規表現がトークンに対して実行されることに注意してください。

create dictionary FirstNamesDict as
  (
  'Aaron', 'Matthew', 'Peter'
  );
create view NotFirstName as
  extract
    regex /[A-Z][a-z]*/
    with flags 'CANON_EQ'
    on 1 token in D.text
    as word
from Document D
  having Not(ContainsDict('FirstNamesDict', word));

例 2: キャプチャー・グループの使用法

以下の例は、extract regex ステートメントでのキャプチャー・グループの使用法を示しています。 このコードは、キャプチャー・グループを使用して、米国の電話番号のフィールドを抽出します。

create view Phone as
  extract regex /(\d{3})-(\d{3}-\d{4})/
    on between 4 and 5 tokens in D.text
    return
      group 1 as areaCode
      and group 2 as restOfNumber
      and group 0 as fullNumber
from Document D;

例 3: 入力テキストに対する複数の正規表現の適用

extract regex 構文を使用して、同じ regexes ステートメントに複数の正規表現を指定できます。

create view PhoneNum as
  extract regexes
    /(\d{3})-(\d{3}-\d{4})/ and /[Xx]\d{3,5}/
        on between 1 and 5 tokens in D.text as num
from Document D;

例 4: グループ化指定の誤用

このコード・サンプルの正規表現には、group -1 も group 3000 も含まれていません。 これによりコンパイル・エラーが発生します。

create view ErrorExample as
    extract regex /(\d+)/
    on D.text
    return group -1 as wrongGroup and
          group 3000 as nonExistentGroup
from Document D;

構文

    dictionar[y|ies]
        '<dictionary>'
        [and '<dictionary>' and ... and '<dictionary>']
        [with flags '<flags string>']

説明

• '<dictionary\>'

  create dictionary ステートメント、create external dictionary ステートメント、またはファイル・システム上の辞書ファイルのいずれかを使用して作成された辞書を参照します。

• [and '<dictionary\>' and ... and '<dictionary\>']

  抽出に使用する追加の辞書を参照します。

• [with flags'<flags string\>']

  辞書のマッチングを制御します。 現在、以下の 2 つのオプションがサポートされています。

  • 正確な

    正確な、大/小文字を区別するマッチングです。

  • IgnoreCase

    大/小文字の区別をしないマッチングです。

フラグが指定されない場合、辞書は、作成時に指定されたフラグに基づいてマッチングされます。 作成時にフラグが指定されなかった場合は、IgnoreCase フラグを使用してマッチングされます。

使用上の注意

• 辞書は常にトークン境界で評価されます。 具体的には、辞書項目の最初のトークンがテキスト領域の最初のトークンと一致し、辞書項目の 2 番目のトークンがテキスト領域の 2 番目のトークンと一致し、以下同様に続く場合に、辞書項目はテキスト領域に一致します。 2 つの連続したトークン間の文字は無視されます。

  例えば、英語などの言語に適した、単純な空白文字ベースのトークン化モデルを使用しているとします。 また、入力テキストが「Let’s go fishing!」であるとします。 辞書が用語 go fish から構成される場合、Let's go fishing! のテキストには一致がありません。 ただし、辞書が項目 go fishing (go と fishing の間に空白文字が 2 つあることに注意してください) から構成される場合、テキスト Let's go fishing! には 1 つの一致があります。 空白文字は、go と fishing が 2 つの明確なトークンであることを示します。 入力テキスト内の 2 つのトークン go と fishing の間に 1 つ以上の空白文字がある場合、一致があります。

  入力テキストと辞書項目の一致ごとに、extract dictionary ステートメントによって出力タプルが生成されます。

例

例 1: 辞書ファイルからの用語の抽出

一般的な名と姓から成る辞書ファイルを大/小文字を区別するマッチングを適用して使用し、個人名を見つけます。

create view Name as
  extract
    dictionaries
        'first.dict'
        and 'last.dict'
    with flags 'Exact'
        on D.text
        as name
from Document D;

以下に、last.dict のサンプル・コンテンツを示します。

#Dictionary for surnames
Anthony
Aparicio
Cate
Lehmann
Radcliff

以下に、first.dict のサンプル・コンテンツを示します。

#Dictionary for given names
Aaron
Candra
Freeman
Mathew
Matthew
Zoraida

注：

• extract dictionary ステートメントで直接参照される辞書ファイル・システムは、言語のセットを使用して明示的に構成することはできないため、実行時に辞書がコンパイルされて適用されます。 代わりに、モジュールにこのステートメントが含まれている場合は、set default dictionary language ステートメントで言語のセットが指定されます。

  したがって、extract dictionary ステートメント内の辞書ファイルの直接参照は推奨されず、将来的に廃止される可能性があります。 推奨される方法は、create dictionary from file ステートメントを使用して辞書オブジェクトを明示的に定義してから、extract ステートメントでその辞書を使用することです。

• コンパイラーとランタイム・コンポーネントが、構成された検索パスで、AQL で参照される辞書ファイルを見つけようとします。

例 2: インライン辞書からの用語の抽出

インライン辞書および大/小文字を区別しないデフォルトのマッチングを使用して、結合を見つけます。

create dictionary ConjunctionDict as
  (
    'and', 'or', 'but', 'yet'
  );

create view Conjunction as
  extract
    dictionary 'ConjunctionDict'
        on D.text
        as name
from Document D;

構文

split using <name>.<split point column>
    [retain [right|left|both] split point[s]]
    on <name>.<column to split>
    as <output name>

説明

分割の抽出指定には 2 つの引数があります。

• テキストのより長いターゲット・スパンを含む列。
• 分割点を含む列。

分割アルゴリズムは入力ビューに対して 2 パスで処理されます。 第 1 のパスでは、すべての入力タプルをグループ化してターゲット列にします。 第 2 のパスは各グループ内のタプルを処理対象として、分割している列の各値でターゲット列を分割します。

• <name\>.<split point column\>

  抽出の分割点を指定します。

• [retain [right|left|both] split point[s]]

  各結果の左右の終点を処理する方法を指定します。 この引数はオプションです。

  • retain left split point が指定された場合、各出力スパンには左の分割点 (その分割点が存在する場合) が含められます。
  • retain right split point が指定されると、各出力スパンに右の分割点が含められます。
  • 分割抽出では、分割点として NULL 値を受け付けることもできます。 抽出結果には、NULL 値それぞれに対して入力スパン全体を含むタプルが返されます。

• <name\>.<column to split\>

  抽出のターゲット列を指定します。

• <output name\>

  抽出の出力の名前を定義します。

例

例 1: 分割点と retain 節

分割点がすべてフレーズ fish are swimming in the fish pond の中の単語 fish のインスタンスだった場合、retain 節の種々の型により、次のような効果が得られます。

• retain 節を省略

  " are swimming in the " and " pond"

• **retain right split point **

  " are swimming in the fish" and " pond"

• retain left split point

  「fish are swimming in the 」と「fish pond」

• retain both split points

  「fish are swimming in the fish」と「fish pond」

例 2: 分割抽出

この例では、文書を文に分割します。 最初は、正規表現を使用して文の境界を識別します。次に、分割の抽出指定を使用して、文の境界で文書テキストを分割します。

create dictionary AbbreviationsDict as
  (
  'Cmdr.',
  'Col.',
  'DR.',
  'Mr.',
  'Miss.');

create view Sentences as
  extract
    split using B.boundary
        retain right split point
        on B.text
        as sentence
  from (
    extract
        D.text as text,
        regex /(([\.\?!]+\s)|(\n\s*\n))/
        on D.text as boundary
        from Document D
    -- Filter the candidate boundaries.
      having Not(ContainsDict('AbbreviationsDict',
            CombineSpans(LeftContextTok(boundary, 1), boundary)))
      ) B;

構文

blocks
    with count [between <min\> and] <max\>
    and separation [between 0 and] <max\> (tokens| characters)
    on <name\>.<column containing spans\>
    as <output name\>

説明

• with count [between<min\> and] <max\>

  1 つのブロックを構成できるスパンの数を指定します。 <min\>および<max\>の値は、ブロックを構成できるスパンの最小数と最大数を指定します。

• [between 0 and] <max\>

  スパンが連続していると見なされるまでのスパン間の分離距離を指定します。

• (tokens| characters)

  スパンの分離距離がトークンの数を表すか、文字数を表すかを指定します。

• <name\>.<column containing spans\>

  ブロック演算子が適用されるビュー名および列名。

• <output name\>

  ブロック演算子からの出力の名前を指定します。

使用上の注意

• 入力スパンに複数の重なり合うブロックが含まれている場合、ブロック抽出ステートメントはすべての可能なブロックを返します。 重複ブロックをフィルターに掛けて除くには、統合を使用します。
• ブロック抽出の指定を使用する extract ステートメントは、複数の入力タプルから、特定のフィールドの値の集約で構成される各ブロックを生成します。 したがって、その select リストには、その入力ビューのフィールドを含めることはできません。

例

例 1: 文字範囲内の単語のブロックの抽出

以下のコードでは、ビュー TwoToThreeCapitalizedWords が、お互いの距離が 100 文字以内の、語頭が大文字の単語 2 つから 3 つで成るブロックを識別します。

create view CapitalizedWords as
  extract
    regex /[A-Z][a-z]*/
        with flags 'CANON_EQ'
        on 1 token in D.text
        as word
from Document D;

create view TwoToThreeCapitalizedWords as
  extract blocks
    with count between 2 and 3
    and separation between 0 and 100 characters
    on CW.word as capswords
from CapitalizedWords CW;

例 2: トークン範囲内の単語のブロックの抽出

以下のコードでは、お互いの距離が 5 トークン以内の、語頭が大文字の単語 2 つから成るブロックを識別します。

create view TwoCapitalizedWords as
extract blocks
    with count 2
    and separation between 0 and 5 tokens
    on CW.word as capswords
from CapitalizedWords CW;

構文

part_of_speech
 '<part of speech spec>'
 [and '<part of speech spec>']*
 [with language '<language code>']
 [and mapping from <mapping table name>]
 on <input column> as <output column\>
 from <input view>

説明

• '<part of speech spec\>'

  入力テキストから抽出する品詞を指定します。 '<part of speech spec\>'は、以下のいずれかのストリングです：

  • マルチリンガル・トークナイザーによって生成されるコンマ区切りの品詞タグのリストを含むストリング
  • マッピング表で定義された内部的な品詞名とフラグの組み合わせ

• [and '<part of speech spec\>']*

  抽出に使用する追加の品詞タグを識別します。

• [with language '<language code\>']

  抽出で使用する言語を指定します。 <language code\>は、2文字の小文字の言語コード（「en」や「ja」など）です。 この引数を省略した場合、品詞抽出の対象となる言語として英語が想定されます。

• [and mapping from <mapping table name\>]

  「NOUN」などの生の品詞タグを、高水準の品詞とフラグの組み合わせにマップする AQL 表の名前を指定します。 オプションのマッピング表では変数名を使用できますが、これらの列名を使用するには品詞マッピング表が必要です。

  • タグ

    マルチリンガル・トークナイザーの品詞タグを保持する列。

  • basetag

    対応する内部タグを保持する列。

  • flagstr

    指定された品詞に関連付けられたフラグから成るコンマ区切りリストを保持する列。

  マッピング表は、それを使用する extract create table ステートメントと同じモジュールで、part_of_speech ステートメントを使用して定義する必要があります。 これは、インポートされた表にすることも、外部の表にすることもできません。

  create table POSMapping_EN(tag Text, basetag Text, flagstr Text)
  as values
   ('CCONJ','CONJ','coordinating'),
   ('SCONJ','CONJ','subordinating');
  

• <input column\>

  品詞情報の抽出元となる、入力ビューの列を指定します。

• <output column\>

  指定された品詞を持つトークンのスパンが送信される列の名前を指定します。

• <input view\>

  品詞情報の抽出元となる、入力ビューを指定します。

使用上の注意

• 品詞の抽出が機能するのは、マルチリンガル・トークナイザーが使用される場合のみです。 システムで標準のトークナイザーが使用される場合、part_of_speech の抽出でエラーが生成されます。

言語の品詞タグ

サポートされるすべての言語で、マルチリンガル・トークナイザーでは、次の表にリストされた品詞タグが使用されます。

例

例 1: extract ステートメントでの品詞タグの直接の使用

ビュー EnglishNoun では、英語の名詞 (単数形または不特定多数) または固有名詞 (単数形) が抽出されます。

create view EnglishNoun
as extract parts_of_speech 'NOUN' and 'PROPN'
with language 'en' on D.text
as noun from Document D;

構文

シーケンス・パターンの一般的な構文は、まずテキストでマッチングするパターンを指定し、次に抽出プログラムによって返す内容を指定します。 シーケンス・パターンの最後の部分で、パターンに対する入力内容を指定します。つまり、以前に定義されたビューの列か、文書テキスト全体になります。

pattern <pattern specification> [return clause] [with inline_match on <viewname.colname>]

説明

• <pattern specification\>

  <pattern specification\>は、複数のアトムで構成されます。 個々のアトムは、定義済みビュー、固定ストリング、または正規表現の列にすることができます。 オプションで繰り返しになるようにアトムを指定し、アトム間のトークン・ギャップを指定することができます。

  パターン指定は、extract 文節を含む、より大きな AQL ステートメントの一部です。

  以下に、以前の定義済みビューからの 3 つの隣接する一致を含むビューを作成する方法の簡単な例を示します。 この例では、組み合わせ全体が返されます。これは、group 0 が参照するものです。

  create view Money as
  extract pattern <C.match> <N.match> <Q.match>
  return group 0 as  match
  from Currency C, Number N, Quantifier Q;
  

  複数のアトムがお互いに正確に隣接する必要がない場合は、その他の一致を許可するように、アトム間のトークン・ギャップを使用できます。 この例では、個人名があり、0 から 2 トークン後に電話番号が記載されているものを検索します。 <Token>{0,2}この構文に注目してください。これは、personアノテーションとphoneアノテーションの間に0個から2個のトークンのギャップが許可されることを示しています。

  create view Phone as
  extract regex /(\d{3})-(\d{3}-\d{4})/
    on between 4 and 5 tokens in D.text
    return
     group 1 as areaCode
     and group 2 as restOfNumber
     and group 0 as fullNumber
  from Document D;
  create view PersonPhone as
  extract
    pattern (<P.name>) <Token>{0,2} (<Ph.fullNumber>)
    return group 0 as match
     and group 1 as person
     and group 2 as phone
  from Person P, Phone Ph;
  

  トークン・ギャップ構文は、シーケンス式内での使用に制限されます。 さらに、シーケンス内の各トークン・ギャップの前後は、トークン・ギャップ式以外でなければなりません。 このため、extract pattern ステートメントは例外を生成します。

  -> pattern consisting only of a token gap is an error
  extract pattern <Token> as match from ...
  -> pattern beginning with a token gap is an error
  extract pattern <Token> {0,2} <Ph.phone> as match from ...
  -> pattern ending with a token gap is an error
  extract pattern <P.name> <Token> ?  as match from ...
  -> group consisting only of a token gap is an error
  extract pattern <P.name> (<Token>)  <Ph.phone> as match from ...
  

  各アトムの繰り返し回数を示すには、(min,max) 構文を使用します。 1 つのアトムまたは繰り返しのアトムがオプションであることを示すために、? 構文を使用することもできます。 これらの繰り返しおよびオプションの指示とともに、アトムが結合され、シーケンスが作成されます。

  以下に、要素を繰り返す方法を示す、より複雑な例を示します。 大文字で始まる 1 つから 3 つの単語があり、その次に「Hotel」または「hotel」というトークンが出現することを指定して、候補にするホテル名を検索します。

  create view CapsWord as
  
  extract
      regex /[A-Z][a-z]*/
         on 1 token in D.text
         as word
  from Document D;
  
  create view HotelCandidate as
  extract
    pattern <CW.word>{1,3} /[Hh]otel/ as hotelname
  from CapsWord CW;
  

  extract pattern <A.match>| <B.match> <C.match> as match from Apple A, Bacon B, Chocolate C;のように、|演算子を使用して、アトムの選択を示すこともできます。 このパターンは、1 つの A.match、または B.match とそれに続く C.match のシーケンスのいずれかの一致として説明することができます。 | 演算子を使用する完全な例は、例 1 で確認できます。

  パターンを作成した後、<pattern specification>と一致するたびに、パターン仕様の return 節と、extractステートメントの先頭にあるオプションの<select list>に従って、出力結果が構成されます。 having ステートメントの consolidate 節、limit 節、および extract 節に従って、結果がフィルタリングされて統合されます。 例えば、パターン指定に複数のオーバーラップする一致がある場合、考えられる一致がすべて返されます。また、consolidation 節を使用して重複出力を除外できます。

  前の例を考えてみます。ただし、今回は、「Sheraton」という単語を含む一致を削除し、より大きい一致に含まれている一致を削除することで、結果として得られる一致を統合することを目的としています。 例えば、テキストの同じスパンでは、「Best Garden Hotel」に加えて「Garden Hotel」を見つけることはできません。

  create view HotelCandidate as
  extract
    pattern <CW.word>{1,3} /[Hh]otel/ as hotelname
  from CapsWord CW
  having Not(ContainsRegex(/.*Sheraton.*/,hotelname))
  consolidate on hotelname using 'ContainedWithin';
  

構文およびいくつかの例について学習したので、次の図で、パターン指定の完全な構文について概説します。 パターンの構築を始めるときに、この完全な構文を参照して、構築するパターンの構成方法を確認してください。

POSIX 文字ベースの正規表現に精通している場合は、構文が類似していることが分かります。 この場合、構文で要素間に空白文字を使用でき、AQL の目的に合うように要素をどのようにすることができるかも定義されます。この場合の用語 Alternation は選択肢を意味することに注意してください。 要素間に垂直バーを使用することは、選択肢があることを示します。これは、( ) を使用してグループ化できます。

Pattern   -> Alternation
Alternation  -> Sequence | Sequence | ... | Sequence
Sequence   -> Optional Optional ... Optional
Optional   -> Repeat | Repeat ? Repeat     -> Atom | Atom { min, max }
Atom     -> <view_name.column_name>
     'string'
   <'string' [match parameters]>
     /regex/
     <Token>
     Group
Group -> ( Pattern )

具体的には、アトムには 6 つの形式があります。

• <view_name.column_name\>

  extract pattern ステートメントの from リストで指定された、ビュー、表、または表関数参照のいずれかからの列を指定します。

• 「文字列」

  AQL デフォルト・ディクショナリー・マッチング・セマンティクスを使用して、指定したストリングに対する一致を指定します。

• <'string' [match parameters]\>

  [match parameters] で指定されたディクショナリー・マッチング・セマンティクスを使用して、指定したストリングに対する一致を指定します。 [match parameters] の形式は、case (exact | insensitive) です。 この形式は、ストリング一致を判別するために使用される大文字変換のタイプを指定します。 大/小文字の区別がある完全一致を指定するには、exact を選択します。 大/小文字の区別をしない一致を指定するには、デフォルト値の insensitive を選択します。

• /regex/

  ドキュメント・テキスト内の単一トークンに制約したマッチングを行う、文字ベースの正規表現マッチングを指定します。　 さらに、この構文ではシーケンス式で特殊なトークン・ギャップ構文を指定することができ、これを使用して、min から max までの数のトークンとの一致を指示できます。

• <token\>

  いずれかのトークンに対する一致。

• [return clause]

  return 節に従って、パターン式の一致ごとに抽出された値を生成します。 return 節は、return ステートメントの extract regex 節と同じセマンティクスに従います。

• [with inline_match on <viewname.colname\>]

  ストリングおよび正規表現などのアトムでは、システムがストリング抽出または正規表現抽出に使用するテキスト・オブジェクトを with inline_match 節で判別します。 例えば、節が with inline_match on Email.subject の場合、すべてのディクショナリーと、パターン指定でインライン定義される正規表現が Email ビューの subject フィールドに適用されます。 with inline_match が存在しなければ、ストリング抽出と正規表現抽出は、デフォルトで Document.text 全体に対して実行されます。 この場合、viewname は、現行モジュールで定義されたか、別のモジュールからインポートされたビューまたは表の名前でなければなりません。また、表関数への参照は、inline_match 文節では許可されません。

• [with language as <language code(s)\>]

  ストリングを評価する言語の en (英語) や zh (中国語) などの 2 文字の言語コードのコンマ区切りリストを指定します。 このストリングに言語コードが含まれていない文書には、一致はありません。 language パラメーターを指定しないと、評価言語は、次のいずれかの言語セットにデフォルト設定されます。

  • 宣言されている場合は、収容モジュールで set default language ステートメントで指定された言語セット
  • ドイツ語 (de)、スペイン語 (es)、英語 (en)、フランス語 (fr)、イタリア語 (it)、および未指定の言語 (x_unspecified) を含む言語セット

使用上の注意

• extract pattern ステートメントのセマンティクスは、パターン指定によって駆動されます。 それぞれの一致によって、パターン指定の return 節と、extract ステートメントの先頭の select リストに従って出力結果が構成されます。 extract ステートメントの having 節、consolidate 節、および limit 節に従って、結果がフィルタリングされて統合されます。 パターン指定に複数のオーバーラップする一致がある場合、パターンの抽出で、考えられる一致がすべて出力されます。 重複出力をフィルタリングするには、consolidation を使用します。

• from ステートメントの extract pattern 節のセマンティクスは、パターン指定を持たない他の形式の extract ステートメントとは異なります。 extractステートメントの一般的なセマンティクスでは、<from list\>で定義されているビューの組み合わせごとに抽出指定を評価する必要があります。 <from list\>内の少なくとも1つのビューに特定の文書の結果が含まれていない場合、入力ビュー内の結果のすべての組み合わせのセットが空であるため、抽出ステートメントの出力は空になります。 extract pattern ステートメントの特殊なケースでは、from 節は、パターン指定に関連する関係の名前を宣言するプレースホルダーです。 ステートメントのセマンティクスは、パターン指定によってのみ駆動されます。 特に、一部の入力ビューが空であっても、ステートメントの出力を空にならないようにすることができます。

• シーケンス・パターンの抽出を使用する extract ステートメントは、from リスト内の任意のビューの列を持ち越すことができます。ただし、ビュー名がパターン指定の繰り返しエレメントに表示されない場合に限ります。 例えば、ステートメント CapsWordOneToThree は、コンパイル・エラーとなります。 このエラーは、extractステートメントの最上部にある持ち越し列CW.typeが、パターン指定の繰り返しエレメント<CW.word>{1,3}にあるビュー名CWに属しているために発生します。

  create view CapsWord as
  extract 'UpperCase' as type,
      regex /[A-Z].*/ on 1 token in D.text as word
  from Document D;
  
  ---> This results in and error due to the repeating element CW.word
  create view CapsWordOneToThree as
  extract CW.type as type,
      pattern <CW.word>{1,3} as match
  from CapsWord CW;
  
  output view CapsWordOneToThree;
  

  パターン指定の代替またはオプションのエレメントに表示されるビュー名から持ち越される列の場合、対応する代替またはオプションのエレメントがテキスト内にない場合、出力列の値は null になります。 この点を示す例として、例 1 の Person ビューがあります。

• 繰り返しエレメント内に group を記述してステートメントの return 節で出力することはできません。 例えば、次のステートメントでは、例外が発生することになります。

  create view CapsWordOneToThree as
    extract
           pattern (<CW.word>){1,3}
          return group 0 as fullmatch
                 and group 1 as word   -- not allowed due to repeat
    from CapsWord CW;
  

例

例 1: キャプチャー・グループを使用するシーケンス・パターン

この例の目的は、名、次にオプションでミドルネームのイニシャル、その次に姓が出現し、マッチング全体の先頭にはオプションで一般的な敬称 (salutation) が付くことを指定して、個人名を検索することです。 また、抽出プログラムが、マッチング全体を reference、第 1 のグループを salutation、第 2 のグループを name として返し、それぞれの入力ビューから名、ミドルネームのイニシャル、および姓の値を持ち越す必要があります。

create view MiddleInitial as
extract regex /\b([\p{Lu}\p{M}*]\.\s*){1,5}\b/
            on between 1 and 10 tokens in D.text as initial
from Document D;

create view Person as
extract F.first as first,
        M.initial as middle,
        L.last as last,
        pattern ('Mr.'|'Ms.'|'Miss')? (<F.first> <M.initial>? <L.last>)
return group 0 as reference
  and group 1 as salutation
  and group 2 as name
from FirstName F, MiddleInitial M, LastName L;

サブパターン式 ('Mr.'|'Ms.'|'Miss')? はオプションであるため、テキストに salutation が存在しない場合、salutation 出力列の値は null になります。 同様に、パターン副次式<M.initial>?はオプションであるため、ミドルネームのイニシャルが存在しない場合、出力列の中間の値はnullになります。

例 2: ストリング一致およびマッチング・パラメーターを使用したシーケンス・パターン

この例の目的は、文書のタイトル・アノテーションを調べることにより、既知のプロジェクトの記載を会議メモから検索することです。 with inline_match 節に注目してください。この節で、文書テキスト全体ではなく、Title ビューの match フィールドに対して実行されるストリングのマッチングを指定しています。

create view Project as
extract
regex /[Pp]roject\s?\w*/ on D.text as name
from Document D;


create view Title as
extract regex /[A-z][a-z]+.*/
on between 1 and 20 tokens in D.text as match
from Document D;


create view MeetingNote as
extract
pattern <'Meeting Notes:'[with case exact]> (<P.name>)
return group 0 as match
  and group 1 as projectname
with inline_match on Title.match
from Project P;

例 3: 入力ビューが空であっても、空でない結果を返すシーケンス・パターン

次のステートメントは、入力ビュー LastName が空であっても結果を生成します。 パターン指定の2番目の部分である<L.name\>?には、オプションのエレメントが含まれています。 パターン指定のセマンティクスは、FirstName.name スパン、または直後に FirstName.name スパンが続く LastName.name スパンのいずれかで構成されるすべてのスパンを出力するように設計されています。 したがって、ビュー LastName が空である文書では、ステートメントの結果は、その文書から識別される単一の FirstName.name スパンがある、すべてのスパンで構成されます。

create dictionary FirstNamesDict as
(
  'Aaron', 'Matthew', 'Peter'
);
create dictionary LastNamesDict as
(
  'Anthony', 'Lehman', 'Radcliff'
);

create view LastName as
  extract dictionary 'LastNamesDict'
  on D.text as last
from Document D
having MatchesRegex(/((\p{L}\p{M}*)+\s+)?\p{Lu}\p{M}*.{1,20}/, last);

create view FirstName as
  extract dictionary 'FirstNamesDict'
  on D.text as first
from Document D
having MatchesRegex(/\p{Lu}\p{M}*.{1,20}/, first);

create view PersonName as
extract pattern <F.first> <L.last>? as fullName
from FirstName F, LastName L;

構文

select ステートメントは、SQL SELECT ステートメントの構造に類似しています。

select `<select list>`
  from `<from list>`
  [where `<where clause>`]
  [consolidate on `<column>`
     [using '`<policy>`' [with priority
         from `<column> ` [priority order]]]]
  [group by `<group by list>`]
  [order by `<order by list>`]
  [limit `<maximum number of output tuples for each document>`];

説明

• <select list\>

  出力式のコンマ区切りリスト。

• <from list\>

  選択されるタプルのソースである、コンマ区切りリスト。

• [where <where clause\>]

  from 節内の関係にあるすべてのタプルのデカルト積から生成される各タプルに適用される述部を定義します。 この節はオプションです。

• [consolidate on<column\>[using '<policy\>' [with priority from <column\> priority order]]]

  オーバーラップするスパンを管理するための統合ポリシーを定義します。 この節はオプションです。

• [group by<group by list\>]

  指定されたフィールドの共通の値によって、同じ文書から生成されるタプルをグループ化します。 この節はオプションです。

• [order by<order by list\>]

  各文書からの select ステートメントによって生成される出力タプルを順序付けします。 この順序は、式のコンマ区切りリストである、order by list の値に基づきます。 この節はオプションです。

• [limit <maximum number of output tuples for each document\>]

  各文書からの出力タプルの数を、指定された最大値に制限します。 この節はオプションです。

使用上の注意

select ステートメントのセマンティクスは、以下のとおりです。

• from リストの関係のデカルト積を使用して、入力データ (タプル内) を判別します。
• 生成される入力タプルごとに、(オプションの) where 節の述部を適用して、フィルタリングします。
• オプションの group by 節が存在する場合、同じ文書から生成されたタプルを、group by list に指定された値によってグループ化して、select リスト内の aggregate 関数の結果を計算します。
• (オプションの) consolidation 節で定義されたポリシーに従って、オーバーラップするタプルをすべて統合します。 オプションの order by 節が存在する場合、order by list の値によってこれらのタプルを順序付けします。
• 各タプルの select リスト内のすべての式を計算し、as 節で指定されたように、列の名前を変更します。
• オプションの limit 節がある場合、文書ごとに、指定されたタプル数に出力タプルの数を限定します。

例

select ステートメントの使用例として、パターンに一致する電話番号の抽出があります。 米国のパターン XXX-XXX-XXXX の電話番号を抽出する PhoneNumbers ビューが既に定義されているとします。 この select ステートメントは、パターン 444-888-XXXX の正規表現を入力テキスト全体で評価します。 このビューには、出力列 documentText および phoneNumber があります。 また、出力は、文書ごとに識別されたこの電話番号パターンの最初の出現に限定されます。

create view PhoneNumbersPattern1 as
select D.documentText, D.phoneNumber
from PhoneNumbers D
where MatchesRegex(/444-888-\d{4}/,D.phoneNumber)
limit 1;

select ステートメントを使用するもう 1 つの例として、人とその対応する電話番号のおおよそのマッピングの検出があります。 ビュー Person が既に定義されており、それに列 person とビュー PhoneNumbers があるとします。 この select ステートメントは、where 節を評価して、個人名があり、その 1 つから 3 つの単語またはトークンの範囲内に電話番号が続くテキスト・スパンを検索します。 このステートメントに対する入力は、from リストの Person ビューと PhoneNumbers ビューの結合によって表されます。

create view PersonPhone as
select P1.documentText, P1.person, P2.phoneNumber, CombineSpans(P1.person,P2.phoneNumber) as personPhoneSpan
from Person P1, PhoneNumbers P2
where FollowsTok(P1.person,P2.phoneNumber,1,3);

personPhoneSpan 列には、個人と電話番号のおおよそのマッピングを示す一致するスパンが含まれます。

personPhoneSpan
John : 433-999-1000
Martha Mob 433-999-1001

• select リスト AQL select または extract ステートメントの select リストは、出力式から成るコンマ区切りリストです。
• from リスト AQL の select または extract ステートメントの 2 番目の部分は from リストです。 from リストは、選択または抽出されるタプルのソースである、コンマ区切りリストです。
• where 節 オプションの where 節は、from 節内の関係にあるすべてのタプルのデカルト積から生成される各タプルに適用される述部を定義します。
• consolidate on 節 オプションの consolidate on 節は、select ステートメントまたは extract ステートメントによって出力されるすべてのタプルで、オーバーラップするスパンをどのように解決するかを指定します。 この節の使用時は、オーバーラップするスパンのないタプルには影響しません。
• group by 節 group by ステートメントのオプションの select 節は、指定されたフィールドの共通の値によって、同じ文書から生成されるタプルをグループ化するように、ランタイム・コンポーネントに指示します。
• order by 節 オプションの order by 節は、コンマで区切られた一連の式である order by list の値に基づいて、各文書の select ステートメントによって生成される出力タプルを順序付けするように、ランタイム・コンポーネントに指示します。
• limit 節 オプションの limit 節は、文書の select ステートメントによって生成される出力タプルの数の制限を指定します。
• select... into ステートメント select ... into ステートメントは、単一のステートメントでビューを定義し、出力ビューとしてそれを指定するうえで役立ちます。

構文

それぞれの select 式は、以下のいずれかの形式でなければなりません。

select
   <viewname>.<colname> as <alias> |
   <viewname>.* |
   <expr> as <alias> |
     case
     when <predfunction1()> then <expr1>
      when <predfunction2()> then <expr2>...
     when <predfunctionn()>
      then <exprn>
     [else <expr\_default>]
      as <name>

説明

• <viewname\>.<colname\> as <alias\>

  • <viewname\>

    列の選択元のビューを指定します。

  • <colname\>

    そのビューの列を指定します。

  • <alias\>

    選択されたフィールドが認識される名前を指定します。 このフィールドは、オプション・フィールドです。 これは、各出力タプルの一部として選択されます。 <alias\>を指定しない場合、列の名前はデフォルトで<colname\>になります。 これは、単純な ID でも、二重引用符付き ID でもかまいません。

• <viewname\>.*

  ビューの名前を指定します。 この構文は、指定されたビューのすべての列が、囲んでいる select ステートメントまたは extract ステートメントに持ち越される必要があることを示しています。

  SQL と同様に、AQL では簡略な select * ステートメントを使用できます。 このステートメントの効果は、from ステートメントの select 節で指定されたすべての入力からすべての列を選択することです。 ただし、省略表現の extract * ステートメントはサポートされていません。

• <expr\> as <alias\>

  包含するビューの属性に対する式の割り当てを表します。

  • <expr\>

    スカラー関数呼び出し、集約関数呼び出し、または定数で構成される式を指定します。

  • <name\>

    <expr\> によって<alias\>として指定された式の結果を保持する列の名前を表します。 <alias\>を指定しない場合、列の名前はデフォルトで<name\>になります。 これは、単純な ID でも、二重引用符付き ID でもかまいません。

• when<function1()\> then <expr1\> when <function2()\> then <expr2\> ... when <functionN()\> then <exprn\> [else ] <expr_default\> as <name\>

  • <function1()\>, <function2()\>, <functionN()\>

    Boolean 型を返すスカラー関数を指定します。

  • <expr1\>, <expr2\>, <exprn\>, <expr_default\>

    スカラー関数呼び出しで構成される式を指定し、同じ型を返す必要があります。

  <function1()\>の結果が真の場合、case式の結果は<expr1\>の結果になり、後続の when節はすべて評価されません。 そうでない場合、後続の when 節が存在すれば、それらは同じ方法で評価されます。

  when節の条件がいずれも満たされない場合、このCASE式の結果はデフォルト式<expr\_default\>の結果になります。 この式は、オプションの else 節で指定されます。 [else] 節がない場合、この case 式の結果は null になります。

使用上の注意

• 次のステートメントはサポートされていません。

  select * from Document;
  

  Document ビューの内容が、この select ステートメントが発行された .aql ファイルの現行コンテキストまたはスコープ内で、完全に認識されていない可能性があります。 この内容に関する情報の不足は、現行の .aql ファイルの外部で提供される複数の require document with columns ステートメントによって、この特殊な Document ビューの最終的なスキーマ定義が、モジュールのレベルで使用される場合に、変更される場合があることが原因です。 省略表現の Document.* ステートメントは有効な AQL 構成体ではありません。

• Document ビューからフィールドを明示的に選択できます。 次の例は、Document ビューからのフィールドの有効な明示的選択を示しています。

  select D.label as label,
    D.text as text
  from Document D;
  

例

次の例は、select リストのさまざまな形式を示しています。

例 1: 定数を使用した明示的な値の割り当て

この例では、select リスト内のビュー属性への定数値の割り当てを示します。 polarity と呼ばれるフィールドは、PS.match の極性が正か負かを示します (この属性に対する定数値の明示的な割り当てに注意してください)。

create view PositiveSentimentsWithPolarity as
select
  'positive' as polarity,
  PS.match as sentiment
from
  PositiveSentiments PS;

create view NegativeSentimentsWithPolarity as
select
  'negative' as polarity,
  NS.match as sentiment
from
  NegativeSentiments NS;

例 2: 関数呼び出しを使用した明示的な値の割り当て

次の例では、関数呼び出しの結果が select リスト内のビュー属性に明示的に割り当てられる方法を示します。

create view Citizenship as
select
  P.Name as name,
  MatchesDict('USCities.dict', P.birthPlace) as isUSCitizen
from
  Person P;

例 3: 辞書の抽出からの select リストの式

次の例では、select リストの式で、辞書の抽出の結果から Span 型の値を選択する方法を示します。

create view PersonNames as
select N.match as name
from
  (extract
  dictionary 'firstNames.dict'
  on D.text
  as match
  from Document D
)N;

例 4: case 式の例

この最初の例では、特定のフィールドに対して NULL 処理を指定する方法を示します。

create view School as
select
case
when Not(NotNull(P.education)) then 'Unknown'
else GetString(P.education)
as name
from Person P;

次の例では、データを分類する方法を説明します。

create view Company as
select
PM.name as productname,
case
when ContainsRegex (/IBM/,PM.name) then 'IBM'
when ContainsDict ('OpenSourceDict',PM.name) then 'OSS'
else 'Unknown'
as name
from ProductMatches PM;

構文

from <from list item> <name>  [, <from list item> <name>]

説明

• <from list item\>

  ビュー、表、表関数参照、またはネストされた AQL ステートメント。 AQL では、ネストしているすべてのステートメントを括弧で囲む必要があります。

• <name\>

  selectステートメントまたはextractステートメント内で有効範囲が指定されている<from list item\>のローカル名。 ローカル名は、単純な ID でも、二重引用符付き ID でもかまいません。 スペース、句読文字、または AQL キーワードを含むローカル名を、二重引用符で囲む必要があります。

例

例 1: ビューおよびネストしたステートメントを含む from リスト

次の例は、ビューおよびネストした extract ステートメントを参照する from リストを示しています。 この例は、ステートメントの結果をローカル名 FN に割り当てます。 また、この例は、LastName ビューの出力をローカル名 Last Name に割り当てます。

create dictionary LastNamesDict as
  (
    'Anthony', 'Lehman', 'Radcliff'
  );

create view LastName as
  extract dictionary 'LastNamesDict'
  on D.text as lastname
from Document D;

create view FromList as
  select *
    from
    (extract dictionary 'first.dict' on D.text
      as firstname from Document D) FN,
      LastName "Last Name"
    where Follows(FN.firstname,
      "Last Name".lastname, 0, 1);

以下の名前は、外部辞書 first.dict に含まれています。

#Dictionary for given names
Aaron
Candra
Freeman
Mathew
Matthew
Zoraida

構文

select <select list>
  from <from list>
[where <where clause>]

説明

• <where clause\>

  1 つ以上の述部を指定します。 where 節のいずれかの述部が from リストに属する複数のビューのフィールドを含む場合に、結合が行われます。 この述部は、データ型 Boolean を返す一連の組み込み述部関数、またはその他のユーザー定義関数の論理積にしなければなりません。

  function1() and function2()
  and ... and functionn()
  

  where 節はオプションであり、select ステートメントに適用する述部がない場合は省略可能です。

例

例 1: WHERE 節の述部を使用した、結合されたタプルの除外

次の例は、0 から 1 文字後に有効な姓が続く有効な名から成る句のみを検索する where 節を示しています。

-- a view containing words that are valid given names
create view FirstName as
  extract dictionary 'first.dict'
  on D.text as firstname
from Document D;

-- a view containing words that are valid surnames
create view LastName as
  extract dictionary 'last.dict'
  on D.text as lastname
from Document D;

-- a view containing phrases consisting of valid given names
-- followed within 0-1 characters by valid surnames.
create view FullName as
  select *
  from
  FirstName FN,
  LastName LN
  where
  Follows (FN.firstname, LN.lastname, 0, 1);

以下の名前は、外部辞書 first.dict に含まれています。

#Dictionary for given names
Aaron
Candra
Freeman
Mathew
Matthew
Zoraida

以下の名前は、外部辞書 last.dict に含まれています。

#Dictionary for surnames
Anthony
Lehman
Radcliff

構文

以下のコードは、この節の一般的な構造の例です。

consolidate on <target>
  [using '<policy>'[ with priority from <priority_column>
    [ <priority_order> ]]]

説明

• <target\>

  from 節のビューの列、または引数として from 節に指定されたビューの列を含むスカラー関数呼び出しで構成される式を指定します。

• '<policy\>'

  テキスト分析でサポートされる以下の統合ポリシーの 1 つを指定します。

  • ContainedWithin

    このポリシーはデフォルトです。 スパン A とスパン B が重なり合い、A が B を完全に含む場合、このポリシーによって、スパン B を含むタプルが出力から削除されます。 A と B が同じである場合、いずれか 1 つが削除されます。 どちらのタプルが削除されるかは任意です。

  • NotContainedWithin

    スパン A とスパン B が重なり合い、A が B を完全に含む場合、このポリシーによって、スパン A が出力から削除されます。 A と B が同じである場合、いずれか 1 つが削除されます。 どちらのタプルが削除されるかは任意です。

  • ContainsButNotEqual

    このポリシーは、まったく同じスパンが保持されることを除いて、ContainedWithin と同じです。

  • ExactMatch

    いくつかのスパンがテキストの同じ領域をカバーする場合、このポリシーによって、その内の 1 つのみが返されます。 他のスパンはすべてそのまま残されます。

  • 左から右

    このポリシーによって、スパンが左から右に順に処理されます。 重なり合いが発生する場合、一番左の最も長い重なり合っていないスパンが保持されます。 このポリシーは、多くの正規表現エンジンの重なり合い処理ポリシーをエミュレートします。

• <priority\_column\>

  Text、String、Integer、または Float 型の列を指定します。 LeftToRight 統合ポリシーが指定されている場合にのみ指定できます。

• <priority\_order\>

  昇順または降順のいずれかを指定します。 LeftToRight 統合ポリシーが指定されている場合にのみ指定できます。 ascending の順を指定すると、タプル T1 の優先度が 1 でタプル T2 の優先度が 2 である場合、T1 の優先度は T2 より高くなります。 それに対し、優先度順が descending なら T2 の優先度の方が高くなります。 優先度順のデフォルト値は ascending です。

使用上の注意

• priority 節が指定された場合、統合のセマンティクスは以下の順序に従います。
  • スパンを左から右に処理し、スパンが重なり合う場合は一番左のスパンが保持されます。
  • 複数のそのような重なり合うスパンが同じオフセットで始まる場合、優先度順で最高の優先度のものが保持されます。
  • 最終的に同じ条件で残っているもののうち、同じ優先度のスパンの中で最長のスパンを保持します。
• 統合では、NULL を同一として処理します。 ヌル<consolidate target\>を持つすべての入力は、単一の出力タプルになります。このタプルは、これらの入力の中からランダムに選択されます。 この動作は、ターゲット列の同じスパンとの、タプルの統合方法に類似しています。 1 つの出力タプルになる例外は、ポリシーが ContainsButNotEqual の場合です。 その場合、ヌルの<consolidate target\>は、ヌルの集約ターゲットを持つすべての入力を出力します。

例

例 1: 単一の列での統合

この例は、すべての出力タプルのフィールド Person.name を調べて、重なり合いを解決するために ContainedWithin 統合ポリシーを使用するようにシステムに指示します。

consolidate on Person.name
  using 'ContainedWithin'

例 2: 複数の列を含む式での統合

この例は、各出力タプルの CombineSpans フィールドと Person.firstname フィールドに Person.lastname スカラー関数を適用した結果を調べるようにシステムに指示します。 ContainedWithin 統合ポリシーを使用して重なり合いを解決します。

consolidate on
  CombineSpans(Person.firstname, Person.lastname)
  using 'ContainedWithin'

例 3: LeftToRight ポリシーと優先度順を使用した統合

以下の用語タプルが入力テキスト John Doe から抽出されるとします。

match: `John`,
priority: `1`

および

match: `John Doe`,
priority: `2`

両方のスパンの開始オフセットは同じです。 優先順位の昇順の LeftToRight ポリシーを使用して統合する場合、タプル (match: John, priority: 1) が高い優先順位を持つため、保持されます。 優先順位の降順を使用して統合する場合、次の例のように、タプル (match: John Doe, priority: 2) が保持されます。

create view ConsolidatePeopleWithPrioritiesAscending as
  select P.match as match, P.weight as weight
  from People P
  consolidate on P.match
  using 'LeftToRight'
  with priority from P.weight
  ascending;

構文

select <select list>
from <from list>
[where <where clause>]
...
[group by <group by list>]

説明

• <group by list\>

  from 節およびスカラー関数呼び出しのビューの列を含む式のコンマ区切りリストを指定します。 group by 節を適用すると、すべての group by 式に関して共通の値を持つそれぞれのタプル・グループは、グループ全体を表現する 1 つの出力タプルを生成します。

  group by 節に出現しないフィールドや式は、(集約関数呼び出しで使われない限り) select リストにも出現できません。　 リスト内の式の順序は任意です。

  group by節は、すべてのヌルを同一として扱います。 NULL値を持つ列に対してGroup byを指定すると、単一グループになります。

例

例 1: 集約値の計算

集約値を計算するには、group by 節を使用します。 次の例は、文書内のそれぞれの名の出現回数を数えます。 この例では、Count は集約関数です。

create view SampleView as
  select
    GetText(P.firstname) as name,
    Count(GetText(P.firstname)) as occurrences
  from
    (extract
    dictionary 'first.dict'
    on D.text as firstname
    from Document D
    ) P
  group by GetText(P.firstname);

この場合、first.dict は、以下の項目を含む外部辞書です。

#Dictionary for given names
Aaron
Candra
Freeman
Matthew
Zoraida

以下のステップでは、このステートメントのセマンティクスについて説明します。

1. from フィールドのテキストの内容で、firstname 節で副照会によって生成されたタプルをグループ化します。
2. 各グループで、非ヌルの firstname 値を持つタプルの数をカウントします。 そのようなグループごとに、名前とそのグループ内のタプル数の 2 つの値を持つ 1 つの出力タプルを生成します。

例 2: 異なるフィールドのグループ化に関する問題

次の例は、無効なステートメントを示しています。

select GetText(P.firstname) as first,
  GetText(P.lastname) as last,
  Count(P.firstname) as occurrences
from Person P
group by GetText(P.firstname);

select リストに GetText(P.lastname) を含めることは許容されません。同じ firstname 値を持つタプルの lastname 値が異なる可能性があり、あいまいさが発生するためです。

構文

select ...
  [order by <order by list>]

説明

• <order by list\>

  式のコンマ区切りリストを指定します。

  この順序は、式のコンマ区切りリストの値に基づきます。 order by 節では、数値 (Integer または Float)、Text、または Span のデータ型を返す式がサポートされます。 order by 節の式が Span 型を返す場合、結果のタプルは、関連するスパン値を比較することによって比較されます。 次の例では、person フィールドのスパン値が比較されます。

  order by P.person
  
  

  order by 節は、NULL を (それらの中で) 順不同として処理します。 NULL は、他のオブジェクトよりも下に順序付けされます。

例

例 1: 複数の式による順序付け

person が Span 型のフィールドであるとします。 以下の order by 節は、ステートメントが各文書内のタプルを返すことを指定します。 これらは、person フィールドのテキストに基づき辞書の順序で並べ替えられ、さらに person フィールドの開始に基づき並べ替えられます。

order by GetText(P.person), GetBegin(P.person)

構文

select <select list>
  from <from list>
  ...
  [limit <maximum number of output tuples for each document>];

説明

• <maximum number of output tuples for each document\>

  各文書の出力タプルの最大数を指定します。 このしきい値が、返されるタプルの総数以上の場合は、すべてのタプルが返されます。

例

例 1: 戻り値の数の制限

この例では、各文書の最初の 3 つの個人名が返されます。

create view SampleView as
  select *
  from Person P
  order by GetBegin(P.name)
  limit 3;

構文

select <select list>
into <output view name>
from <from list>
[where <where clause>]
[consolidate on <column> [using '<policy>' [with priority from <column> [priority order]]]]
[group by <group by list>]
[order by <order by list>]
[limit <maximum number of output tuples for each document>];

説明

• <output view name\>

  ステートメントによって定義される出力ビューの名前を指定します。 select ... intoステートメントは、追加のinto <output view name\>節を除き、selectステートメントと同じです。

例

例 1: ビューの定義

この例では、PersonPhone と呼ばれるビューを定義し、このビューを出力ビューとして指定します。

select P.name as name,
  Ph.number as phoneNumber
into PersonPhone
from Person P, Phone Ph;

この例は以下の 2 つのステートメントと同等です。

create view PersonPhone as
  select P.name as name,
    Ph.number as phoneNumber
  from Person P, Phone Ph;

output view PersonPhone;

構文

detag <input view name>.<text column>
 as <output view name>
[detect content_type (always|never)]
[annotate
 element '<element name>' as <auxiliary view name>
 [with attribute '<attribute name>' as <column name>]
 [and attribute '<attribute name>' as <column name>]
 [, element ...]];

説明

• <input view name\>.<text column\>

  • <input view name\>

    タグ除去プロセスの実行対象となる入力ビューの名前を指定します。 <input view name\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。

  • <text column\>

    タグ除去プロセスの実行対象となる入力ビューのテキスト・フィールドを指定します。 <text column\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。

• <output view name\>

  タグが除去されたテキストを含む出力ビューの名前を指定します。 出力ビューには、タグが除去されたテキストを保持する text と呼ばれる単一の列が含まれます。 <output view name\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。

• always|never

  detag ステートメントが処理される前に、コンテンツが HTML または XML であることを検証するかどうかを指定します。 非HTMLと非XMLテキストをデタガーを介して実行すると、テキストに<、>、または&などのXML特殊文字が含まれている場合に問題が発生する可能性があります。 detect content_type 節が欠落している場合、デフォルト値は always になり、システムによって常にコンテンツが検出されます。

  • always

    HTML でも XML でもない文書の解析に関する問題を回避するために、操作が試行される前に常に検証が行われることを指定します。 <text column\>の値にマークアップが含まれていないように見える場合、システムは現在の文書に対するタグ除去をスキップします。

  • never

    タグ除去操作が試行される前に、検証が行われないことを指定します。 テキストに HTML や XML コンテンツがまったく含まれていない場合でも、システムは対象テキストからタグを除去しようとします。

• <element name\>

  アノテーションを付ける HTML または XML エレメントの名前を指定します。 オプションの annotate 節で、1 つ以上のビューを作成して、除去されるタグに関する情報を覚えておくようにランタイム・コンポーネントに指示できます。

• <auxiliary view name\>

  元のタグとその属性を保持するために作成されるビューの名前を指定します。 これは、単純な ID でも、二重引用符付き ID でもかまいません。

• <attribute name\>

  HTML または XML エレメントの属性の名前。

• <column name\>

  <attribute name\>の値を保存するために使用される<auxiliary view name\>内の列の名前。 これは、単純な ID でも、二重引用符付き ID でもかまいません。

例

例 1: タグ除去出力ビューと補助ビューの指定

この例では、ビュー DetaggedDoc の text 属性の元のテキストのタグが除去されたバージョンを保持するための Document ビューが作成されます。 DetaggedDoc ビューに加えて、annotate 節によって、Anchor という名前の補助ビューが作成されます。 この補助ビューには 2 つの列があります。 match という 1 つの列には、アンカー・テキストが含まれます。 linkTarget というもう 1 つの列には、リンクの実際のターゲットがテキストとして含まれます。 match 列のスパンは DetaggedDoc ビューのテキスト値に対するものです。

detag Document.text as DetaggedDoc
annotate
  'a' as Anchor
  with attribute 'href' as linkTarget;

例 2: Remap 関数の使用

以下の例では、Remap 関数を使用して、タグが除去されたテキストからのスパンを、元のソースの対応するスパンにマップする方法を示しています。

-- Strip out tags from each document, provided that the document
-- is in HTML or XML format.
-- Remember the locations and content of all <A> and <META> tags
-- in the original source document.
detag Document.text as DetaggedDoc
detect content_type always
annotate
  element 'a' as Anchor
    with attribute 'href' as target,
  element 'meta' as Meta
    with attribute 'name' as name
    and attribute 'content' as content;

output view DetaggedDoc;

-- Create a view containing all lists of keywords in the
-- document's META tags.
create view MetaKeywordsLists as
select M.content as list
from Meta M
where MatchesRegex(/keywords/, 'CASE_INSENSITIVE', M.name)
  and NotNull(M.content);

-- Create a dictionary of "interesting" web sites
create dictionary InterestingSitesDict as
(
  'ibm.com', 'slashdot.org'
);

-- Create a view containing all anchor tags whose targets contain
-- a match of the "interesting sites" dictionary.
create view InterestingLinks as
select A.match as anchortext, A.target as href
from Anchor A
where ContainsDict('InterestingSitesDict', A.target);

-- Find all capitalized words in the anchor text of links to
-- "interesting" web sites.
create view InterestingWords as
extract I.href as href,
  regex /[A-Z][a-z]+/ on 1 token in I.anchortext as word
from InterestingLinks I;

-- Map spans in the InterestingWords view back to the original
-- HTML or XML source of the document.
create view InterestingWordsHTML as
select I.href as href, Remap(I.word) as word
from InterestingWords I;

AQL 文書による detag ステートメントの文書化

detag ステートメントの AQL 文書コメントには、次の情報が含まれます。

• ステートメントの機能に関する一般的な説明。
• タグ除去プロセスの実行対象となる入力ビューの各テキスト・フィールドを表す @field。
• @auxView はビュー名を指定します。
• @auxViewField は、ビューの完全修飾列名を指定します。

/**
* Detags the input document
* @field text the detagged text of the document
* @auxView Anchor stores the anchor points from tagged doc
* @auxViewField Anchor.linkTarget stores the href attribute of anchor tag
*/

detag Document.text as DetaggedDoc
  annotate element 'a' as Anchor
  with attribute 'href' as linkTarget;

構文

内部の create dictionary ステートメントには、from file、from table、およびインライン形式の 3 つの構文形式があります。

• 内部辞書

  From file:

  create dictionary <dictionary name>
  
   from file '<file name>'
   [with language as '<language code(s)>']
   [and case (exact | insensitive)]
   [and lemma_match];
  

  from table:

  create dictionary <dictionary name>
  
    from table <table name>
    with entries from <column name>
    [and language as '<language code(s)>']
    [and case (exact | insensitive)]
    [and lemma_match];
  

  インライン形式

  create dictionary <dictionary name>
  [with language as '<language code(s)>']
  [and case (exact | insensitive)]
  [and lemma_match]
   as
      (
      '<entry 1>', '<entry 2>', ... , '<entry n>'
      )
  ;
  

• 外部辞書

  create external dictionary <dictionary-name>
  required [true|false]
  [with language as '<language codes\>']
  [and case (exact | insensitive )]
  [and lemma_match];
  

説明

• <dictionary name\>

  新しい内部辞書または外部辞書の名前を指定します。 これは、単純な ID でも、二重引用符付き ID でもかまいません。

• '<file name\>'

  辞書項目を含むファイルの名前を指定します。 辞書ファイルは、行ごとに辞書項目を 1 つ持つ改行で区切られたテキスト・ファイルです。 辞書ファイル内の項目は、複数のトークンで構成することができます。

• <table name\>

  辞書項目の追加元の表の名前を指定します。 別のモジュールからインポートされた表から辞書を作成することはできません。

• <column name\>

  辞書項目の追加元の表の列の名前を指定します。

• required [true|false]

  モジュールを実行するために外部辞書の外部コンテンツを必要とするかどうかを指定します。

  • true

    節が required true の場合、外部コンテンツを含むファイルの場所の URI を指定する必要があります。 指定したファイルにコンテンツが含まれている必要があります。 URI が指定されない場合、またはファイルにコンテンツが含まれない場合、ランタイム・コンポーネントは例外をスローします。

  • false

    節が required false の場合、この辞書に対して外部コンテンツの URI が指定されない場合でも、モジュールを正常に実行できます。 URI が指定されない場合、ランタイム・コンポーネントはそれを空の辞書として扱います。

  create external dictionary <dictionary-name\> allow_emptyの使用は推奨されなくなったため、コンパイラー警告が出されます。

• '<language code(s)\>'

  辞書を評価する言語または外部辞書の文書言語の en (英語) や zh (中国語) などの 2 文字の言語コードのコンマ区切りリストを指定します。 このストリングに言語コードが含まれていない文書については、辞書は結果を生成しません。

  language パラメーターを指定しないと、辞書の言語は、次のいずれかの言語セットにデフォルト設定されます。

  • 宣言されている場合は、収容モジュールで set default language ステートメントで指定された言語セット
  • ドイツ語 (de)、スペイン語 (es)、英語 (en)、フランス語 (fr)、イタリア語 (it)、および未指定の言語 (x_unspecified) を含む言語セット

• lemma_match

  文書内の辞書の用語に類似した単語の一致を検索するには、見出し語化を使用します。

  見出し語化は、特定の単語の見出し語を決定するプロセスです。 見出し語は、1 つの特定の用語に対する一致として使用できる単語です。 例えば、用語「go」は、「goes」、「going」、「gone」、または「went」の用語と一致することができます。 このプロセスには、コンテキストの理解や、文の中での単語の品詞の判別などの、複雑なタスクが含まれます。 見出し語化は、IBM マルチリンガル・トークナイザーが品詞サポートを提供するすべての言語で使用可能です。

  見出し語のマッチングは、lemma match 節で宣言された辞書に対してのみ実行されます。

  lemma_match 節を使用した辞書の抽出のセマンティクスは、次のとおりです。

  • 入力文書の各トークンの見出し語化された形式が計算されます。
  • 辞書は見出し語化された文書に対して評価されます。 lemma_match オプションと case exact オプションは一緒には使用できません。 両方を使用すると、コンパイラー・エラーが返されます。

• case (exact | insensitive)

  文書の特定の領域が一致するかどうかを判別するときに辞書が実行する大文字変換のタイプを指定します。

  • exact

    大/小文字の区別がある完全一致を指定します。

  • insensitive

    大/小文字の区別をしない一致を指定します。 このオプションはデフォルト値です。

• '<entry 1\>', '<entry 2\>', ... , '<entry n\>'

  インライン辞書に含めるストリングを指定します。 インライン辞書の項目は、1 つ以上のトークンで構成することができます。

使用上の注意

• from file と from table の形式を推奨します。特に、項目の変更が予期される場合や、多数の項目がある場合にお勧めします。 これらの形式を使用すると、コードを変更せずに辞書のコンテンツを変更できます。

• create dictionary ステートメントがモジュラー AQL コンパイラーによって処理される場合、create dictionary ... from file 構文で指定された辞書ファイルの場所の参照は、この create dictionary ステートメントを発行するモジュールのルートを基準にする必要があります。

• コメントの前に文字 # を付けることによって、辞書ファイルのコメントを指定できます。 コメントは、行内の任意の場所から開始できます。

• 複数の行にまたがるコメントを指定する場合は、各行の先頭にコメント文字を付ける必要があります。 コメント文字が辞書項目の一部である場合は、\# のように円記号 (\) を使用してエスケープする必要があります。 円記号が辞書項目の一部である場合は、\\ のように、それ自体でエスケープする必要があります。

• 外部辞書については、モジュールがロードされるときに、ロードされるモジュールに必要な、外部辞書への URI のリストを指定する必要があります。

• 辞書の見出し語化: 既存の辞書のマッチングのセマンティクスと見出し語化されたセマンティクスの主な違いは、文書の元の形式ではなく、文書の見出し語化された形式に対してマッチングが実行されることです。

  見出し語のマッチングが有効になっている辞書に属する辞書項目には、以下の前提条件があります。

  • 辞書項目には、1 つ以上のトークンを含めることができます。ここで、各項目のトークンは見出し語です。 見出し語の辞書を作成するには、[GetLemma スカラー関数を使用します。
  • 辞書項目のトークンは、空白文字で区切る必要があります。 トークンが空白文字で構成されている場合は、円記号 (\) を使用して空白文字をエスケープする必要があります。

• 次の表に、create external dictionary ステートメントと create dictionary ステートメントの相違点を示します。

例

例 1: 外部辞書の作成

外部辞書 PersonPositiveClues では、ロード時に外部ファイルからの値が取り込まれることが予期されます。 また、そのフラグで指定されたとおりに、一部の西洋言語に対してマッチングされることも予期されます。

module PersonModuleEnglish;

create external dictionary PersonPositiveClues
  allow_empty false
  with case exact;

export dictionary PersonPositiveClues;

例 2: 見出し語化

見出し語のマッチングが有効になっており、go shop と went shopping の 2 つの項目を含む辞書を考えてみます。 文書にはテキスト Anna went shopping が含まれます。 入力文書の見出し語化された形式は、Anna go shop です。 見出し語のマッチングにより、項目 go shop の一致として、went shopping が返されます。 元の文書テキストは、辞書項目とは比較されません。見出し語化された文書テキストのみが対象となります。 したがって、項目 went shopping については、文書に一致はありません。

AQL 文書による create dictionary ステートメントおよび create external dictionary ステートメントの文書化

create dictionary ステートメントの AQL 文書コメントには、次の情報が含まれます。

辞書に関する一般的な説明

/**
* A dictionary of terms used to greet people.
*
*/

create dictionary GreetingDict as
(
  'regards', 'regds', 'hello', 'hi', 'thanks', 'best', 'subj', 'to', 'from'
);

create external dictionary ステートメントの AQL 文書コメントには、作成された辞書に関する一般的な説明が含まれます。 次のストリングは、形式を示しています。

/**
 * Customizable dictionary of given names.
 * Evaluated on English, French, Italian, German, Portuguese, Spanish text.
 */
create external dictionary CustomFirstNames_WesternEurope
  allow_empty true;

構文

create table <table name> (
    <colname> <type> [,  <colname> <type>]* )
 as values
    ( <value> [, <value>]*),
    ...
    ( <value> [, <value>]*);

説明

• <table name\>

  作成する表の名前を指定します。 <table name\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。

• <colname\>

  作成する列の名前を指定します。

• <type\>

  関連する列の AQL データ型を指定します。 すべての列は、Text、Integer、Float、または Boolean の型である必要があります。

• <value\>

  作成された表に取り込まれるタプルを指定します。

例

例 1: 会社名の表の作成

この例では、create table ステートメントにより、会社名のアノテーションにさらに場所メタデータが追加されます。

-- Create a dictionary of company names
create dictionary CompanyNames as
  ('IBM', 'BigCorp', 'Initech');

-- Find all matches of the company names dictionary.
create view Company as
  extract
    dictionary 'CompanyNames' on D.text as company
  from Document D;


-- Create a table that maps company names to locations of
-- corporate headquarters.
create table NameToLocation
  (name Text, location Text) as
  values
  ('IBM', 'USA'),
  ('BigCorp', 'Apex'),
  ('Initech', 'Dallas'),
  ('Acme Fake Company Names', 'Somewhere');

-- Use the table to augment the Company view with location
-- information.
create view CompanyLoc as
  select N2C.location as loc,
          C.company as company
  from Company C, NameToLocation N2C
  where Equals(GetText(C.company), GetText(N2C.name));

output view CompanyLoc;

AQL 文書による create table ステートメントの文書化

create table ステートメントの AQL 文書コメントには、次の情報が含まれます。

• 表に関する一般的な説明
• この表のスキーマのすべての列名を表す @field

/** Create a table that maps company names to locations
/** of corporate headquarters.
* @field name name of the company
* @field location location of corporate headquarters
*/

create table NameToLocation
  (name Text, location Text) as
 values
  ('IBM', 'USA'),
  ('Enron', 'UK'),
  ('Initech', 'Dallas'),
  ('Acme Fake Company Names', 'Somewhere');

構文

create external table <table-name\>
  (<colname\> <type\>
   [,  <colname\> <type\>]* )
   allow_empty <true|false>;

説明

• <table-name\>

  作成する外部表の名前を指定します。 <table-name\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。

• <colname\>

  作成する列の名前を指定します。

• <type\>

  関連する列の AQL データ型を指定します。 すべての列は、Text、Integer、Float、または Boolean の型である必要があります。

• [, <colname\> <type\>]*

  外部表で使用される追加の列および AQL オブジェクトを指定します。

• allow_empty [true|false]

  allow_empty 節の値を指定します。

  • true

    節が allow_empty true の場合、この表に対して外部コンテンツの URI が指定されない場合でも、モジュールを正常に実行できます。 URI が指定されない場合、ランタイム・コンポーネントはそれを空の表として扱います。

  • false

    節が allow_empty false の場合、外部コンテンツを含むファイルの場所の URI を指定する必要があります。 指定したファイルにコンテンツが含まれている必要があります。 URI が指定されない場合、またはファイルにコンテンツが含まれない場合、ランタイム・コンポーネントは例外をスローします。

使用上の注意

• モジュールのコンパイル済み表記には、モジュールが定義する外部オブジェクト (ビュー、辞書、および表) に関するメタデータが含まれます。
• モジュールがロードされるときに、ロードされるモジュールに必要な、外部表への URI のリストを指定する必要があります。
• 外部表のコンテンツのサポートされる形式は、ヘッダー付きの 1 つの CSV (.csv) ファイルです。

次の表に、create external table ステートメントと create table ステートメントの相違点を示します。

例

例 1: ロード時にデータが取り込まれる外部表の作成

外部表 PersonNegativeClues では、フラグ allow_empty false が原因でロード時にデータが取り込まれることが予期されます。

module PersonModuleFrench;

create external table PersonNegativeClues (name Text)
  allow_empty false;

export table PersonNegativeClues;

例 2: 外部表を持つ辞書の作成

create table ステートメントで宣言されたインライン表から作成される場合と同様に、外部表から辞書を作成することもできます。

create external table Product (nickName Text, formalName Text)
allow_empty false;

/**
  * Dictionary of product nicknames, from the nickName field
  * of the customizable external table Product.
  */
create dictionary ProductDict
from table Product
with entries from nickName;

AQL 文書による create external table ステートメントの文書化

create external table ステートメントの AQL 文書コメントには、次の情報が含まれます。

• 表に関する一般的な説明
• この表のスキーマのすべての列名を表す @field

/** Create a table that maps company names to locations of corporate headquarters.
* @field name name of the company
* @field location location of corporate headquarters
*/
create external table Company2Location
  (name Text, location Text)
   allow_empty false;

構文

create external view <view_name> (
        <colname> <type> [, <colname> <type>]*
        )
external_name '<view_external_name>';

説明

• <view_name\>

  外部ビューの内部名を指定します。 外部ビューは、この名前で AQL 規則で参照されます。 <view_name\>は、単純なIDまたは二重引用符で囲んだIDにすることができます。 <view_name\>にピリオド文字を含めることはできません。

• <colname\>

  外部ビューで定義する列の名前を指定します。

• <type\>

  関連する列のデータ型を指定します。 外部ビューの列でサポートされるデータ型は、Text、Span、Integer、および Float です。

• '<view_external_name\>'

  外部ビューの外部名を指定します。 外部ビューにタプルを取り込む外部システムは、外部名で外部ビューを参照します。 '<view_external_name\>'は、単一引用符で囲まれたストリング定数 ('ExternalName ') でなければなりません。

例

外部ビューを説明するために、E メール・メッセージ内の個人の名前を識別する必要があるサンプル・アプリケーションを考えてみます。

例 1: E メール・メッセージ内の個人の名前の識別

E メール・メッセージのテキストが「Ena, please send me the document ASAP」であるとします。 人間は、E メールのテキストに基づいて、Ena が個人の名前であることを理解できますが、一般的なテキストから高い精度で個人の名前を識別するために作成された AQL 規則は、控えめすぎて、Ena が大文字で始まる単語であるという事実に基づいて、高い信頼性で同じ結論を導き出すことができない場合があります。

規則の適用を強化する 1 つの方法は、E メールの送信元、送信先および CC の各フィールドのワードを使用する方法です。

E メールのアドレスが「Ena Smith」であり、アプリケーションがこの情報を抽出プログラムで使用できるようにすると、抽出プログラム開発者は追加の AQL 規則を作成して、通常 E メールが人に対してアドレス指定されるドメイン・ナレッジに基づく抽出プログラムの適用を強化できます。

例えば、E メールのメタデータ・フィールドから個人のトークンを識別するための AQL 規則を作成できます。 その後、E メール・テキスト内の大文字で始まるトークンが個人名であるかどうかを判別する際に、その情報を強力な手掛かりとして使用します。 一般に、E メールのメタデータは実際の E メール・メッセージの一部ではありませんが、アプリケーションでは、外部ビューを使用して、抽出プログラムでこのメタデータを使用できるようにすることが可能です。

アプリケーションでは、処理が必要な E メールごとに、実行時に E メール・テキストを文書テキストとして渡すことができます (ビュー Document にデータを設定できます)。 また、適切に定義された外部ビューを使用して、追加のメタデータを渡すこともできます。

以下のステートメントは、EmailMetadata という名前の外部ビューを定義します。 外部ビューには、Text 型の 3 つのフィールドを含むスキーマがあります。 実行時に、ビュー EmailMetadata は EmailMetadataSrc という名前の外部型から自動的にデータが設定されます。 その後、AQL 規則で、他のビューを参照する方法と同じように、EmailMetadata ビューを参照できます。

create external view EmailMetadata
  (fromAddress Text, toAddress Text, ccAddress Text)
external_name 'EmailMetadataSrc';

AQL 文書による create external view ステートメントの文書化

create external view ステートメントの AQL 文書コメントには、次の情報が含まれます。

• ビューに関する一般的な説明
• ビュー内のすべての列名を表す @field

/**
* The external view named EmailMetadata, containing three fields
* of type Text. At run time, the view EmailMetadata is
* automatically populated from an external type named
* EmailMetadataSrc.
*
* @field from the fromAddress field of the email
* @field to the toAddress field of the email
* @field cc the ccAddress field of the email
*/

create external view EmailMetadata(fromAddress Text, toAddress Text, ccAddress Text)
external_name 'EmailMetadataSrc';

外部辞書

外部辞書の項目を含むファイルの形式は、以下のように定義されます。

• 改行で区切られたテキスト・ファイル。
• 行ごとに 1 つの辞書項目。
• 推奨されるファイル拡張子は .dict ですが、その他のファイル拡張子がサポートされることがあります。
• 辞書内の項目は、複数のトークンで構成することができます。
• コメントの内容の前に文字 # を付けることによって、コメントを指定できます。
• コメントは、行内の任意の場所から開始できます。
• 複数行のコメントでは、各行の先頭に # 文字が含まれている必要があります。
• 辞書項目には、それぞれが円記号でエスケープされたコメント文字を含めることができます。 例えば、\#のように。

外部表

外部表のコンテンツのサポートされるファイル形式は、ヘッダー付きの .csv ファイルです。

次の例は、create external table ステートメントと、この外部表のコンテンツを指定する .csv ファイルを示しています。

create external table Company2Location
  (name Text, location Text)
   allow_empty false;

.csv ファイルの最初の行には、ヘッダーが含まれます。 残りの行にはデータが含まれます。

name,location
IBM,USA
Infosys,India
LG,Korea
Vodafone,UK

外部ビュー

外部ビューのコンテンツは、以下の方法で指定できます。

• 抽出プログラムを実行する場合、JSON 入力フォーマットを使用している場合にのみ、データ収集の外部ビュー・コンテンツを指定できます。

例

次の例では、集約関数でどのように人の名前のアノテーションの数を数えることができるか、文書内で識別される別々の姓それぞれと関連する名のセットをどのように計算できるかを示します。

-- identify occurrences of given names in the document
create view FirstName as
extract dictionary 'firstNames.dict' on D.text as name
from Document D;

-- identify occurrences of surnames in the document
create view LastName as
extract dictionary 'lastNames.dict' on D.text as name
from Document D;

-- identify complete person names in the document
create view Person as
select F.name as firstname, L.name as lastname
from FirstName F, LastName L
where FollowsTok(F.name, L.name, 0, 0);

-- count the number of person annotations in the document
create view CountPerson as
select Count(*)
from Person;

-- for each distinct surname, output a list of given names associated with it in the document
create view FamilyMembers as
select GetText(P.lastname) as lastname, List(GetText(P.firstname)) as firstnames
from Person P
group by GetText(P.lastname);

次の例では、Min 関数と Max 関数の使用を示します。

-- Extract stop words from input text
create view StopWords as
extract
regex /\s(the|in|a|an|as|to|from)\s/ on D.text as match
from Document D;


-- Count the number of times each stop word matched above, was used in the text
create view StopWordsCount as
select
GetText(S.match) as stopword,
Count(S.match) as stopwordcount
from StopWords S
group by GetText(S.match);

-- Retrieve the most used and least used stop word count
create view StopWordUsageCount as
        select Min(S.stopwordcount) as least, Max(S.stopwordcount) as most
from StopWordsCount S;

および

And 関数は、可変数のブール引数を受け入れ、すべての入力引数に対する論理 AND 操作の結果を返します。

AQL オプティマイザーは、この関数の引数の評価順序を、論理 AND 操作の一部として最適化しようとしません。 入力が null の場合、結果は null になります。

次の照会形式を考えてみます。

select ...
from ...
where And(predicate1, predicate2);

この結果、AND 操作を使用する照会形式は、以下の形式を使って同じ照会を実行する場合と比べて、通常はかなり遅くなります。

select ...
from ...
where predicate1 and predicate2;

可能であれば、この関数の代わりに SQL スタイルの and キーワードを使用してください。

次を含む

Contains 関数は、次のように 2 つのスパンを引数として取ります。

Contains(<span1>, <span2>)

TRUE の中に span1 が完全に含まれる場合、この関数は span2 を戻します。 span2 が span1 の先頭またはその後で開始し、span1 の末尾またはその前で終了する場合、span2 は完全に含まれます。 いずれかの引数が null の場合、関数は null を戻します。

ContainsDict

ContainsDict 関数は、スパンのテキストに、特定の辞書からの項目が含まれているかどうかを検査します。 この関数は、入力引数として、辞書、オプションのフラグ指定、および評価対象のスパンを受け入れます。

ContainsDict('<dictionary>', ['<flags>', ]<span>)

辞書のマッチがスパンに 1 つ以上含まれる場合、ContainsDict 関数は TRUE を戻します。 フラグとして Exact または IgnoreCase が可能です。

• Exact を使用すると、辞書内の各用語に対して大/小文字を区別するマッチングが実行されます。
• IgnoreCase を使用すると、辞書内の各用語に対して実行されるマッチングで大/小文字が区別されません。
• フラグが指定されない場合、辞書は、作成時に指定されたフラグに基づいてマッチングされます。 作成時にフラグが指定されなかった場合は、IgnoreCase フラグを使用してマッチングされます。

スパンが null の場合、関数は null を戻します。

次の例では、ContainsDict 関数の使用方法を示します。

create dictionary EmployeePhoneDict as
(
 '121-222-2346', '121-234-1198', '121-235-8891'
);

create view PhoneNum as
extract regex /(\d{3})-(\d{3}-\d{4})/
    on between 4 and 5 tokens in D.text
    return
        group 1 as areaCode
        and group 2 as restOfNumber
        and group 0 as number
from Document D;

create view PhoneNumbers as
select P.number as number
from PhoneNum P
where ContainsDict('EmployeePhoneDict',P.number);

辞書は常にトークン境界で評価されます。 例えば、辞書が用語 fish から構成される場合、テキスト Let's go fishing! には一致がありません。

ContainsDicts

ContainsDicts 関数は、スパンのテキストに、特定の複数の辞書からの項目が含まれているかどうかを検査します。 この関数は、入力引数として、複数の辞書、オプションのフラグ指定、および評価対象のスパンを受け入れます。

ContainsDicts('<dictionary>','<dictionary>','<dictionary>', ['<flags>', ]<span>)

1 つ以上の指定された辞書のマッチがスパンに 1 つ以上含まれる場合、ContainsDicts 関数は TRUE を戻します。 フラグとして Exact または IgnoreCase が可能です。

• Exact を使用すると、複数の辞書のそれぞれの用語に対して大/小文字を区別するマッチングが実行されます。
• IgnoreCase を使用すると、複数の辞書のそれぞれの用語に対して実行されるマッチングで大/小文字が区別されません。
• フラグが指定されない場合、辞書は、作成時に指定されたフラグに基づいてマッチングされます。 作成時にフラグが指定されなかった場合は、IgnoreCase フラグを使用してマッチングされます。

一方または両方の引数が NULL の場合、関数は null を戻します。

以下の例は ContainsDicts フラグを含む Exact 関数の使用法を例示しています。

create view PersonWithFirstName as
select P.reference as reference
from Person P
where ContainsDicts(
'FirstNamesUsedGlobally',
'FirstNamesUsedInGermanyLong',
'NickNamesUsedGlobally',
'FirstNamesUsedInGermanyShort',
'FirstNamesUsedInItaly',
'FirstNamesUsedInFrance',
'Exact',
P.reference);

ContainsRegex

ContainsRegex 関数は、スパンのテキストが特定の正規表現と一致するかどうかを検査します。 この関数は、マッチングに使用する正規表現、オプションのフラグ指定、およびマッチング対象の入力スパンを受け入れます。

ContainsRegex(/<regular expression>/, ['<flags>', ]<span>)

別個の Java™ ストリングとして取られるスパンのテキストに正規表現のマッチが 1 つ以上含まれる場合、この関数は TRUE を戻します。 スパンが null の場合、関数は null を戻します。 オプションのフラグは、Java 正規表現で使われるフラグと同様に、マッチング動作に影響を与えます。

「flags」ストリングを形成するには、区切り文字として | を使用し、以下の 1 つ以上のフラグを組み合わせます。

• CANON_EQ
• CASE_INSENSITIVE
• DOTALL
• リテラル
• MULTILINE
• UNICODE (meaningless without CASE_INSENSITIVE)
• UNIX_LINES

flags ストリングの例

'UNICODE | CASE_INSENSITIVE'

次の例を考えてみます。ここで、ContainsRegex は、製品名と、前後のバージョン番号のメンションを識別します。 MatchesRegex の例とは異なり、バージョン番号の一致は厳密には regex を使用して識別されず、regex に対して一致するトークンを含む製品名のメンションの前後のコンテキストによって識別されます。

-- dictionary of product names
create dictionary ProductNamesDict as
(
  'IBM WebSphere Application Server',
  'Microsoft Windows',
  'Apple Mac OS',
  'IBM Rational Application Developer',
  'Apache HTTP Server',
  'Eclipse',
  'Google Android'
);

-- extract product names from input text
create view ProductNames as
extract
  dictionary 'ProductNamesDict'
  on D.text as name
from Document D;

-- gather context around product name mention
create view ProductNamesWithContext as
select
  P.name as name,
  LeftContext(P.name, 5) as leftctxt,
  RightContext(P.name, 5) as rightctxt
from ProductNames P;

-- use a regex to identify products with version number mentions on either sides of the product mention
create view ProductsWithVersionNumbers as
(
  select
    P.name as productname,
    P.leftctxt as productversion
  from ProductNamesWithContext P
  where ContainsRegex (/v\d((\.\d)+)?/, P.leftctxt)
)
union all
(
  select
    P.name as productname,
    P.rightctxt as productversion
  from ProductNamesWithContext P
  where ContainsRegex (/v\d((\.\d)+)?/, P.rightctxt)
);

等しい

Equals 関数は、次のように任意のタイプの 2 つの引数を取ります。

Equals(<arg1>, <arg2>)

2 つのスパンは、同じオフセットで開始して終了し、同じテキストを含んでいる場合に、等しいと見なされます。 一方または両方の引数が NULL の場合、関数は null を戻します。

以下の例は Equals 関数の使用法を例示しています。

-- Select phone number spans whose text is equal to 001-543-2217
create view PhoneNumber as
select P.number as number
from PhoneNum P
where Equals('001-543-2217',GetText(P.number));

Follows

Follows 述部関数は、次のように 2 つのスパン引数と 2 つの整数引数を取ります。

Follows(<span1>, <span2>, <minchar>, <maxchar>)

TRUE の終了と span1 の開始の間にある文字数が span2 から minchar の境界を含む範囲に入っている場合、この関数は maxchar を戻します。 いずれかの引数が null の場合、関数は null を戻します。

FollowsTok

FollowsTok 述部関数は、Follows の 1 つのバージョンです。ただし、FollowsTok の距離引数は、文字の代わりにトークンに関連します。

FollowsTok(<span1>, <span2>, <mintok>, <maxtok>)

FollowsTok の終了と TRUE の開始の間にあるトークン数が span1 から span2 の境界を含む範囲に入っている場合、mintok 関数は maxtok を戻します。 いずれかの引数が null の場合、関数は null を戻します。

GreaterThan

GreaterThan 述部関数は、任意のタイプの 2 つの引数を取ります。

GreaterThan(<arg1>, <arg2>)

この関数は、<arg1>が<arg2>より大きい場合にTRUEを返します。 いずれかの引数が FALSE の場合、関数は null を戻します。

IsNull

IsNull 関数は、データが NULL かどうかをテストします。 これは、任意のタイプの単一の引数を取り、単一の引数が TRUE の場合に null を戻し、それ以外の場合に FALSE を戻します。 この述部および既に定義されている NotNull 述部の動作は、NULL の入力に対して NULL を返す他のすべての述部とは異なります。

MatchesDict

MatchesDict 関数は、辞書 (「辞書の抽出」にあるとおり)、オプションのフラグ指定、およびスパンを引数として取ります。

MatchesDict('<dictionary>', ['<flags>', ]<span>)

スパンが辞書内の 1 つ以上の用語と完全に一致する場合、MatchesDict 関数は TRUE を戻します。 フラグとして Exact または IgnoreCase が可能です。

• Exact を使用すると、辞書内の各用語に対して大/小文字を区別するマッチングが実行されます。
• IgnoreCase を使用すると、辞書内の各用語に対して実行されるマッチングで大/小文字が区別されません。
• フラグが指定されない場合、辞書は、作成時に指定されたフラグに基づいてマッチングされます。 作成時にフラグが指定されなかった場合は、IgnoreCase フラグを使用してマッチングされます。

いずれかの引数が null の場合、関数は null を戻します。

辞書は常にトークン境界で評価されます。 例えば、辞書が用語 fish から構成される場合、テキスト Let's go fishing! には一致がありません。

MatchesRegex

MatchesRegex 関数の構文は、ContainsRegex と似ています。 ContainsRegex 関数とは異なり、MatchesRegex 関数は、(別個の Java ストリングとして取得される) スパンのテキスト全体が正規表現にマッチする場合にのみ、TRUE を戻します。 いずれかの引数が null の場合、関数は null を戻します。 オプションのフラグは、Java 正規表現で使われるフラグと同様に、マッチング動作に影響を与えます。

MatchesRegex(/<regular expression>/, ['<flags>', ]<span>)

「flags」ストリングを形成するには、区切り文字として | を使用し、以下のフラグのサブセットを組み合わせます。

• CANON_EQ
• CASE_INSENSITIVE
• DOTALL
• リテラル
• MULTILINE
• UNICODE (meaningless without CASE_INSENSITIVE)
• UNIX_LINES

flags ストリングの例

'UNICODE | CASE_INSENSITIVE'

次の例を考えてみます。ここで、MatchesRegex は、製品名と、右側のバージョン番号のメンションを識別するために使用されます。 ContainsRegex セクションの例とは異なり、製品名のメンションの直後のトークンとして、正確なバージョン番号が識別されます。

-- gather right context around product name mention
create view ProductNamesWithContext as
select
  P.name as name,
  RightContext(P.name, 5) as rightctxt
from ProductNames P;

-- use a regex to identify products with version number mentions to the right
create view ProductsWithVersionNumbers as
select
  P.name as productname,
  P.rightctxt as productversion
from ProductNamesWithContext P
where MatchesRegex (/v\d((\.\d)+)?/, P.rightctxt);

Not

Not 関数は 1 つのブール引数を取り、その補数を戻します。 引数が null の場合、関数は null を戻します。

NotNull

NotNull 関数は、任意のタイプの 1 つの引数を取ります。

名前から推測されるように、NotNull 関数は引数の値が NULL ではない場合に TRUE を戻し、引数が FALSE の場合に null を戻します。

それとも

Or 関数は可変数の NULL 以外のブール引数を取ります。 いずれかの引数が null の場合、関数は null を戻します。

これらのいずれかが Or と評価される場合、TRUE 関数は TRUE を戻します。

オーバーラップ

Overlaps 関数は、次のように 2 つのスパン引数を取ります。

Overlaps(<span1>, <span2>)

2 つの入力スパンがドキュメント・テキスト内でオーバーラップする場合、この関数は TRUE を戻します。 いずれかの引数が null の場合、関数は null を戻します。

Chomp

Chomp 関数は Perl の Chomp 演算子と似ていますが、相違点として Chomp はストリングではなくスパンを操作対象とします。

Chomp(<span1>)

以下の例は Chomp 関数の使用法を例示しています。

detag Document.text as DetaggedDoc
annotate
element 'a' as Anchor
with attribute 'href' as linkTarget;

create view Links as
select Chomp(A.linkTarget) as link
from Anchor A;

入力スパンの始まりまたは終わりに空白が含まれる場合、Chomp 関数は、空白を除去してスパンを縮小します。 その後、この関数は、先頭/末尾に空白がない新しいスパンを戻します。 入力スパンの先頭/末尾のどちらにも空白が含まれない場合、Chomp 関数は同じスパンを戻します。 入力スパンが null の場合、Chomp は null を戻します。

CombineSpans

CombineSpans 関数は 2 つのスパンを入力として取り、スパンが同じテキスト・オブジェクトに基づいている場合に、両方の入力スパンが完全に収まる最短のスパンを戻します。

CombineSpans(['IgnoreOrder',] <span1>, <span2>)

CombineSpans 関数は、IgnoreOrder パラメーターを使用しない限り、入力スパンの順序の影響を受けます。 オプションの IgnoreOrder パラメーターを使用する場合、2 つのスパンの順序は無視されます。

以下の例は CombineSpans 関数の使用法を例示しています。

create view FullName as
     select
             CombineSpans('IgnoreOrder',F.name, L.name) as fullName
     from
             FirstName F,
             LastName L
     where
             FollowsTok(F.name, L.name, 0,0);

この関数のセマンティクスは、以下のとおりです。

• span1 または span2 が null であるか、または 2 つのスパンが異なる Text オブジェクトを対象としている場合、この関数は null を戻します。
• それ以外の場合で、span1 が span2 よりも小さいか、IgnoreOrder パラメーターが使用されている場合、この関数は span1 と span2 の両方が収まる最短のスパンを戻します。
• それ以外の場合 (span1 が span2 よりも大きく、IgnoreOrder が使用されていない場合)、この関数はランタイム・エラーを戻します。

CombineSpans 関数に対する引数のさまざまなシナリオは、スパンの定義に基づいて以下のようになります。

• スパン2は常にスパン1の後にあります。 つまり、左から右への順序が維持されます。

  CombineSpans([0,7], [3,7]) returns the span [0,7]
  CombineSpans([0,7], [8,10]) returns the span [0,10]
  CombineSpans([0,7], [3,6]) returns the span [0,7]
  CombineSpans([0,7], [0,7]) returns the span [0,7]
  

• スパン2はスパン1より後ではありません。 つまり、左から右への順序は 維持されません。

  CombineSpans(‘IgnoreOrder’, [0,10], [0,7]) returns the span [0,10]
  CombineSpans(‘IgnoreOrder’, [3,6], [0,7]) returns the span [0,7]
  CombineSpans(‘IgnoreOrder’, [3,7], [0,7]) returns the span [0,7]
  CombineSpans(‘IgnoreOrder’, [8,10], [0,7]) returns the span [0,10]
  CombineSpans([3,6], [0,7]) will result in Runtime error as the IgnoreOrder flag has not been specified.
  

GetBegin および GetEnd

GetBegin 関数は 1 つのスパン引数を取り、その入力スパンの開始オフセットを戻します。

例：

GetBegin([5, 10])

これは値 5 を戻します。

同様に、GetEnd 関数は入力スパンの終了オフセットを戻します。

以下の例は GetBegin および GetEnd 関数の使用法を例示しています。

create view PersonOffsets as
select GetBegin(P.name) as offsetBegin, GetEnd(P.name) as offsetEnd
from Person P;

これらの両方の関数では、引数が null の場合、関数は null を戻します。

GetLanguage

GetLanguage 関数は 1 つのスパン引数を取り、そのスパンのソース・テキストの言語コード (2 文字) を戻します。 引数が null の場合、関数は null を戻します。

データ・ソースが適切な言語によるタグ付けテキスト・フィールドである場合にのみ、このステートメントは意味のある結果を生成します。

GetLemma

GetLemma 関数は、1 つの Span オブジェクトまたは Text オブジェクトを引数として取り、入力スパンの見出し語化された形式を含むストリングを戻します。 引数が null の場合、関数は null を戻します。 見出し語のマッチング用に辞書項目を使用した場合、この関数は、トークナイザーによって返されるさまざまなトークンの見出し語化された形式を判別できます。 例えば、スパン went shopping の場合、GetLemma は、見出し語ストリング go shop を返します。

この関数の結果は、次の規則に従います。

• 入力スパンがトークンの先頭で開始し、トークンの末尾で終了する場合、結果には、最初のトークンの見出し語で開始し、空白文字、2 番目のトークンの見出し語、空白文字のように続く一連の見出し語 (例: dog cat fish bird ...) が含まれます。 トークンの見出し語が空白文字で構成されている場合は、円記号 (¥¥) を使用して空白文字をエスケープします。
• 入力スパンが空白文字で開始または終了する場合 (例えば、2 つのトークン間で開始する場合や、2 つのトークン間で終了する場合)、関数は先頭と末尾の空白文字を無視します。
• 入力スパンがトークンの途中で開始または終了する場合、出力は、空白文字で区切られた以下の順序の以下の内容で構成されます。
  • 存在する場合は、最初の部分的なトークンの表層形。
  • 最初から最後までの完全なトークンに対応する一連の見出し語。 いずれかの完全なトークンの見出し語が空白文字で構成されている場合は、円記号 (¥¥) を使用して空白文字をエスケープします。
  • 存在する場合は、最後の部分的なトークンの表層形。

使用中のトークナイザーが見出し語を作成できない場合、この関数はエラーを返します。

GetLemma() 関数を使用して、見出し語化された形式の辞書を作成できます。 辞書に含める見出し語化された形式の用語を含む入力に対して GetLemma() を呼び出します。

GetLength

GetLength 関数は 1 つのスパン引数を取り、その入力スパンの長さを戻します。 引数が null の場合、関数は null を戻します。

例：

GetLength([5, 12])

これは値 7 を戻します。

GetLengthTok

GetLengthTok 関数は 1 つのスパン引数を取り、その入力スパンの長さをトークンで戻します。 入力引数が null の場合、関数は null を戻します。

GetString

GetString 関数は、1 つの AQL オブジェクトを引数として取り、そのオブジェクトのストリング表記から形成された Text オブジェクトを戻します。

スパン引数およびテキスト引数の場合、返される値は、GetText() によって返される値とは異なります。 Text オブジェクトの場合、戻り値には、テキスト・ストリングを囲む単一引用符が含まれます。 スパン・オブジェクトの場合、戻り値には、大括弧で囲まれたオフセットも含まれます。

スカラー・リストの場合、この関数は、リスト要素の GetString() 値をセミコロンで連結して戻します。 Integer、Float、Boolean、および String の各引数の場合、この関数は引数の値をストリングとして戻します。 null の引数の場合、この関数は null を戻します。

GetText

GetText 関数は、1 つのスパンまたはテキストを引数として取ります。 スパン入力の場合、そのスパンでマーク付けされる実際のテキスト・ストリングに基づいてテキスト・オブジェクトを戻します。 テキスト入力の場合、入力テキスト・オブジェクトを戻します。 入力が null の場合、この関数は null を戻します。 以下に例を示します。

GetText([5, 12])

スパンは、文字位置 5 から 12 までの、ドキュメントのサブストリングを戻します。

GetText 関数には、2 つの主な使用法があります。

2 つのスパンによりマーク付けされるテキスト間のストリング等価性を検査します。

-- Create a dictionary of company names
create dictionary CompanyNames as
('IBM', 'BigCorp', 'Initech');

-- Find all matches of the company names dictionary.
create view Company as
extract
    dictionary 'CompanyNames' on D.text as company
from Document D;


-- Create a table that maps company names to locations of
-- corporate headquarters.
create table NameToLocation (name Text, location Text) as
values
    ('IBM', 'USA'),
    ('BigCorp', 'Apex'),
    ('Initech', 'Dallas'),
    ('Acme Fake Company Names', 'Somewhere');

-- Use the table to augment the Company view with location
-- information.
create view CompanyLoc as
select N2C.location as loc, C.company as company
from Company C, NameToLocation N2C
where Equals(GetText(C.company), GetText(N2C.name));

output view CompanyLoc;

1 つのドキュメントを、より小さい複数のサブドキュメントに分割します。

例えばメイン・ドキュメントが複数のブログ項目から成る 1 つのブログである場合、GetText を使用して、ブログ項目ごとにサブドキュメントを作成できます。

detag Document.text as DetaggedBlog
annotate
    element 'blog' as Blog
    with attribute 'name' as title;


create view BlogEntry as
select B.match as entry, B.title as title
from Blog B;

-- Turn each tuple in the BlogEntry view into a sub-document
create view BlogEntryDoc as
select GetText(B.title) as title, GetText(B.entry) as body
from BlogEntry B;

output view BlogEntryDoc;

--Dictionary for Companies
create dictionary CompanyNameDict as
(
    'A Corporation', 'B Corporation'
);

-- Run an extraction over the sub-documents.
-- The spans that this "extract" statement creates will have
-- offsets relative to the blog entries themselves, as opposed
-- to the original multi-entry document.
create view CompanyName as
extract dictionary 'CompanyNameDict' on B.body as name
from BlogEntryDoc B;

output view CompanyName;

LeftContext および RightContext

LeftContext 関数はスパンおよび整数を入力として取ります。

LeftContext(<input span>, <nchars>)

LeftContext(<input span\>, <nchars\>)関数は、<input span\>のすぐ左側にある文書のnchars文字を含む新しいスパンを返します。 入力スパンが文書の先頭から<nchars\>文字未満で始まる場合、LeftContext()は文書の先頭から始まり、入力スパンの先頭まで続くスパンを返します。

例えば、LeftContext([20, 30], 10) は、スパン [10, 20] を戻します。 スパン LeftContext([5, 10], 10) は [0, 5] を戻します。

入力の始まりがドキュメントの先頭文字である場合、LeftContext() は長さ 0 のスパンを戻します。 同様に、RightContext 関数は入力スパンの右側のテキストを戻します。 両方の関数で、いずれかの引数が null の場合、関数は null を戻します。

LeftContextTok および RightContextTok

LeftContextTok および RightContextTok 関数は LeftContext および RightContext と似ていますが、トークンで距離を計測します。

LeftContextTok(<input span>, <num tokens>)
RightContextTok(<input span>, <num tokens>)

以下の例は RightContextTok 関数の使用法を例示しています。

create view Salutation as
extract
 regex /Mr\.|Ms\.|Miss/
  on D.text as salutation
  from Document D;

--Select the token immediately following a Salutation span
create view NameCandidate as
select RightContextTok(S.salutation, 1) as name
from Salutation S;

両方の関数で、いずれかの引数が null の場合、関数は null を戻します。

Remap

Remap 関数は次のように 1 つのスパン引数を取ります。

Remap(<span>)

別のテキスト・オブジェクトからの変換によって生成されたテキスト・オブジェクトを対象とする入力スパンの場合、Remap 関数は、そのスパンを元の「ソース」テキストに対するスパンに変換します。

例えば N.name というスパンが、AQL detag ステートメントを使って HTML を実行することにより生成されたタグ解除済みドキュメントを対象とする場合、

Remap(<N.name>)

は、元の HTML と同等のスパンを戻します。

スパン引数が、空のドキュメントに対して detag ステートメントを実行して生成された場合、関数は、スパンをドキュメントの先頭 (つまり、Document.text[0-0]) に再マップします。 また、detag ステートメントによって空ストリングが生成されると、関数は、スパンをドキュメントの先頭に再マップします。 AQL の各部分の中で、detag ステートメントだけが、このような派生テキスト・オブジェクトを生成します。

次の例では、Remap 関数の使用方法を示します。

-- Detag the HTML document and annotate the anchor tags
detag Document.text as DetagedDoc
    annotate
    element 'a' as Anchor;

-- Remap the Anchor Tags
create view AnchorTag as
select Remap(A.match) as anchor
from Anchor A;

Remap の引数が派生テキスト・オブジェクトでなく、派生テキスト・オブジェクトに対するスパンでもない場合、この関数はエラーを生成します。 引数が null の場合、関数は null を戻します。

SpanBetween

SpanBetween 関数は、2 つのスパンを入力として取り、スパンが同じテキスト・オブジェクトに基づいている場合は、2 つのスパン間のテキストを正確に包含するスパンを戻し、異なるテキスト・オブジェクトに基づいている場合は、null を戻します。

SpanBetween(['IgnoreOrder',] <span1>, <span2>)

オプションの IgnoreOrder パラメーターを使用する場合、AQL コンパイラーでは 2 つのスパンの順序は無視されます。

2つのスパンの間にテキストが存在しない場合、SpanBetweenは<span1>の終わりから始まる空のスパンを返します。

CombineSpansと同様に、 SpanBetweenは、IgnoreOrderパラメーターを使用しない限り、入力の順序に依存します。 したがって、

SpanBetween([5, 10], [50, 60])

はスパン [10, 50] を戻しますが、

SpanBetween([50, 60], [5, 10])

はスパン [60, 60] を戻します。

SpanBetween の引数が null の場合、関数は null を戻します。

SpanIntersection

SpanIntersection 関数は、2 つのスパンを入力として取り、スパンが同じテキスト・オブジェクトに基づいている場合は、どちらの入力にも含まれるテキストを包含するスパンを戻し、異なるテキスト・オブジェクトに基づいている場合は、null を戻します。

SpanIntersection(<span1>, <span2>)

例：

SpanIntersection([5, 20], [10, 60])

はスパン [10, 20] を戻しますが、

SpanIntersection([5, 20], [7, 10])

はスパン [7, 10] を戻します。

2 つのスパンがオーバーラップしない場合、SpanIntersection は null を戻します。 いずれかのスパン入力が null の場合、関数は null を戻します。

SubSpanTok

SubSpanTok 関数は 1 つのスパンと、そのスパンへのオフセットのペアを入力として取ります。

SubSpanTok(<span>, <first_tok>, <last_tok>)

関数の名前が示すように、<first_tok>引数と<last_tok>引数は、システムが使用するように構成されているトークナイザーに応じて、トークン内の距離です。

SubSpanTok 関数は、入力スパン内の、指定されたトークン範囲 (境界を含む) を包含する新しいスパンを戻します。 指定された範囲がスパンの内部で始まり、スパンの末尾を超過する場合には、含まれる部分的な範囲が戻されます。 <first_tok>がターゲット・スパンを超える距離を表す場合、SubSpanTokは入力スパンの先頭から始まる長さゼロのスパンを戻します。

いずれかの入力が null の場合、関数は null を戻します。

ToLowerCase

ToLowerCase 関数は 1 つのオブジェクトを引数として取り、そのオブジェクトの小文字ストリング表記を戻します。 ストリングへの変換方法は、GetString() 関数で変換が実行されるときと同じです。

この関数の主な使用法は、以下のように、大/小文字を区別しない等価結合を実行することです。

where Equals(ToLowerCase(C.company), ToLowerCase(N2C.name))

入力オブジェクトが null の場合、関数は null を戻します。

Java で実装された UDF のライフサイクル

以下の操作は、抽出プログラムのコンパイル (CompileAQL.compile() API)、インスタンス化 (OperatorGraph.createOG() API)、および検証 (OperatorGraph.validateOG() API) の際に、AQL の create function ステートメントごとに 1 回のみ実行されます。

1. 新規のクラス・ローダーを使用して、UDF メソッドを含む Java クラスをロードします。 クラスは、対応する create function ステートメントで指定された UDF JAR 内で検索されます。 このクラスのロード時に必要なその他のクラスも同じ UDF JAR 内で検索され、見つからないと、検索はランタイムをインスタンス化したクラス・ローダーに委任されます。
2. そのクラスのインスタンスを作成します。
3. 表 UDF の場合は、メソッド initState() を呼び出します。

create function ステートメントごとにこれらのステップが実行されるため、Java クラスに複数の UDF メソッドが含まれている場合 (およびすべてのメソッドが AQL の別の create function ステートメントで使用される場合)、クラスは複数回ロードされます。ロードごとに個別のクラス・ローダーが使用されます (ステップ 1)。 さらに、クラスの複数のインスタンスが作成され (ステップ 2)、メソッド initState() がインスタンスごとに 1 回呼び出されます (ステップ 3)。 異なる UDF で、同じクラス (またはライブラリー) の異なるバージョンを使用できるようにすることが、各 UDF に個別のクラス・ローダーが使用される理由です。

UDF クラスは、抽出プログラムのインスタンス化中にロードされているため、実行時 (OperatorGraph.execute() API) には再ロードされません。 UDF を実装する Java メソッドは、出力の一部を計算する必要がある場合に呼び出されます。 抽出プログラムが単一スレッド内で使用される場合は、各入力文書に対して、呼び出しが存在しない場合から、場合によっては多数の呼び出しが存在する場合までがあることを意味します (Operator Graph オブジェクトの存続期間全体では複数の呼び出しが存在する可能性が高いです)。 複数のスレッドで抽出プログラムが共有されると、異なるスレッドがほぼ同時に (異なる入力で) メソッドをヒットできます。

呼び出し全体で UDF メソッドに必要なデータ構造を初期化する場合など、UDF コードの特定の部分が 1 回のみ評価される必要がある場合、そのメソッドは抽出プログラム (OperatorGraph オブジェクトなど) の存続期間中に複数回実行される可能性が高いため、そのコードは、UDF 評価メソッドに配置することはできず、複数のスレッドで抽出プログラムを共有する場合に、ほとんど同時にヒットすることができます。　 または：

1. スカラー UDF の場合は、標準の Java プログラミングの原則に従います。 例えば、コードを静的ブロックに配置します。
2. 表 UDF の場合は、コードを initState() メソッドに配置するか、標準の Java プログラミングの原則に従います。 例えば、コードを静的ブロックに配置します。

これを行う場合は、上記のステップ 1 から 3 で説明されているように、抽出プログラムのコンパイル、インスタンス化、および検証中にクラスが複数回ロードされる可能性があることを覚えておいてください。 UDF を初期化するコードが静的ブロック内に配置される場合、そのコードはクラスがロードされるたびに (複数回ロードされる可能性があります) 実行されるため、コンパイルおよびオペレーターのグラフのインスタンス化の際にオーバーヘッドが発生します。 オーバーヘッドが大きい場合は、以下のベスト・プラクティスに従ってください。

• コンパイル時のオーバーヘッドを最小限にするには、大規模な辞書や初期化時間が長い UDF のようなコンパイル時の高負荷のリソースを個別の AQL モジュールに入れてエクスポートすることがベスト・プラクティスです。 変更された AQL モジュール、およびそれらのモジュールに依存する他のモジュールのみのコンパイルを試行してください。
• オペレーターのグラフのインスタンス化および検証の際のオーバーヘッドを最小限にするには、以下のようにします。
  1. 初期化コードが単一の UDF メソッドで必要な場合は、その UDF メソッドを個別の Java クラスに配置します (さらに、前述のように高負荷のインスタンス化コードを静的イニシャライザーに配置するか、コードが確実に 1 回実行される他の何らかのメカニズムを使用します)。
  2. 初期化コードが複数の UDF メソッドで共有される場合、ランタイムおよび AQL には、初期化コードが確実に 1 回のみ実行される明示的なメカニズムはありません。 このような状況で、初期化時間が非常に長い場合、唯一の解決策は、共有リソースと初期化コードをシステム・クラスパスに配置することです。 つまり、初期化コードを新しいクラス MySeparateClass.java に配置し、初期化の結果を MySeparateClass.myVar などのこのクラスの静的変数に保管します。 MySeparateClass.java を初期化時に必要なすべてのリソースとともに JAR ファイルにパッケージし、その JAR をシステム・クラスパスに配置します。 UDF メソッドは、MySeparateClass.myVar の静的変数を使用して、初期化されたモデルを参照できます。 これで、クラス MySeparateClass.java がシステムのクラス・ローダーでロードされるときに、初期化コードが 1 回のみ実行されます。

ヒント：

モジュールのコンパイル済み表記 (.tam ファイル) には、UDF の直列化されたバイナリー・コードが含まれています。 したがって、同じ UDF コードが 2 つの異なるモジュールの create function ステートメントによって参照される場合、UDF コードは両方のモジュールのコンパイル済み表記で直列化されます。 つまり、UDF コードは 2 回直列化されます。 このような場合は、UDF のライブラリーとして機能する個別のモジュールを作成して冗長性を回避し、他のモジュールでそのライブラリーを再利用することができます。 UDF のライブラリーを作成するには、次のステップに従います。

1. 1 つのモジュールを作成します。
2. そのモジュール内にすべての UDF JAR ファイルを配置します。
3. create function ステートメントを使用して、必要なすべての関数を定義します。
4. それらをすべて export function ステートメントでエクスポートして、他のモジュールでインポートして使用することができます。

例

例 1: スカラー UDF の実装

この例は、toUpperCase という名前のスカラー UDF の実装を示しています。 この UDF は、Span 型の値を入力として取り、大文字に変換された入力スパンのテキスト・コンテンツから構成されるストリング値を出力します。

package com.ibm.biginsights.textanalytics.udf;
import com.ibm.avatar.algebra.datamodel.Span;

/**
  * @param s input Span
  * @return all upper-case version of the text of the input Span
  */
public String toUpperCase(Span s) {
  return s.getText().toUpperCase();
}

例 2: 表を入力として使用するスカラー UDF の実装

この例は、TableConsumingScalarFunc という名前のスカラー UDF の実装を示しています。 この UDF は、タプルの 2 つのリストを入力として取り、2 つの入力タプルのリストの内容を連結したストリング値を出力します。

import com.ibm.avatar.algebra.datamodel.TupleList;

/**
  * Example implementation of a user-defined scalar function using a table as input
*/
public class TableConsumingScalarFunc
{

  /**
    * Main entry point to the `scalar` function. This function takes two lists of tuples and concatenates them into a single string.
    *
    * @param arg1 first set of tuples to merge
    * @param arg2 second set of tuples to merge
    * @return the two sets of tuples, concatenated
    */
  public String eval (TupleList arg1, TupleList arg2)
  {
    StringBuilder sb = new StringBuilder ();

    sb.append("Input1: ");
    sb.append(arg1.toPrettyString ());
    sb.append("\nInput2: ");
    sb.append(arg2.toPrettyString ());

    return sb.toString ();
  }
}

例 3: 表を入力として使用する表 UDF の実装

この例は、TableConsumingTableFunc という名前の表 UDF の実装を示しています。 この UDF は、タプルの 2 つのリストを入力として取り、2 つ目の入力からのタプルが組み入れられた、最初の入力からのタプルを含むタプルの単一のリストを出力します。 実装が基本クラス com.ibm.avatar.api.udf.TableUDFBase から拡張されて、入出力のスキーマを取得するための API を提供することに注意してください。

package com.ibm.test.udfs;

import java.lang.reflect.Method;

import com.ibm.avatar.algebra.datamodel.AbstractTupleSchema;
import com.ibm.avatar.algebra.datamodel.FieldCopier;
import com.ibm.avatar.algebra.datamodel.Tuple;
import com.ibm.avatar.algebra.datamodel.TupleList;
import com.ibm.avatar.algebra.datamodel.TupleSchema;
import com.ibm.avatar.api.exceptions.TableUDFException;
import com.ibm.avatar.api.udf.TableUDFBase;

/**
  * Example implementation of a user-defined table function
*/
public class TableConsumingTableFunc extends TableUDFBase
{

  /** Accessors for copying fields from input tuples to output tuples. */
  private FieldCopier arg1Copier, arg2Copier;

  /**
    * Main entry point to the `table` function. This function takes two lists of tuples and generates a new list of wide
    * tuples, where element i of the returned list is created by joining element i of the first input with element i of
    * the second input.
    *
    * @param arg1 first set of tuples to merge
    * @param arg2 second set of tuples to merge
    * @return the two sets of tuples, interleaved
    */
  public TupleList eval (TupleList arg1, TupleList arg2)
  {

    TupleSchema retSchema = getReturnTupleSchema ();
    TupleList ret = new TupleList (retSchema);

    // We skip any records that go off the end
    int numRecs = Math.min (arg1.size (), arg2.size ());

    for (int i = 0; i < numRecs; i++) {
      Tuple retTuple = retSchema.createTup ();

      Tuple inTup1 = arg1.getElemAtIndex (i);
      Tuple inTup2 = arg2.getElemAtIndex (i);

      arg1Copier.copyVals (inTup1, retTuple);
      arg2Copier.copyVals (inTup2, retTuple);

      // System.err.printf ("%s + %s = %s\n", inTup1, inTup2, retTuple);

      ret.add (retTuple);
    }

    return ret;
  }

  /**
    * Initialize the internal state of the `table` function. In this case, we create accessors to copy fields from input
    * tuples to output tuples.
    *
    * @see com.ibm.avatar.api.udf.TableUDFBase#initState() for detailed description
    */
  @Override
  public void initState () throws TableUDFException
  {
    // Create accessors to do the work of copying fields from input tuples to output tuples
    AbstractTupleSchema arg1Schema = getRuntimeArgSchema ().getFieldTypeByIx (0).getRecordSchema ();
    AbstractTupleSchema arg2Schema = getRuntimeArgSchema ().getFieldTypeByIx (1).getRecordSchema ();
    TupleSchema retSchema = getReturnTupleSchema ();

    // Create offsets tables for a straightforward copy.
    String[] srcs1 = new String[arg1Schema.size ()];
    String[] dests1 = new String[arg1Schema.size ()];
    String[] srcs2 = new String[arg2Schema.size ()];
    String[] dests2 = new String[arg2Schema.size ()];

    for (int i = 0; i < srcs1.length; i++) {
      srcs1[i] = arg1Schema.getFieldNameByIx (i);
      dests1[i] = retSchema.getFieldNameByIx (i);
    }
    for (int i = 0; i < srcs2.length; i++) {
      srcs2[i] = arg2Schema.getFieldNameByIx (i);
      dests2[i] = retSchema.getFieldNameByIx (i + srcs1.length);
    }

    arg1Copier = retSchema.fieldCopier (arg1Schema, srcs1, dests1);
    arg2Copier = retSchema.fieldCopier (arg2Schema, srcs2, dests2);
  }

  /**
    * Check the validity of tuple schemas given in the AQL “create function”.
    *
    * @see com.ibm.avatar.api.udf.TableUDFBase#validateSchema(TupleSchema, TupleSchema, TupleSchema, Method, Boolean) for
    *      description of arguments
    */
  @Override
  public void validateSchema (TupleSchema declaredInputSchema, TupleSchema runtimeInputSchema,
    TupleSchema returnSchema, Method methodInfo, boolean compileTime) throws TableUDFException
  {
    // The output schema should contain the columns of the two input schemas in order.
    AbstractTupleSchema arg1Schema = declaredInputSchema.getFieldTypeByIx (0).getRecordSchema ();
    AbstractTupleSchema arg2Schema = declaredInputSchema.getFieldTypeByIx (1).getRecordSchema ();

    System.err.printf ("TableConsumingTableFunc: Input schemas are %s and %s\n", arg1Schema, arg2Schema);

    // First check sizes
    if (returnSchema.size () != arg1Schema.size () + arg2Schema.size ()) { throw new TableUDFException (
      "Schema sizes don't match (%d + %d != %d)", arg1Schema.size (), arg2Schema.size (), returnSchema.size ()); }

    // Then check types
    for (int i = 0; i < arg1Schema.size (); i++) {
      if (false == (arg1Schema.getFieldTypeByIx (i).equals (returnSchema.getFieldTypeByIx (i)))) { throw new TableUDFException (
        "Field type %d of output doesn't match corresponding field of first input arg (%s != %s)", i,
        returnSchema.getFieldTypeByIx (i), arg1Schema.getFieldTypeByIx (i)); }
    }

    for (int i = 0; i < arg2Schema.size (); i++) {
      if (false == (arg2Schema.getFieldTypeByIx (i).equals (returnSchema.getFieldTypeByIx (i + arg1Schema.size ())))) { throw new TableUDFException (
        "Field type %d of output doesn't match corresponding field of first input arg (%s != %s)", i
          + arg1Schema.size (), returnSchema.getFieldTypeByIx (i + arg1Schema.size ()), arg2Schema.getFieldTypeByIx (i)); }
    }
  }

}

構文

create function ステートメントの一般的な構文は、次のとおりです。

create function <function-name>(<input-schema-definition>)
return <return-type> [like <column-name>] | table ( <output-schema-definition)
external_name <ext-name>
language [java | pmml]
[deterministic | not deterministic]
[return null on null input | called on null input];

<input-schema-definition>
<column-name> <data-type> | table (<output-schema-definition>) as locator [,<column-name> <data-type> | table (<output-schema-definition>) as locator ]*

<output-schema-definition>
<column-name> <data-type> [,<column-name> <data-type>]*

説明

• <function-name\>

  <function-name\>は、UDFのAQL名を宣言します。 UDF は、この名前を使用して AQL コードで参照されます。

• <input-schema-definition\>

  UDF の入力パラメーターを指定します。 入力パラメーターには、<column-name\>として指定される名前があり、スカラー型または表ロケーターのいずれかにすることができます。 言語が PMML の場合は、この関数は、引数として params という単一の表を取る必要があります。

• <column-name\>

  UDF の入力または出力の列の名前を指定します。

• <data-type\>

  UDF への入力スカラー・パラメーターのタイプ、UDF への入力表のスキーマ内の列のタイプ、または UDF の出力表のスキーマ内の列のタイプ。 <data-type\>に指定できる値は、Integer、Float、String、Text、Span、Boolean、または ScalarList です。

• table (<output-schema-definition\>) as locator

  この入力タイプにより、関数は、現在の文書で計算された特定の AQL ビューの全体のコンテンツを入力として取ることができます。 ロケーター・パラメーターは、ビューまたは表を引数として参照します。

• <return-type\>

  スカラーUDFの場合、<return-type\>は、UDFによって戻されるスカラー値のタイプを指定します。 戻りの型に指定できる値は、Integer、Float、String、Text、Span、Boolean、または ScalarList です。 戻りの型が Integer である場合、UDF を実装する Java™ 関数は Integer 型のオブジェクトを返します。 UDF 実装は、プリミティブ int 型を返すことはできません。 戻りの型が Text または Span である場合、戻りの型の派生元の入力パラメーターを指定します。 スパンは常に、基礎となる列から派生するため、オプションの like 指定を使用して、入力パラメーターを指定できます。 戻りの型が ScalarList である場合、ScalarList 内のスカラー型の推測元の入力パラメーターを指定します。 言語が PMML の場合、関数は表を戻す必要があります。

• <output-schema-definition\>

  表UDFの場合、<output-schema-definition\>は、列名とそのタイプを含む、UDFによって返される表の出力スキーマを指定します。

• <ext-name\>

  external_name は、UDF の実装を検索する場所を指定します。　 言語が Java の場合、これは'<jar-file-name\>:<fully-qualified-class-name\>!<method-name\>'という形式のストリングで、以下の 3 つの部分から構成されます。

  • JAR ファイル名: モジュラー AQL をコンパイルする場合、UDF JAR ファイルのロケーション参照は、参照が作成されるモジュールのルートを基準にする必要があります。
  • クラス名: UDF 実装を含む完全修飾クラス名。
  • メソッド名: メソッドはクラスの public メソッドであることが必要です。 メソッド・シグニチャーは、create function ステートメントに指定されたパラメーター・タイプと一致している必要があります。 自動型変換がランタイム・コンポーネントによって行われることはありません。 言語が PMML の場合、external_name 節は、モジュールのルート・ディレクトリーを基準とする相対位置の PMML ファイルの場所となるストリングを指定します。 現在の実装は、PMML 標準バージョン 4.1 を使用して表現されたモデルをサポートし、バージョン 1.0.22 org.jpmml ライブラリーを使用してそれらを評価します。

• language

  language の指定は、UDF の実装の言語を指します。 ランタイム・コンポーネントは、Java™ で実装される UDF のみをサポートします。

• deterministic/not deterministic

  オプションの deterministic/not deterministic は、この関数がステートレスかどうかを指定します。 deterministic 関数は、同じ入力値のセットに対して常に同じ値を返します。

• return null on null input

  オプションの return null on null input は、1 つ以上の入力値が NULL だった場合の関数の動作を指定します。 return null on null input が指定されると、NULL 入力の場合にシステムは UDF を呼び出さずに null を返します。 called on null input が指定されると、入力値が NULL の場合でも UDF は呼び出されます。

PMML で実装される UDF の使用上の注意

PMML ファイルから作成された関数は、引数として params という単一の表を取り、表を出力します。 関数の実装により、create function ステートメントで宣言された入出力スキーマと PMML ファイルで指定された入出力スキーマの入力フィールドがマップされます。 つまり、モデルが生成および消費する入力レコードおよび出力レコードに表示可能なフィールドの名前とタイプを記述する DataDictionary セクション、DataDictionary セクションで定義された名前付きファイルが、フィーチャー・ベクトルを表す各タプルに含まれるよう指示する MiningSchema セクション、DataDictionary セクションで定義された名前付きフィールドが、モデルの出力の外部表現の各タプルに含まれるよう指示する Output セクションです。 これらの関数は、表関数でなければなりません。表の各行は PMML モデルに渡され、出力行を生成します。

PMML タイプ・システムと AQL タイプ・システムは完全に一致しないため、このスキーマ情報が必要です。 例えば、PMML にはタイム・スタンプを表すためのタイプがいくつかありますが、AQL では現在、ユーザーがタイム・スタンプをストリング値としてエンコードする必要があります。 また、スキーマ情報により、AQL を知っているが PMML を知らない開発者が AQL 規則セットを理解できるようになります。

AQL コンパイラーは、2 つのスキーマに互換性があることを確認するために、PMML ファイルの入力スキーマに対して入力スキーマを検査します。 2 つのスキーマに同じ名前のフィールドが含まれているが、互換性のないタイプである場合は、コンパイルは失敗し、該当するエラー・メッセージが表示されます。 関数の入力スキーマまたは出力スキーマに余分な列または欠落した列がある場合、resulting 関数はこれらの列を無視し、エラーを生成しません。 列名の順序は、AQL 定義と PMML ファイルの間で異なっていてもかまいません。 列名が入力スキーマと出力スキーマの両方に表示されるが、PMML スキーマには表示されない場合は、その列の値は関数の出力に渡されます。

例

例 1: Java を使用した、スカラー値を入力として取るスカラー UDF の宣言

以下の例は、create function という名前の関数を宣言する udfCombineSpans ステートメントを示します。 このユーザー定義関数は、入力として 2 つのスパンを受け取り、1 番目の入力スパンと似たマージされたスパンを返します。 実際の UDF Java™ 関数は、udfs.jar ディレクトリーにある udfjars という名前の JAR ファイルにパッケージされています。 この関数を実装するメソッドは、クラス combineSpans の com.ibm.test.udfs.MiscScalarFunc です。 このメソッドには、スパンが指定サイズより大きい場合に udfSpanGreaterThan を返す関数 true も宣言されています。

/**
* A function to combine two spans and return the resultant span from beginOffset of first span, to endOffset of second span
* @param p1 first input span
* @param p2 second input span
* @return a span from beginOffset of p1 till endOffset of p2
*/

create function udfCombineSpans(p1 Span, p2 Span)
return Span like p1
external_name 'udfjars/udfs.jar:com.ibm.test.udfs.MiscScalarFunc!combineSpans'
language java
deterministic
return null on null input;

/**
* A function to compare an input Span's size against an input size
* @param span input span
* @param size input size to be compared against
* @return Boolean true if input span's size is greater than input argument size, else false
*/

create function udfSpanGreaterThan(span Span, size Integer)
return Boolean
external_name 'udfjars/udfs.jar:com.ibm.test.udfs.MiscScalarFunc!spanGreaterThan'
language java
deterministic;

次の例は、udfCompareNames という名前の関数を宣言する方法を示します。この関数は、名前のリスト nameList と単一の名前 myName を受け取ります。 出力は入力リストと似たリストです。この中には myName に似た nameList のエントリーのみが格納されます。

/**
* A function to compare an input string against a list of names
* and returns a list of entries from nameList similar to myName.
* @param nameList a list of names
* @param myName a name to compare against the list
* @return a list of entries from nameList similar to myName
*/

create function udfCompareNames(nameList ScalarList, myName String)
return ScalarList like nameList
external_name 'udfjars/udfs.jar:com.ibm.test.udfs.MiscScalarFunc!compareNames'
language java
deterministic;

例 2: Java を使用した、表を入力として取るスカラー UDF の宣言

次の例では、table as locator 入力タイプの使用方法を示します。 これは、MyScalarFunc という関数を宣言する create function ステートメントを示しています。 UDF の Java™ 実装は、クラス com.ibm.test.udfs.TableConsumingScalarFunc 内にパッケージされます。

この UDF は、タプルの 2 つのリストを入力として取り、2 つの入力タプルのリストの内容を連結したストリング値を出力します。 UDF の Java™ 実装は、『ユーザー定義関数の実装』に含まれています。

-- Declare a simple scalar function that turns two tables into a big string
create function MyScalarFunc(
    firstArg table( spanVal Span ) as locator,
    secondArg table( spanVal Span, strVal Text ) as locator
)
return String
external_name
  'udfjars/udfs.jar:com.ibm.test.udfs.TableConsumingScalarFunc!eval'
language java
deterministic
called on null input;

例 3: Java を使用した表 UDF の宣言

次の例では、return table 節の使用方法を示します。 この例は、MyScalarFunc という表関数を宣言する create function ステートメントを示しています。 UDF の Java™ 実装は、クラス com.ibm.test.udfs.TableConsumingTableFunc 内にパッケージされます。 この UDF は、タプルの 2 つのリストを入力として取り、入力リストをマージしたタプルのリストを出力します。 UDF の Java™ 実装は、『ユーザー定義関数の実装』に含まれています。

-- Declare a simple table function that "zips together" two input tables
create function MyTableFunc(
    firstArg table( spanVal Span ) as locator,
    secondArg table( spanVal Span, strVal Text ) as locator
)
return table( outSpan1 Span, outSpan2 Span, outStr Text)
external_name
  'udfjars/udfs.jar:com.ibm.test.udfs.TableConsumingTableFunc!eval'
language java
deterministic
called on null input;

例 4: PMML で実装される表 UDF の宣言

以下の例は、PMML 言語を使用して IrisDecisionTree という名前の表関数を宣言する create function ステートメントを示します。 UDF の PMML 実装は IrisTree.xml ファイルに指定されています。その内容を以下の例に示します。 IrisTree.xml に保管されているモデルは、デシジョン・ツリー・モデルです。

-- Scoring function based on a decision tree model stored in IrisTree.xml
create function IrisDecisionTree(
    params table(
        sepal_length Float,
        sepal_width Float,
        petal_length Float,
        petal_width Float
    ) as locator
)
return table( class Text, actual_class Text,
    -- This PMML file also defines additional output fields
    "Probability_Iris-setosa" Float,
    "Probability_Iris-versicolor" Float,
    "Probability_Iris-virginica" Float)
external_name 'IrisTree.xml'
language pmml;

IrisTree.xml

<?xml version="1.0"?>
<PMML version="3.2" xmlns="http://www.dmg.org/PMML-3_2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.dmg.org/PMML-3_2 http://www.dmg.org/v3-2/pmml-3-2.xsd">
  <Header copyright="Copyright (c) 2012 DMG" description="RPart Decision Tree Model">
  <Extension name="user" value="DMG" extender="Rattle/PMML"/>
  <Application name="Rattle/PMML" version="1.2.29"/>
  <Timestamp>2012-09-27 12:46:08</Timestamp>
  </Header>
  <DataDictionary numberOfFields="5">
  <DataField name="class" optype="categorical" dataType="string">
    <Value value="Iris-setosa"/>
    <Value value="Iris-versicolor"/>
    <Value value="Iris-virginica"/>
  </DataField>
  <DataField name="sepal_length" optype="continuous" dataType="double">
    <Interval closure="closedClosed" leftMargin="4.3" rightMargin="7.9"/>
  </DataField>
  <DataField name="sepal_width" optype="continuous" dataType="double">
    <Interval closure="closedClosed" leftMargin="2" rightMargin="4.4"/>
  </DataField>
  <DataField name="petal_length" optype="continuous" dataType="double">
    <Interval closure="closedClosed" leftMargin="1" rightMargin="6.91"/>
  </DataField>
  <DataField name="petal_width" optype="continuous" dataType="double">
    <Interval closure="closedClosed" leftMargin="0.1" rightMargin="2.5"/>
  </DataField>
  </DataDictionary>
  <TreeModel modelName="RPart_Model" functionName="classification" algorithmName="rpart" splitCharacteristic="binarySplit" missingValueStrategy="defaultChild">
  <MiningSchema>
    <MiningField name="class" usageType="predicted"/>
    <MiningField name="sepal_length" usageType="supplementary"/>
    <MiningField name="sepal_width" usageType="supplementary"/>
    <MiningField name="petal_length" usageType="active"/>
    <MiningField name="petal_width" usageType="supplementary"/>
  </MiningSchema>
  <Output>
    <OutputField name="class" optype="categorical" dataType="string" feature="predictedValue"/>
    <OutputField name="Probability_Iris-setosa" optype="continuous" dataType="double" feature="probability" value="Iris-setosa"/>
    <OutputField name="Probability_Iris-versicolor" optype="continuous" dataType="double" feature="probability" value="Iris-versicolor"/>
    <OutputField name="Probability_Iris-virginica" optype="continuous" dataType="double" feature="probability" value="Iris-virginica"/>
  </Output>
  <Node id="1" score="Iris-virginica" recordCount="105" defaultChild="3">
    <True/>
    <ScoreDistribution value="Iris-setosa" recordCount="33" confidence="0.314285714285714"/>
    <ScoreDistribution value="Iris-versicolor" recordCount="35" confidence="0.333333333333333"/>
    <ScoreDistribution value="Iris-virginica" recordCount="37" confidence="0.352380952380952"/>
    <Node id="2" score="Iris-setosa" recordCount="33">
    <SimplePredicate field="petal_length" operator="lessThan" value="2.6"/>
    <ScoreDistribution value="Iris-setosa" recordCount="33" confidence="1"/>
    <ScoreDistribution value="Iris-versicolor" recordCount="0" confidence="0"/>
    <ScoreDistribution value="Iris-virginica" recordCount="0" confidence="0"/>
    </Node>
    <Node id="3" score="Iris-virginica" recordCount="72" defaultChild="7">
    <SimplePredicate field="petal_length" operator="greaterOrEqual" value="2.6"/>
    <ScoreDistribution value="Iris-setosa" recordCount="0" confidence="0"/>
    <ScoreDistribution value="Iris-versicolor" recordCount="35" confidence="0.486111111111111"/>
    <ScoreDistribution value="Iris-virginica" recordCount="37" confidence="0.513888888888889"/>
    <Node id="6" score="Iris-versicolor" recordCount="37">
      <SimplePredicate field="petal_length" operator="lessThan" value="4.85"/>
      <ScoreDistribution value="Iris-setosa" recordCount="0" confidence="0"/>
      <ScoreDistribution value="Iris-versicolor" recordCount="34" confidence="0.918918918918919"/>
      <ScoreDistribution value="Iris-virginica" recordCount="3" confidence="0.0810810810810811"/>
    </Node>
    <Node id="7" score="Iris-virginica" recordCount="35">
      <SimplePredicate field="petal_length" operator="greaterOrEqual" value="4.85"/>
      <ScoreDistribution value="Iris-setosa" recordCount="0" confidence="0"/>
      <ScoreDistribution value="Iris-versicolor" recordCount="1" confidence="0.0285714285714286"/>
      <ScoreDistribution value="Iris-virginica" recordCount="34" confidence="0.971428571428571"/>
    </Node>
    </Node>
  </Node>
  </TreeModel>
</PMML>

コメントによる create function ステートメントの文書化

create function ステートメントの AQL 文書コメントには、次の情報が含まれます。

• 関数に関する一般的な説明。
• 関数で使用される各パラメーター名を指定する @param の説明。 スカラー型か表かの、パラメーターのタイプを示します。 パラメーターが表の場合は、入力として予期される表のスキーマに表示される順序で列の名前と型が含まれる、表のスキーマを説明します。
• 関数で戻される情報を指定する @return の説明。 関数が表を戻す場合は、出力表のスキーマに表示される順序で列の名前と型が含まれる、表の出力スキーマを指定します。

/**
* A function to compare an input string against a list of names
* and returns a list of entries from nameList similar to myName.
* @param nameList a list of names
* @param myName a name to compare against the list
* @return a list of entries from nameList similar to myName
*/

create function udfCompareNames(nameList ScalarList, myName String)
  return ScalarList like nameList
  external_name 'udfjars/udfs.jar:com.ibm.test.udfs.MiscScalarFunc!compareNames'
  language java
  deterministic;

例

例 1: スカラー値を入力として取る、Java で実装されたスカラー UDF の使用

この例では、『udfCombineSpansユーザー定義関数の宣言udfSpanGreaterThan』で宣言された 関数および 関数の使用方法を示します。

create function udfCombineSpans(p1 Span, p2 Span)
return Span like p1
external_name 'udfjars/udfs.jar:com.ibm.test.udfs.MiscScalarFunc!combineSpans'
language java
deterministic
return null on null input;

create function udfSpanGreaterThan(span Span, size Integer)
return Boolean
external_name 'udfjars/udfs.jar:com.ibm.test.udfs.MiscScalarFunc!spanGreaterThan'
language java
deterministic;

-- identify occurrences of given names in the document
create dictionary FirstNamesDict from file 'firstNames.dict';

create view FirstName as
extract dictionary 'FirstNamesDict' on D.text as name
from Document D;

-- Use a UDF to merge the name that is longer than 7 characters with the text to its right in a
-- way that is appropriate to the application.
create view NameAndContext as
select udfCombineSpans(F.name, RightContext(F.name, 50)) as name
from FirstName F
where udfSpanGreaterThan(F.name, 7);

例 2: 表を入力として取る、Java で実装されたスカラー UDF の使用

以下の例は、表を入力として使用するスカラー関数の使用方法を示しています。 この例は、MyScalarFunc 表 UDF 関数の使用方法を示しています。この Java™ 実装は『ユーザー定義関数の実装』に含まれています。 これらの列の型は同じですが、列の名前が異なります。

-- Declare a simple scalar function that turns two tables into a big string
create function MyScalarFunc(
    firstArg table( spanVal Span ) as locator,
    secondArg table( spanVal Span, strVal Text ) as locator
)
return String
external_name
  'udfjars/udfs.jar:com.ibm.test.udfs.TableConsumingScalarFunc!eval'
language java
deterministic
called on null input;

-- Create two views to serve as inputs to the `table` function.
-- Note that column names don't match, but types do.
create view FirstInputView as
extract regex /\d+/ on 1 token in D.text as match
from Document D;

create view SecondInputView as
select S.match as spanCol, 'Dummy string' as textCol
from
    (extract regex /[A-Z][a-z]+/ on 1 token in D.text as match
    from Document D) S;

-- Call the `scalar` function defined above from the select list.
create view ScalarFuncOutput as
select MyScalarFunc(FirstInputView, SecondInputView) as func
from Document D;

例 3: Java で実装された表 UDF の使用

この例は、MyTableFunc 表 UDF 関数の使用方法を示しています。この Java™ 実装は『ユーザー定義関数の実装』に含まれています。

-- Declare a simple table function that "zips together" two input tables
create function MyTableFunc(
    firstArg table( spanVal Span ) as locator,
    secondArg table( spanVal Span, strVal Text ) as locator
)
return table( outSpan1 Span, outSpan2 Span, outStr Text)
external_name
  'udfjars/udfs.jar:com.ibm.test.udfs.TableConsumingTableFunc!eval'
language java
deterministic
called on null input;

-- Create two views to serve as inputs to the `table` function.
-- Note that column names don't match, but types do.
create view FirstInputView as
extract regex /\d+/ on 1 token in D.text as match
from Document D;


create view SecondInputView as
select S.match as spanCol, 'Dummy string' as textCol
from
    (extract regex /[A-Z][a-z]+/ on 1 token in D.text as match
    from Document D) S;

-- Use the `table` function
create view TabFuncOutput as
select T.outSpan1 as span1, T.outSpan2 as span2
from MyTableFunc(FirstInputView, SecondInputView) T;

例 2 のように、この例では、スキーマ FirstInputView を持つ (match Span) とスキーマ SecondInputView を持つ (spanCol Span, textCol Text) の 2 つのビューを定義しています。 この例の最後のビューである TabFuncOutput は、2 つの入力ビューを使用して、table 節の from 関数 MyTableFunc を呼び出します。 例 2 で説明されているように、入力ビューと表ロケーターのスキーマの列の数と列の型が一致する限り、ビューは関数の表ロケーター引数と互換性があります。 ただし、列名が一致している必要はありません。

最後に、select 節によって、最初の 2 つの列の outStr と outSpan1 のみが保持され、MyTableFunc の出力表から列 outSpan2 が破棄されます。

例 4: PMML で実装される表 UDF の使用

この例では、『ユーザー定義関数の宣言』の例 4 で宣言された IrisDecisionTree 表 UDF 関数の使用方法を示しています。

-- External view to hold the input records
create external view IrisData(
    sepal_length Float,
    sepal_width Float,
    petal_length Float,
    petal_width Float
)
external_name 'IrisData';
--Invoke the function on the input data records
create view IrisDecisionTreeOutput as
select * from IrisDecisionTree(IrisData);

output view IrisDecisionTreeOutput;