Rosette Name Indexer for Elasticsearch

RNI Elasticsearch Plugin - Version 5.3.2.0.

Copyright © 2000-2018 Basis Technology Corporation. All rights reserved. This document is property of and is proprietary to Basis Technology Corporation. It is not to be disclosed or reproduced in whole or in part without the express written consent of Basis Technology Corporation.

The software product described in this document is copyright © 2000-2018 Basis Technology Corporation.

Lexical data used in this product are, unless otherwise stated, copyright © 2000-2018 Basis Technology Corporation.

Basis Technology is a registered trademark of Basis Technology Corporation. All other brand names may be trademarks of their respective owners.

U.S. Government Rights. This software is commercial computer software owned by Basis Technology Corporation. In accordance with DFARS 48 CFR 227-7202-1 and FAR 48 CFR 227.405-3(a), its use, reproduction, and disclosure by the Government is subject to the terms of Basis Technology's standard software license agreement and as may be set forth in the applicable Government Contract. Copyright © 2000-2018 Basis Technology Corporation. All rights reserved. Licensor/Contractor: Basis Technology Corporation, One Alewife Center, Cambridge, MA 02140, USA.

May 2017

1. はじめに

RNI-Elasticsearch は Elasticsearch1 プラグインであり、人名、地名、組織名のファジー検索・照合アプリケーションを作成するためのものです。このプラグインは、Rosette 名称照合モジュール（RNI） 7.17.1 でビルドされており、Elasticsearch 5.3.2.で動作します。

サポートされている言語と、言語の指定に使用する ISO 639-3 コードは、以下のとおりです。

英語（eng）、フランス語（fra）、ドイツ語（deu）、イタリア語（ita）、ポルトガル語（por）、スペイン語（spa）、朝鮮語（kor）、中国語（zho）、日本語（jpn）、ロシア語（rus）、アラビア語（ara）、西ファルシ語（pes）、ダリ語（prs）、パシュトー語（pus）、ウルドゥ語（urd）。2

2. 準備

RNI-Elasticsearch を使用するには、RNI Elasticsearch プラグイン 5.3.2.0.、RLP ライセンス、および Elasticsearch 5.3.2. が必要です。3

1.Elasticsearch がまだインストールされていない場合はインストールします。

Elasticsearch-5.3.2..zip をダウンロードして解凍します。 RNI Elasticsearch をインストールする際には、正しいバージョンの Elasticsearch (5.3.2.) であることを確認してください。Elasticsearch のバージョンが完全に一致していないと、プラグインはインストールされません。

2.RNI-Elasticsearch プラグインをインストールします。

elasticsearch-5.3.2. ルートディレクトリーに移動して、以下を実行します

bin/elasticsearch-plugin install file:///path/to/rni-es- Elasticsearch5.3.2..zip

プラグインの zip の参照には、ファイルの絶対パスを使用してください。

プラグインが動作するために必要な許可を求められる場合があります。

これで、RNI-Elasticsearch プラグインが plugins/rni にインストールされました。

3.RLP ライセンス（rlp-license.xml）を plugins/rni/bt_root/rlp/rlp/licenses にコピーします。

RNI-Elasticsearch を使用する前に、必ず、このライセンスをここに置いてください。

以下を実行して Elasticsearch サーバーを起動します。

bin/elasticsearch

3. 使用手順

  1. インデックスを作成します。

  2. 人名、地名、組織名を入れるフィールドのマッピングを定義します。これらのフィールドのタイプは "rni_name" です。

  3. 1 つ以上の名称フィールドを含むドキュメントをインデックスします。ドキュメントの各名称フィールドには名称が入ります。

  4. マッピングをテストします。

  5. クエリーを実行してインデックスを検索します。

以下の記述では、RNI-Elasticsearch プラグインを実行するための Elasticsearch API の説明に、cURL コマンドラインツールでの使用例を示します。

3.1. インデックスの作成

以下の cURL ステートメントで、rni-test という名前のインデックスを作成します。

curl -XPUT 'http://localhost:9200/rni-test'

3.2. マッピングの定義

作成するドキュメントのドキュメントタイプを指定し、名称フィールドの "type" を "rni_name" に設定します。

以下のステートメントでは、"record"ドキュメントの "primary_name" フィールドおよび "aka"（別名）フィールドを "rni-test"インデックスの "rni_name"タイプにマップしています。

curl -XPUT 'http://localhost:9200/rni-test/record/_mapping' -d '{
    "record" :{
        "properties" :{
            "primary_name" :{ "type" :"rni_name" },
            "aka" :{ "type" :"rni_name" },
            "occupation" :{ "type" :"string" }
        }
    }
}'

3.3. ドキュメントのインデックス

名称フィールド以外のドキュメントフィールドも使用できます。

curl -XPUT 'http://localhost:9200/rni-test/record/1' -d '{
  "primary_name" :"Joe Schmoe",
  "aka" :"Bossman",
  "occupation" :"business owner" 
}'

名称フィールドには、名称の文字列だけでなく、以下のようなプロパティーを含めることができます。"entityType" は特に役立ちます。

プロパティー 必須 説明
"data" ✓　 名称の文字列。
"language" 使用言語（名称が見つかったドキュメントの言語）の ISO 639-3 コード。
"languageOfOrigin" 名称の起源の言語の ISO 639-3 コード。例: 英語（eng）ドキュメント内のスペイン語（spa）起源の名称など。
"script" ISO 15924 文字体系コード。本リリースでサポートされる全言語の文字体系は "Latn" のみです。
"entityType" "PERSON"、"LOCATION"、または "ORGANIZATION"。
"uid" ドキュメントのユニークな文字列の ID。

例:

curl 'http://localhost:9200/rni-test/record/3' -d '{ 
    "primary_name" :{ 
    "data" :"Joe Schmoe", 
    "language" :"eng", 
    "script" :"Latn", 
    "entityType" :"PERSON" 
    } 
}'

3.4. RNI インテグレーションのテスト

ドキュメントをインデックスしたら、各フィールドが正しくマップされていること、および RNI が実行されていることをテストします。

1.ドキュメントをインデックスに追加します。

2.以下のように、Elasticsearch からテストクエリーを送信します。

curl -XGET localhost:9200/rni-test/rni_plugin/_verify_installation
?rni-name-field=primary_name

rni-name-field の値は、タイプが rni_name のフィールド名です（例えば、primary_name ）。

3.curl の応答を確認します。

  • マッピングと RNI が成功したという応答が返れば、インテグレーションは正常に完了しています。
  • マッピングが失敗したという応答が返された場合には、正しいフィールド（ rni-name-field ）が指定されていること、および指定したフィールドがタイプ rni_name に正しくマップされていることを確認してください。
  • RNI が失敗したという応答が返された場合には、Elasticsearch がクエリーを実行するドキュメントが存在していること、および RNI プラグインがインストールされていることを確認してください。

3.5. クエリーの実行

名称のクエリーは 2 つの部分から成ります。

3.5.1. 基本クエリー

基本クエリーは、名称フィールドに対する標準クエリーです。

"query" :{ 
   "match" :{ 
       "primary_name" :"Jo Shmoe" 
  } 
}

クエリーでは、ドキュメントをインデックスする時に使用できるのと同じ 名称プロパティー を指定できます。ドキュメントの作成時とは異なり、文字列として名称フィールドが記述された JSON オブジェクトを渡す必要があります。

curl 'http://localhost:9200/rni-test/record/_search' -d '{ 
   "query" :{ 
       "match" :{ 
           "primary_name" :
"{\"data\" :\"Jo Shmoe\", \"language\" :\"eng\", \"entityType\" :\"PERSON\"}" 
       } 
   } 
}'

インデックス時と同様に、RNI は名称に基づいて一連のキーを作成し、次にインデックスされたキーと照合する複雑な内部クエリーを生成します。

3.5.2. RNI ペア名称照合による再スコア計算

RNI ペア照合機能は計算負荷が高いプロセスであるため、クエリーの 2 番目の部分では、Elasticsearch の再スコア計算を使用して、有効な候補のみが RNI ペア照合機能に渡されるようにしています。

再スコア計算では以下のパラメーターを使用します。

  • window_size（整数、デフォルト値は10）。基本クエリーから RNI ペア照合機能に送るドキュメントの数を指定します。

    このパラメーターを使用して、計算負荷が高い名称照合の実行回数を制限することで、クエリーの応答時間を短縮します。

  • query_weight （実数、デフォルト値は 1.0）。基本クエリーから返されるスコアの重み付けを指定します。

    RNI ペア照合では基本クエリーのスコアはあまり意味を持たないため、0.0 に設定することをお勧めします。

  • rescore_query_weight（実数、デフォルト値は 1.0）。RNI ペア照合の最大スコアの重み付けを指定します。

    query_weight が 0.0 で rescore_query_weight が 1.0 の場合、再スコア計算によって返されるスコアは RNI ペア照合スコア になります。

  • score_to_rescore_restriction（負でない実数、デフォルト値は 0.4）。ドキュメントを RNI 再スコア計算機能に渡すために必要な最小クエリースコアを動的に制御します。

    値が 0.0 の場合、すべてのドキュメントの再スコア計算が行われます。値を大きくすると、再スコア計算が行われるドキュメントの数が減り、精度が低下する代わりに速度が上がります。

  • windows_size_allowance（区間 (0, 1] の実数、デフォルト値は 0.5）。再スコア計算のウィンドウサイズを動的に制御します。 window_size より多くの名称がスコア計算されることはありません。

    値が 1.0 の場合、すべてのドキュメントの再スコア計算が行われます。値を大きくすると、再スコア計算が行われるドキュメントの数が増え、速度が低下する代わりに精度が向上します。

以下の例では、基本クエリーから返される上位 200 の名称に対してペア照合を実行しています。

"rescore" :{ 
   "window_size" :200, 
   "query" :{ 
     "rescore_query" :{ 
       "function_score" :{ 
         "name_score" :{ 
           "field" :"primary_name", 
           "query_name" :"Jo Shmoe" 
         } 
       } 
     }, 
     "query_weight" :0.0, 
     "rescore_query_weight" :1.0 
   } 
 }

"name_score" 関数は、指定されたフィールドのすべての名称をクエリーの名称と照合し、最大スコアを再スコア計算機能に返します。

"name_score" 関数のスコアクエリーには、以下の項目を含むオブジェクトを 1 つ以上指定する必要があります。

  • field: 照合するフィールド、タイプは "rni_name"
  • query: 検索する名称

前述の 名称プロパティー もすべて指定できます。

以下の例で、RNI クエリーパラメーターを使用して、match（照合）とrescore（再スコア計算）の両方を組み込んだ完全なクエリーを示します。

curl 'http://localhost:9200/rni-test/record/_search' -d '{   
        "query" :{ 
                "match" :{ 
                        "primary_name" :"Jo Shmoe" 
                } 
        }, 
        "rescore" :{ 
                "window_size" :200, 
                "query" :{ 
                        "rescore_query" :{ 
                                "function_score" :{ 
                                        "name_score" :{ 
                                                "field" : "primary_name", 
                                                "query_name" :"Jo Shmoe", 
                                                "score_to_rescore_restriction":1.0, 
                                                "window_size_allowance":0.5 
                                        } 
                                } 
                        }, 
                        "query_weight" :0.0, 
                        "rescore_query_weight" :1.0 
                } 
        } 
}'

このクエリーでは、"Joe Shmoe" に対する RNI 照合スコアが "_score" フィールドの値として返されます。

{ 
"_index":"rni-test", 
"_type":"record", 
"_id":"1", 
"_score":0.80217975, 
"_source":{ 
    "primary_name":"Joe Shmoe", 
    "aka":"Bossman", 
    "occupation":"business owner" 
    } 
}

3.6. 多値名称フィールドの使用

ドキュメント内の名称フィールドに複数の値が含まれることがある場合、ネストされたオブジェクトにフィールドをラップすることをお勧めします。これにより、Elasticsearch クエリーの精度が向上します。

マッピングには、名称フィールドが含まれている、タイプが "nested" のフィールドを含める必要があります。

"nested_names" :{ 
    "type" :"nested", 
    "properties" :{ 
        "name" :{ "type" :"rni_name" } 
    } 
}

ネストされたフィールドに複数の名称を追加できます。

{ 
    "nested_names" :[ 
        { 
            "name" :"Joe Smith" 
        }, 
        { 
            "name" :"Mike Schmoe" 
        }
    ] 
}

クエリーもネストする必要があります。必ず、"score_mode" を "max" に設定してください。

{ 
    "query" :{ 
        "nested" :{ 
            "path" :"nested_names", 
            "query" :{ 
                "match" :{ 
                    "nested_names.name" :"Jo Shmoe" 
                } 
            } 
        } 
    }, 
    "rescore" :{ 
        "query" :{ 
            "rescore_query" :{ 
                "nested" :{ 
                    "path" :"nested_names", 
                    "score_mode" :"max", 
                    "query" :{ 
                        "function_score" :{ 
                            "name_score" :{ 
                                "field" :"nested_names.name", 
                                "query_name" :"Jo Shmoe" 
                            } 
                        } 
                    } 
                } 
            }, 
            "query_weight" :0.0, 
            "rescore_query_weight" :1.0 
        } 
    } 
}

ネストされたオブジェクトおよびクエリーの詳細については、Elasticsearch の資料を参照してください。

3.7. データフィールド

"|" でフィールドを区切って、フィールドをもつ名称を処理できます。フィールドは空の場合もあります。各フィールドに明示的な意味づけ（姓、名など）はありませんが、フィールドをもつ 2 つの名称を比較する際にフィールドの順序は考慮されます。RNI では、フィールドの境界をまたいでいる一致（例えば、ある名称の 1 番目のフィールドが別の名称の 2 番目のフィールドに一致した場合）に割り当てられるスコアは低くなります。

データフィールドのある名称とデータフィールドのない名称を照合して一致する可能性をスコア計算する際には、データフィールドのない名称を、1 つのデータフィールドをもつ名称として処理します。

RNI では、最後の空フィールドはないものとして処理します。例えば、"Rosanne|Taylor Smith|" は、"Rosanne|Taylor Smith" と同じものとして処理されます。

空フィールドのかわりに、フィールドに不明な値を指定することもできます。不明な名称を指定するには、フィールドを *?* に置き換えます。

3.8. RNI SDK バージョンの確認

プラグインで使用されている RNI SDK のバージョンを確認するには、{index_name}/rni_plugin/_get_version の GET 要求を送信します

curl -XGET localhost:9200/rni-test/rni_plugin/_get_version
{"rosette_sdk_version":"7.15.0"}

3.9. RNI スコア

RNI のスコアは 0 から 1 の範囲です。スコアが大きいほど、関連性の高い一致である信頼度が高くなります。スコアが 1.0 の場合は、クエリーの名称文字列と結果の名称文字列が（すべての名称プロパティーも含めて）一致することを示します。スコアが 1.0 未満の場合は、類似した名称で、クエリーの名称とインデックスの名称の間に、 1 つ以上のプロパティー（起源の言語など）や、以下の 1 項目以上の相違があります。

異綴・変形 例
表音・綴りの違い Nayif Hawatmeh と Nayif Hawatma
名称構成要素の欠如 Mohammad Salah と Mohammad Abd El-Hamid Salah
希少な共通名称構成要素 Ditters が含まれている 2 つの英語の名称は、Smith が含まれている 2 つの名称よりも一致している可能性が高いといえます
イニシャル John F. Kennedy と John Fitzgerald Kennedy
ニックネーム Bobby Holguin と Robert Holguin
同語源の名称 Pedro Calzon と Peter Calzon
大文字・小文字 Rosa Elena PACHECO と Rosa Elena Pacheco
名称構成要素の順序違い Zedong Mao と Mao Zedong
分かち書きの違い Henry Van Dick と Henry VanDick, Robert Smith と Robert JohnSmyth と
対応する名称フィールド [Katherine][Anne][Cox] の場合、[Katherine][Ann][Cox] との類似度の方が、[Katherine Ann][Cox] との類似度より高くなります
名称要素の切り捨て Sawyer の場合、 Sawy との類似度の方が、Sawi との類似度より高くなります。

スコア計算は相互可換です。与えられた 2 つの名称のスコアは、どちらの名称がインデックスに含まれていてどちらの名称がクエリーに含まれているのかに関係なく、常に同じです。

4. 日付照合

RNI-Elasticsearch プラグインでは、名称照合システムの一部として日付が照合されます。2 つの日付の類似度を示す日付照合スコアが返されます。

名称照合と同様に、名称に関係した日付をその名称と関連付けてインデックスします。その上で、日付と名称をもつクエリーを実行すると、RNI-Elasticsearch から照合スコアが返されます。例えば、ある人名とその誕生日に対して個別の照合スコアが返されます。ユーザシステム内で、日付照合のスコアと名称照合のスコアを重み付けして組み合わせ、最終的な照合スコアを計算することもできます。

4.1. 日付の定義

日付には、年、月、日が含まれます。さまざまなフォーマットで日付を記述できます（例えば、December 30 1955、30 Dec 1955、12/30/55 など）。RNI-Elasticsearch では、日付に関連しない単語は除去されます。

フィールドの値がない場合は、そのフィールドは省略されます。例:1955-12-30、1955--03、12/30、 -12-、--30、1955、1955-12-.

4.2. 日付照合の使用

4.2.1. 日付のインデックス

1.インデックスを作成します。

curl -XPUT 'http://localhost:9200/rni-test'

2.日付が含まれるフィールドのマッピングを定義します。該当する各フィールドのタイプは "rni_date" です。

curl -XPUT 'http://localhost:9200/rni-test/record/_mapping' -d '{ 
    "record" :{ 
        "properties" :{ 
            "birth_date" :{ "type" :"rni_date" }, 
            "primary_name" :{ "type" :"rni_name" } 
        } 
    } 
}'

オプションとして Elasticsearch 日付形式を指定することもできます。時刻が含まれる ES 日付形式を指定した場合、RNI-Elasticsearch では時刻フィールドは無視されます。日付はすべて、この形式に準拠している必要があります。

curl -XPUT 'http://localhost:9200/rni-test/record/_mapping' -d '{ 
    "record" :{ 
        "properties" :{ 
            "birth_date" :{ 
                "type" :"rni_date", 
                "format" :"MM-yyyy-dd" 
            }, 
            "primary_name" :{ 
                "type" :"rni_name" 
            } 
        } 
    } 
}'

3.日付フィールドを含むドキュメントをインデックスします。

curl -XPUT 'http://localhost:9200/rni-test/record/1' -d '{
    "primary_name" : "Joe Schmoe",
    "birth_date" : "07-1955-24"
}'

4.2.2. 日付のクエリー

様々な方法でクエリーに日付照合を組み込むことができます。ここでは 2 つの例を示します。1 つは日付照合を単独で使用し、もう 1 つは日付照合と名称照合を使用します。

基本クエリー　基本クエリーは、日付フィールドに対する標準クエリーです。

インデックスのクエリー を参照してください。

curl 'http://localhost:9200/rni-test/record/_search' -d '{
    "query" : {
        "match" : {
            "birth_date" : "08-1955-25"
        }
    }
}'

日付による再スコア計算　RNI ペア名称照合による再スコア計算 を参照してください。

curl 'http://localhost:9200/rni-test/record/_search' -d '{
    "query" : {
        "match" : { "birth_date" : "08-1955-25" }
    },
    "rescore" : {
        "query" : {
            "rescore_query" : {
                "function_score" : {
                    "date_score" : {
                        "field" : "birth_date",
                        "query_date" : "08-1955-25"
                    }
                }
            }
            , "query_weight" : 0
        }
    }
}'

このクエリーでは、RNI 日付照合スコアが含まれた結果が返されます。

"hits": {
    "total": 1,
    "max_score": 1.618923,
    "hits": [
        {
            "_index": "test",
            "_type": "record",
            "_id": "AVXMepnorGuybmuiQtQr",
            "_score": 0.8120856,
            "_source": {
                "primary_name": "Joe Schmoe",
                "birth_date": "07-1955-24"
            }
        }
    ]
}

日付照合スコアは日付の類似度を示します。類似した日付は一致度が高く、日付照合スコアが 1 に近づきます。

例えば、11/05/1993 と 11/07/1993 は非常に類似していて 2日離れているだけなので、スコアが高くなります。一方、11/05/1993 と 11/05/1995 は 2年違うため、スコアが低くなります。

5. レコード照合

RNI-Elasticsearch プラグインには、複数のフィールドをもつドキュメント間の、単一の類似スコアを生成する関数が含まれています。フィールドのタイプは、rni_name、rni_date、その他のどの Elasticsearch フィールドタイプも使用できます。

各フィールドに異なる重みを割り当てることができます。さらに、カスタムな類似関数を使用することもできます。

5.1. レコード照合の使用

5.1.1. レコードのインデックス

1.さまざまなタイプのフィールドを含むマッピングで、インデックスを作成します。

curl -XPUT 'http://localhost:9200/rni-test' -d '{
    "mappings": {
        "record": {
            "properties": {
                "name" : { "type" : "rni_name" },
                "dob": { "type": "rni_date" },
                "height" : { "type" : "integer" },
                "nationality" : { "type" : "keyword" }
            }
        }
    }
}'

2.これらのフィールドが含まれているドキュメントをインデックスします。

curl -XPUT 'http://localhost:9200/rni-test/record/1' -d '{
    "name": "Ryan McDonagh",
    "dob": "11/19/1987",
    "nationality": "USA",
    "height": 65
}'

5.1.2. レコードのクエリー

複数のフィールドを含むレコードのクエリーも可能です。クエリーレコードのフィールドは、インデックスされたドキュメントのフィールドにマップされている必要があります。

基本クエリー　基本クエリーは、再スコア計算用の有効な候補が返される、複数のフィールドに対する標準 Elasticsearch クエリーです。

curl 'http://localhost:9200/rni-test/record/_search' -d '{
    "query" : {
        "bool" : {
            "should" : [
                { "match" : { "name" : "Brian McDonough" } },
                { "match" : { "dob" : "10/19/87" } }
            ]
        }
    }
}'

レコードによる再スコア計算　'doc_score' 関数を使用して、クエリーレコードに対するインデックス内のドキュメントのスコアを計算します。

curl 'http://localhost:9200/rni-test/record/_search' -d '{
    "query" : {
        "bool" : {
            "should" : [
                { "match" : { "name" : "Brian McDonough" } },
                { "match" : { "dob" : "10/19/87" } }
            ]
        }
    },
    "rescore" : {
        "query" : {
            "rescore_query" : {
                "function_score" : {
                    "doc_score": {
                        "fields": {
                            "name": { "query_value": "Brian McDonough" },
                            "dob": { "query_value": "10/19/87" },
                            "height": { "query_value": 67 },
                            "nationality": { "query_value": "CANADA" }
                        }
                    }
                }
            },
            "query_weight" : 0
        }
    }
}'

さらに、各フィールドに、全体的な照合ロジックにおける重要さを示す重みを割り当てることもできます。

curl 'http://localhost:9200/rni-test/record/_search' -d '{
    "query" : {
        "bool" : {
            "should" : [
                { "match" : { "name" : "Brian McDonough" } },
                { "match" : { "dob" : "10/19/87" } }
            ]
        }
    },
    "rescore" : {
        "query" : {
            "rescore_query" : {
                "function_score" : {
                    "doc_score": {
                        "fields": {
                            "name": { "query_value": "Brian McDonough", "weight": 4 },
                            "dob": { "query_value": "10/19/87", "weight": 2 },
                            "height": { "query_value": 67, "weight": 0.5 },
                            "nationality": { "query_value": "CANADA", "weight": 1 }
                        }
                    }
                }
            },
            "query_weight" : 0
        }
    }
}'

デフォルトでは、インデックス内のクエリー対象フィールドがヌルの場合、そのフィールドはスコア計算から除外され、その他のフィールドに重みが再配分されます。ただし、score_if_null オプションを使用して、インデックスドキュメントの対象フィールドがヌルの場合にこのフィールドに対して返すべきスコアを指定すれば、この動作は行われません。

curl 'http://localhost:9200/rni-test/record/_search' -d '{
    "query" : {
        "bool" : {
            "should" : [
                { "match" : { "name" : "Brian McDonough" } },
                { "match" : { "dob" : "10/19/87" } }
            ]
        }
    },
    "rescore" : {
        "query" : {
            "rescore_query" : {
                "function_score" : {
                    "doc_score": {
                        "fields": {
                            "name": { 
                                "query_value": "Brian McDonough",
                                "weight": 4,
                                "score_if_null" : 0.0
                                },
                            "dob": {
                                "query_value": "10/19/87",
                                "weight": 2
                                },
                            "height": {
                                "query_value": 67,
                                "weight": 0.5
                                },
                            "nationality": {
                                "query_value": "CANADA",
                                "weight": 1 , 
                                "score_if_null" : 1.0 
                                }
                        }
                    }
                }
            },
            "query_weight" : 0
        }
    }
}'

doc_score 関数には、多数のコアフィールドタイプ用の組込み類似度関数が含まれていますが、クエリー時にカスタムな類似度関数を与えることもできます。以下の例では、'CANADA' と 'USA' を高いスコアで一致させるシンプルな 'script_score' 関数を使用しています。 Elasticsearch のスクリプト作成 の詳細については、Elasticsearch の資料を参照してください。その他どのような 'function_score' 関数 も使用できます。

curl 'http://localhost:9200/rni-test/record/_search' -d '{
    "query" : {
        "bool" : {
            "should" : [
                { "match" : { "name" : "Brian McDonough" } },
                { "match" : { "dob" : "10/19/87" } }
            ]
        }
    },
    "rescore" : {
        "query" : {
            "rescore_query" : {
                "function_score" : {
                    "doc_score": {
                        "fields": {
                            "name": { "query_value": "Brian McDonough", "weight": 4 },
                            "dob": { "query_value": "10/19/87", "weight": 2 },
                            "height": { "query_value": 67, "weight": 0.5 },
                            "nationality": {
                                "function": {
                                    "function_score": {
                                        "script_score": {
                                            "script": {
                                                "lang": "painless",
                                                "params": {
                                                    "query_value": "CANADA"
                                                },
                                                "inline":
                                    "if (params.query_value == '\''CANADA'\'' &&
                                    doc['\''nationality'\''].value == '\''USA'\'')
                                    {return 0.8} else {return 0.2}"
                                            }
                                        }
                                    }
                               }, "weight": 1
                            }
                        }
                    }
                }
            },
            "query_weight" : 0
        }
    }
}'

注 curl コマンドで使用できるように、上記スクリプトの単一引用符はエスケープ処理されています（ '\" ）。

ドキュメントのスコアは、各フィールドの類似度スコアの 加重算術平均 で計算されます。クエリーのフィールドがインデックスのレコードにない場合、そのフィールドは無視され、その重みがその他のフィールドに均等に配分されます。

5.2. サポートされるフィールドタイプ

'doc_score' 関数は、rni_name, rni_date、および Elasticsearch コアフィールドタイプの多くをデフォルトでサポートしています。デフォルトの類似度 スコアは、すべて、0.0 から 1.0 の範囲です。

フィールドタイプ デフォルト類似関数 例
rni_name name_score (参照: RNI 名称照合スコア ) 'John David Smith' vs 'Jon D Smith' = 0.88
rni_date, date date_score (参照: RNI 日付照合スコア ) '2010-11-4' vs '2010-5-11' = 0.92
keyword, text, string Normalized edit distance '37 Congress St.' vs '35 Congres St.' = 0.875
integer, long, long, short, double, float Normalized difference (例: percentage) '65' vs '59' = 0.908
boolean Equality 'true' vs 'true' = 1.0, 'true' vs 'false' = 0.0
geo_point Log function over Haversine distance '[lat=42.361145, lon=-71.057083]' vs '[lat=42.3736, lon=-71.1097]'=0.83

6. ユーザー設定可能機能

ユースケースやデータに合わせて RNI を設定するための様々な方法が用意されています。

6.1. 停止パターンと停止語プレフィックス

インデックス時やクエリー実行時に、停止パターンや停止語プレフィックスと一致した名称要素は削除されます。プレフィックス（文字列リテラル）の削除は、停止パターン（正規表現）の適用より高速に処理できるので、名称照合から除外する敬称などのプレフィックスを効率的に削除するには、停止語プレフィックスを利用します。

各名称に対し、RNI は、まず文字レベルの正規化を実行します。この正規化では、ピリオド、カンマ、ハイフン以外の句読点が削除され、複数の空白が単一の空白に短縮され、文字はすべて小文字に変換されます。その後、RNI は、停止パターンと停止語の処理を反復します。毎回の処理の中で削除対象がなかったパターンと停止語はリストから削除されます。この反復処理は、停止パターンと停止語のリストが空になるまで行われます。

停止パターン 　停止パターンは正規表現で、インデックス時やクエリー実行時に、これと一致した名称要素が除外されます。Java 1.8 の java.util.regex.Pattern でサポートされる任意の正規表現を使用できます。詳細については、Javadoc を参照してください。

特定の言語の停止パターンは、ファイル名に 3 文字の ISO639 言語コードを使用した UTF-8 ファイルで指定します。

stopregexes_LANG[_TYPE].txt4

LANG は 3 文字の言語コードです。先頭が # の行を除き5、ファイル内の各行は正規表現です。先頭と末尾の空白は正規表現から除かれるため、先頭および末尾に空白が必要な場合には \s を使用してください。

処理対象の名称の中の、停止パターンの正規表現のどれかに一致した要素は削除されます。長い停止パターンが短い停止パターンより先に適用されるため、短い停止パターンが存在していても、その短いパターンを含む長いパターンが先に削除されます。例えば、停止パターン brigadier[- ]general は、 general も停止パターンであっても、該当する箇所で先に適用されます。

SDK には、英語（汎用および ORGANIZATION 用）、日本語（PERSON 用）、スペイン語（汎用）、および中国語（PERSON 用）の名称の停止パターンのファイルが付属しています。該当するファイルは、bt_root/rlpnc/data/rnm/ref/override にあります。汎用（特定の固有表現に特化していない）英語ファイルは、stopregexes_eng.txt です。例えば、項目

^fnu\d 
^lnu\d

は、後ろに何も続いていない fns（名が不明であることを示す一般標識）と lnu（姓が不明であることを示す一般標識）を削除することを示します。

フィールドをもつ名称の処理時に正規表現を適用するフィールドを指定することもできます。 Tab n を追加するだけです（ n はフィールド番号）。複数のフィールドに適用したい場合には、以下に示すように、各フィールドごとに記述します。フィールドなしの名称の処理時には、フィールドパラメーターは無視されます。例えば、

^lnu\d 2 
^lnu\d 3

は、フィールドのある名称内のフィールド 2 と 3 に正規表現を適用することを示します。

このファイルの内容は変更できます。他の言語の停止パターンを追加するには、同じサブディレクトリーに、ファイル名に 3 文字の言語コードを使用した追加の UTF-8 ファイルを作成します。例えば、 stopregexes_ara.txt には、アラビア語テキストの正規表現が入ります。 stopregexes_eng_PERSON.txt は、英語の PERSON 名称から特定の要素を削除するための正規表現のファイルです。

複雑なパターンを使用すると、処理時間が長くなることがあります。可能な場合は、停止語プレフィックスを使用してください。

停止語プレフィックス　停止語プレフィックスは文字列リテラルで、インデックス時やクエリー実行時に、名称要素からこれと一致したプレフィックスが削除されます。

特定の言語の停止語プレフィックスは、ファイル名に 3 文字の ISO639 言語コードが含まれた UTF-8 ファイルで指定します。

stopprefixes_LANG[_TYPE].txt4

LANG は、3 文字の言語コードです。先頭が # の行を除き5、ファイル内の各行は文字列リテラルです。

処理対象の名称の中の、これらの文字列リテラルのどれかに一致したプレフィックスは削除されます。

停止パターンと同様に、長い停止語プレフィックスは、長い停止語に含まれている短い停止語よりも優先されます。例えば、停止語プレフィックス lieutenant colonel は、colonel も停止語プレフィックスであっても、該当箇所で先に適用されます。

SDK には、英語とスペイン語の名称用の汎用停止語プレフィックスのファイルが付属しています。該当するファイルは、bt_root/rlpnc/data/rnm/ref/override 内にある stopprefixes_eng.txt および stopprefixes_spa.txt です。これらのファイルの内容は変更できます。他の言語の停止語プレフィックスを追加するには、同じディレクトリーに、ファイル名に 3 文字の言語コードを使用した UTF-8 ファイルを作成します。例えば、stopprefixes_rus.txt にはロシア語テキストで使用する停止語プレフィックスが入ります。

6.2. 名称ペア照合の優先設定

特定のフルネームペアに割り当てるスコアを指定する UTF-8 テキストファイルを作成できます。ファイル名に 3 文字の ISO639 言語コードを使用して、各フルネームペアの各フルネームの言語を指定します。

fullnames_LANG1_LANG2[_TYPE].txt6

ここで、LANG1 は 1 番目の名称の 3 文字の言語コードであり、LANG2 は 2 番目の名称の 3 文字の言語コードです。先頭が # の行を除き、ファイル内の各行は、タブ区切りのフルネームペアとスコアです。

query_name Tab index_name Tab score

スコアは 0 から 1.0 の範囲で、0 は不一致、1.0 は完全一致を示します。7

SDK には、サンプル項目がコメントアウトされた以下のサンプルファイル bt_root/rlpnc/data/rnm/ref/override/fullnames_eng_eng.txt が付属しています。このファイル内の項目のコメントを外すと、RNI インデックス内の英語の名称に適用される英語のクエリーにスコアが割り当てられます。例えば、

John Doe Joe Bloggs 1.0

は、クエリーの名称 John Doe がインデックスの名称 Joe Bloggs にスコア 1.0 で一致することを示します（この両名称は、さまざまな地域で不明な人物を示すために使用されます）。

この照合パターンは可換です。前述の項目では、クエリーの名称が Joe Bloggs で、 rni_name フィールドに John Doe が含まれているドキュメントがインデックスに入っている場合にも、一致スコアは 1.0 になります。

英語の名称と英語の名称のペアは、fullnames_eng_eng.txt に追加できます。また、ファイル名で言語を指定して、追加の設定ファイルを作成することもできます。例えば、fullnames_jpn_eng.txt に以下の項目を指定できます。

外山恒 Toyama Koichi 1.0 
ヒラリークリントン Hillary Clinton 1.0

6.3. トークンペア照合の優先設定

一致するトークン（名称要素）ペアを指定するテキストファイルを作成することができます。トークンペア照合の優先設定は、英語/英語、日本語/英語、中国語/英語、ロシア語/英語、スペイン語/英語、日本語/日本語、ロシア語/ロシア語、英語/朝鮮語、朝鮮語/朝鮮語、スペイン語/スペイン語のトークンペアでサポートされます。このペアには、正式名とニックネーム（Peter と Pete など）、および同語源の名称（Peter と Pedro など）などが該当します。トークンは空白を含みません。RNI で 2 つの名称を照合する際に、各名称にこのペアの要素が含まれている場合、結果の名称照合スコアの値が高くなります。例えば、 Abigail と Abby がトークンペアになっている場合、Abigail Harris と Abby Harris の照合スコアは、このトークンペアが指定されていなかった場合よりも高くなります。

トークンペアは、同一言語のものであっても、別々の言語のものであっても構いません。言語は、以下のようにファイル名で指定します。

tokens_LANG1_LANG2[_TYPE].txt8

ここで、LANG1 は各ペアの 1 番目のトークンの 3 文字の言語コードであり、LANG2 は各ペアの 2 番目のトークンの 3 文字の言語コードです。先頭が # の行を除き、ファイル内の各項目はタブ区切りのトークンペアです。また、少なくとも 1 つのトークンがニックネームであること（NICKNAME）や、両トークンが同語源であること（COGNATE）の指定を入れることもできます。

Token1 Tab Token2 [Tab NICKNAMEorCOGNATEorVARIANT]

トークンペアが一致しないようにする場合は、SUPPRESS を使用します。

NICKNAME、COGNATE、VARIANT、SUPPRESS のいずれも指定しなかった場合は、NICKNAME が指定されたものとして扱われます。

SDK には、英語/英語トークンペアのリストが含まれている bt_root/rlpnc/data/rnm/ref/override/tokens_eng_eng.txt が付属しています。例:

Peter Pete NICKNAME 
Peter Pedro COGNATE

このディレクトリーには、LOCATION と ORGANIZATION に対する中国語と英語のトークンオーバーライドに関する以下のファイルも含まれています。

tokens_zho_eng_LOCATION.txt、tokens_zho_eng_ORGANIZATION.txt。

同じ場所に追加のファイルを作成する際には、ファイル名で 3 文字の ISO639 言語名を使用して、ペアの各名称要素の言語を指定します。例えば、tokens_eng_eng.txt は、その内容が英語の名称と英語の名称の照合のためものであることを示しています。また、tokens_eng_eng_ORGANIZATION.txt は、その内容が英語の ORGANIZATION 名称と英語の ORGANIZATION 名称の照合に関するものであることを示しています。SDK には、LOCATION の英語/英語トークンの照合用のサンプルファイル tokens_eng_eng_LOCATION.txt が付属しています。

ファイル名およびトークンペアの言語名はアルファベット順で入力することをお勧めします。なお、スコア計算は可換であるため、結果のスコアは順序の影響を受けません。

6.4. トークンの異綴形の正規化

トークン（名称要素）の正規形と、その形に正規化すべき異綴形を指定したテキストファイルを作成できます。ファイル名で、言語と、正規化するトークンの固有表現タイプ（オプション）を指定します。

equivalenceclasses_LANG[_TYPE].txt

例えば、equivalenceclasses_jpn.txt には、任意の固有表現タイプの日本語トークンの異綴形を正規形に正規化するための項目が含まれます。

ファイル内の各項目には、正規形と、それに続く 1 つ以上の異綴形が含まれます。構文は以下のとおりです。

[normal_form1] 
variant1_1 
variant1_2 
variant1_3 
[normal_form2] 
variant2_1 
variant2_2 
variant2_3 ...

SDK には、bt_root/rlpnc/data/rnm/ref/override/equivalenceclasses_eng_PERSON.txt が付属しています。このファイルには、以下のような、 muhammad に正規化すべき異綴形のリストが含まれています。

[muhammad] 
mohammed 
mahamed 
mohamed 
mohamad 
mohammad 
muhammed 
muhamed 
muhammet 
muhamet 
md 
mohd 
muhd

異綴形のリストをこのファイルに追加できます。各リストの先頭に正規形を大括弧で囲んで指定します。

6.5. 重要でないトークン

影響を低く設定するトークンのリストを編集できます。この重みが低いトークンは、名称照合の精度にあまり寄与しない名称部分（サフィックスなど）です。

ファイル名は、lowWeightTokens_LANG.txt です。

例えば、bt_root/rlpnc/data/rnm/ref/lowWeightTokens_eng.txt には、以下のような重視しない英語トークンの項目が含まれています。"jr"、"sr"、"ii"、"iii"、"iv"、"de"。

6.6. 追加構成

カスタム言語モデルトレーニング や 名前照合パラメーターの調整 などの追加構成オプションについては、[email protected] にお問い合わせください

6.7. 日付照合パラメーター

名称照合パラメーターと同様に、一連の日付照合パラメーターが用意されています。パラメーター値は parameter_defs.yaml ファイルにあり、編集できます。このファイルは、 plugins/rni/bt_root/rlpnc/data/etc にあります。

tryDayMonthSwap　 デフォルトはオン。このパラメーターが有効になっている場合、日と月を入れ替えることで解析エラーを修正しようとします。RNI-Elasticsearch で日付を厳密に照合する場合は、オフにします。

6.7.1. スコア要素の重み

最終的な日付照合スコアに影響する要素は複数あります。要素ごとに独自のスコアが返されます。各スコアは重み付けされ、最終スコアの計算に使用されます。重みの合計は、1 に正規化されます。

1.

要素 説明 例
時間距離 日付間の時間。 January 1 2000 と December 31 1999 の 時間距離 のスコアは高くなります。
年の距離 年の間の時間。 1990 と 1980 の年の距離 のスコアは低くなります。
月の距離 月の間の数値的差。 January 20 2000 と January 3 1950 の 月の距離 のスコアは高くなります。January 1 2000 と December 31 1999 の 月の距離 のスコアは低くなります。
日の距離 日の間の数値的差。 January 1 2000 と September 1 1950 の 日の距離 のスコアは高くなります。January 1 2000 と December 31 1999 の 日の距離 のスコアは低くなります。
文字列の距離 桁の入れ替えやデータのエラーを考慮します。 03-12-1909 と 03-21-1990 の 文字列の距離 のスコアは、比較的高くなります。

RNI-Elasticsearch では、各要素の重み付けされた照合スコアを組み合わせて、最終的な日付照合スコアを生成します。

1. Copyright 2018 by Elasticsearch BV. Licensed under The Apache License Version 2.0. ↩
2. プラグインの Java のみのバージョンでは、英語、フランス語、ドイツ語、イタリア語、ポルトガル語、およびスペイン語のみサポートされています。 ↩
3. 以前のバージョンの Elasticsearch（1.x.y など）をサポートする RNI プラグインについては [email protected] にお問い合わせください。 ↩
4. _TYPE (TYPEは PERSON などの固有表現タイプ）を指定するのは、（停止リストの）名称、照合する名称、または照合するトークンにこの固有表現タイプが割り当てられている場合にのみ優先設定を適用する場合です。ファイル名に _TYPE が含まれていない場合は、固有表現タイプに関係なく、すべての名称に適用されます。 ↩
5. # は、項目の後に同じ行でコメントを開始するためにも使用できます。 ↩
6. _TYPE (TYPEは、PERSON などの固有表現タイプ）を指定するのは、ペアの名称、照合する名称、または照合するトークンにこの固有表現タイプが割り当てられている場合にのみ優先設定を適用する場合です。ファイル名に _TYPE が含まれていない場合は、固有表現タイプに関係なく、すべての名称に適用されます。 ↩
7. RNI クエリーで返される名称の最小スコアは 0 より大きくなくてはならないため、スコアが 0 の場合、RNI クエリーではその名称は返されません。一方、名称照合操作では、スコアが 0 であっても結果が返されます。 ↩
8. _TYPE (TYPEは、PERSON などの固有表現タイプ）を指定するのは、ペアのトークン、照合する名称、または照合するトークンにこの固有表現タイプが割り当てられている場合にのみ優先設定を適用する場合です。ファイル名に _TYPE が含まれていない場合は、固有表現タイプに関係なく、すべての名称に適用されます。 ↩

results matching ""

    No results matching ""