ドキュメントトランスフォーマー

ドキュメントトランスフォーマーは、クエリの結果に含まれるドキュメントに関する返される情報を変更します。

ドキュメントトランスフォーマーの使用

リクエストを実行する際に、ドキュメントトランスフォーマーは、角括弧を使用して `fl` パラメータに含めることで使用できます。例:

fl=id,name,score,[shard]

一部のトランスフォーマーでは、角括弧内にキーと値のペアとして指定できるローカルパラメータが許可または必須です。

fl=id,name,score,[explain style=nl]

通常のフィールドと同様に、Transformer がドキュメントにフィールドを追加するときに使用されるキーをプレフィックスを使用して変更できます。

fl=id,name,score,my_val_a:[value v=42 t=int],my_val_b:[value v=7 t=float]

以下のセクションでは、これらのさまざまなトランスフォーマーが何をするのかを正確に説明します。

利用可能なトランスフォーマー

[value] - ValueAugmenterFactory

すべてのドキュメントがすべてのドキュメントに格納されているフィールドであるかのように、まったく同じ値を含むように変更します。

q=*:*&fl=id,greeting:[value v='hello']&wt=xml

上記のクエリは、次のような結果を生成します。

<result name="response" numFound="32" start="0">
  <doc>
    <str name="id">1</str>
    <str name="greeting">hello</str></doc>
  </doc>
  ...

デフォルトでは、値は文字列として返されますが、特定の戻り値の型を強制するために、`t` パラメータを `int`、`float`、`double`、または `date` の値を使用して指定できます。

q=*:*&fl=id,my_number:[value v=42 t=int],my_string:[value v=42]

これらのリクエストパラメータを使用することに加えて、`solrconfig.xml` ファイルで ValueAugmenterFactory の名前付きインスタンスを追加で設定したり、既存の `[value]` トランスフォーマーのデフォルトの動作をオーバーライドしたりできます。

<transformer name="mytrans2" class="org.apache.solr.response.transform.ValueAugmenterFactory" >
  <int name="value">5</int>
</transformer>
<transformer name="value" class="org.apache.solr.response.transform.ValueAugmenterFactory" >
  <double name="defaultValue">5</double>
</transformer>

`value` オプションは、常に明示的な値が使用されるように強制しますが、`defaultValue` オプションは、`v` および `t` ローカルパラメータを使用してオーバーライドできるデフォルトを提供します。

[explain] - ExplainAugmenterFactory

デバッグセクションの各ドキュメントに関する情報とまったく同じように、各ドキュメントにスコアのインライン説明を追加します。

q=features:cache&fl=id,[explain style=nl]

`style` でサポートされる値は、`text`、`html`、および情報を構造化データとして返す `nl` です。`style=nl` を使用した上記の リクエストの出力は次のとおりです。

{ "response":{"numFound":2,"start":0,"docs":[
      {
        "id":"6H500F0",
        "[explain]":{
          "match":true,
          "value":1.052226,
          "description":"weight(features:cache in 2) [DefaultSimilarity], result of:",
          "details":[{
}]}}]}}

デフォルトのスタイルは、`solrconfig.xml` 設定で `args` パラメータを指定することで設定できます。

<transformer name="explain" class="org.apache.solr.response.transform.ExplainAugmenterFactory" >
  <str name="args">nl</str>
</transformer>

[child] - ChildDocTransformerFactory

このトランスフォーマーは、クエリに一致する各親ドキュメントのすべての子孫ドキュメント（descendant documents）を返します。これは、ネストされた子ドキュメントをインデックス化し、あらゆる種類の検索クエリに対して関連する親ドキュメントの子ドキュメントを取得する場合に役立ちます。

このトランスフォーマーは、結果ドキュメントの照合に使用されるクエリがブロックジョインクエリではない場合でも使用できることに注意してください。

q=book_title:Solr&fl=id,[child childFilter=doc_type:chapter limit=100]

関係するドキュメントに_nest_path_フィールドが含まれている場合、ドキュメントがインデックス化された元の疑似フィールド名を使用して子孫ドキュメントの階層構造を再作成するために使用されます。そうでない場合、子孫ドキュメントは匿名の子のフラットリストとして返されます。

childFilter

オプション

デフォルト：すべての子

含める子ドキュメントをフィルタリングするクエリ。階層ドキュメントが複数レベルある場合に特に役立ちます。

limit

オプション

デフォルト：-1

拡張されるドキュメントの下に返される子ドキュメントの最大数。デフォルトは-1で、無制限を意味します。

fl

オプション

デフォルト：説明を参照

トランスフォーマーが返すフィールドリスト。デフォルトはトップレベルのflです。

ここでのフィールドは、トップレベルのflパラメーターで指定されたフィールドのサブセットである必要があるという制限があります。

parentFilter

オプション

デフォルト：なし

{!child}/{!parent}クエリパーサーのof/whichパラメーターと同じ目的を果たします。ネストされたドキュメントブロックの開始と終了を識別するために、「すべての親」のセットを識別します。これは最近完全にオプションになり、廃止されたようです。今後のSolrリリースで削除される可能性が高いため、何らかの用途がある場合は、プロジェクトに知らせてください！

実験的なchildFilter構文

_nest_path_フィールドが定義されている場合、childFilterオプションは、「パス構文」制限と従来のフィルタリングクエリを組み合わせる実験的な構文をサポートします。

この構文は、:文字を含むクエリの前に/で区切られたパス構造を含めることでトリガーされます。

「パス」が/文字で始まる場合、変換されるドキュメントがルートレベルのドキュメントでない場合でも、ブロックのルートドキュメントから始まるネストされた疑似フィールドドキュメントの「パス」が存在するドキュメントに一致を制限します。

いくつかの例

  • childFilter="/skus/*:*"

    • 現在のドキュメントの子孫であり、/skusの「ネストパス」を持つドキュメントに一致しますが、それらのskusの子には一致しません。

  • childFilter="/skus/color_s:RED"

    • 現在のドキュメントの子孫であるすべてのドキュメントに一致します。color_s:REDに一致し、/skusの「ネストパス」を持ちますが、それらのskusの子には一致しません。

  • childFilter="/skus/manuals/*:*"

    • 現在のドキュメントの子孫であり、/skus/manualsの「ネストパス」を持つドキュメントに一致しますが、それらのmanualsの子には一致しません。

パスが/で始まらない場合、それらは「パスサフィックス」として扱われます

  • childFilter="manuals/*:*"

    • ネストの深さに関係なく、「ネストパス」が「manuals」で終わる現在のドキュメントの子孫であるドキュメントに一致しますが、それらのmanualsの子には一致しません。

[shard] - ShardAugmenterFactory

このトランスフォーマーは、分散リクエストにおいて各ドキュメントがどのシャードから来たかについての情報を追加します。

q=fl=id,[shard]

styleローカルパラメータは、id（デフォルト）またはurls（後方互換性のためにすべてのレプリカURLのパイプ区切りリストを返す）のいずれかとして指定できます。

デフォルトのスタイルは、solrconfig.xml設定でargsパラメータを指定することで変更できます

<transformer name="shard" class="org.apache.solr.response.transform.ShardAugmenterFactory" >
  <str name="args">urls</str>
</transformer>

[docid] - DocIdAugmenterFactory

このトランスフォーマーは、内部LuceneドキュメントIDを各ドキュメントに追加します。これは主にデバッグの目的でのみ役立ちます。

DocIdAugmenterFactoryは、リクエストパラメータまたは設定オプションをサポートしていません。

[elevated] および [excluded]

これらのトランスフォーマーは、クエリ昇格コンポーネントを使用する場合にのみ使用できます。

  • [elevated]は、各ドキュメントにそれが昇格されたかどうかを示す注釈を付けます。

  • [excluded]は、各ドキュメントにそれが除外されたかどうかを示す注釈を付けます。これは、markExcludesパラメータも使用する場合にのみサポートされます。

fl=id,[elevated],[excluded]&excludeIds=GB18030TEST&elevateIds=6H500F0&markExcludes=true
{ "response":{"numFound":32,"start":0,"docs":[
      {
        "id":"6H500F0",
        "[elevated]":true,
        "[excluded]":false},
      {
        "id":"GB18030TEST",
        "[elevated]":false,
        "[excluded]":true},
      {
        "id":"SP2514N",
        "[elevated]":false,
        "[excluded]":false},
]}}

[json] / [xml]

これらのトランスフォーマーは、有効なXMLまたはJSON構造の文字列表現を含むフィールド値を、文字列値ではなく実際の生のXMLまたはJSON構造に置き換えます。それぞれ特定のライターにのみ適用されます。つまり、[json]はwt=jsonにのみ適用され、[xml]はwt=xmlにのみ適用されます。

fl=id,source_s:[json]&wt=json

[subquery]

このトランスフォーマーは、ドキュメントフィールドをサブクエリパラメータの入力として渡すことで、変換ドキュメントごとに個別のクエリを実行します。通常、{!join}および{!parent}クエリパーサーで使用され、[child]の改善を目的としています。

  • 一意の名前を付ける必要があります：fl=*,children:[subquery]

  • いくつか存在する可能性があります。例：fl=*,sons:[subquery],daughters:[subquery]。

  • すべての[subquery]出現は、指定された名前で結果ドキュメントにフィールドを追加します。このフィールドの値はドキュメントリストであり、ドキュメントフィールドを入力として使用してサブクエリを実行した結果です。

  • サブクエリはデフォルトで/select検索ハンドラーを使用し、/selectが設定されていない場合はエラーを返します。これは、foo.qtパラメータを提供することで変更できます。

さまざまな形式を使用した例を以下に示します

XML
  <result name="response" numFound="2" start="0">
      <doc>
         <int name="id">1</int>
         <arr name="title">
            <str>vdczoypirs</str>
         </arr>
         <result name="children" numFound="1" start="0">
            <doc>
               <int name="id">2</int>
               <arr name="title">
                  <str>vdczoypirs</str>
               </arr>
            </doc>
         </result>
      </doc>
  ...
JSON
{ "response":{
    "numFound":2, "start":0,
    "docs":[
      {
        "id":1,
        "subject":["parentDocument"],
        "title":["xrxvomgu"],
        "children":{
           "numFound":1, "start":0,
           "docs":[
              { "id":2,
                "cat":["childDocument"]
              }
            ]
      }}]}}
SolrJ
 SolrDocumentList subResults = (SolrDocumentList)doc.getFieldValue("children");

サブクエリの結果フィールド

サブクエリドキュメントリストに表示するには、両方のflパラメータでフィールドを指定する必要があります。メインのfl（メインの結果ドキュメントにこのフィールドがない場合でも）とサブクエリのfl（例：foo.fl）です。

ワイルドカードは、これらのパラメータのいずれかまたは両方で使用できます。たとえば、フィールドtitleがカテゴリサブクエリに表示される必要がある場合は、次のいずれかの方法で実行できます。

fl=...title,categories:[subquery]&categories.fl=title&categories.q=...
fl=...title,categories:[subquery]&categories.fl=*&categories.q=...
fl=...*,categories:[subquery]&categories.fl=title&categories.q=...
fl=...*,categories:[subquery]&categories.fl=*&categories.q=...

サブクエリパラメータのシフト

サブクエリがfl=*,foo:[subquery]として宣言されている場合、サブクエリパラメータには、指定された名前とピリオドがプレフィックスとして付けられます。例えば

q=*:*&fl=*,**foo**:[subquery]&**foo.**q=to be continued&**foo.**rows=10&**foo.**sort=id desc

サブクエリパラメータの入力としてのドキュメントフィールド

一部のドキュメントフィールド値をサブクエリのパラメータとして渡す必要があります。これは、暗黙的なrow.fieldnameパラメータによってサポートされており、ローカルパラメータ構文を介して参照できます（ただし、それだけではありません）。

q=name:john&fl=name,id,depts:[subquery]&depts.q={!terms f=id v=$row.dept_id}&depts.rows=10

ここでは、検索結果の従業員ごとに部門が取得されます。SQLのjoin ON emp.dept_id=dept.idのようなものと言えるでしょう。

ドキュメントフィールドに複数の値がある場合、デフォルトではカンマで連結されます。これは、ローカルパラメータfoo:[subquery separator=' ']で変更できます。これは、{!terms}をスムーズに動作させるためのものです。

置換されたサブクエリリクエストパラメータをログに記録するには、対応するパラメータ名を追加します。例：depts.logParamsList=q,fl,rows,row.dept_id

SolrCloudのコアとコレクション

foo:[subquery fromIndex=departments]を使用して、同じノード上の別のコアでサブクエリを呼び出します。これは、ユーザー管理クラスターで{!join}が行うことです。SolrCloudでは、サブクエリのネイティブパラメータ（collection, shardsなど）のみを指定します。例：

q=*:*&fl=\*,foo:[subquery]&foo.q=cloud&foo.collection=departments

サブクエリコレクションに異なる一意のキーフィールド名（プライマリコレクションのidではなくfoo_idなど）がある場合は、この違いに対応するために次のパラメータを追加します

foo.fl=id:foo_id&foo.distrib.singlePass=true

そうでない場合、QueryComponent.mergeIdsからNullPointerExceptionが発生します。

[geo] - 地理空間フォーマッター

指定されたフォーマットタイプ名を使用して、空間フィールドの空間データをフォーマットします。2つの内部パラメータが必要です。フィールド名にはf、フォーマット名にはwです。例：geojson:[geo f=mySpatialField w=GeoJSON]。

通常は、空間フィールドタイプのformat属性をWKTまたはGeoJSONに設定することで、必要なフォーマットタイプを一貫して選択します。詳細については、空間検索のセクションを参照してください。一貫していれば、保存したとおりに出力されます。このトランスフォーマーは、取得時に空間フォーマットを別のものに変換する便利な方法を提供します。

さらに、この機能は、潜在的に大きなベクトルジオメトリの二重保存を回避するために、RptWithGeometrySpatialFieldと非常に役立ちます。このトランスフォーマーは、そのフィールドタイプを検出し、ディスク上の内部コンパクトバイナリ表現（docValues内）からジオメトリを取得し、必要に応じてフォーマットします。そのため、フィールドを保存済みとしてマークする必要はありません。これは冗長になります。ある意味で、docValuesと保存値ストレージ間のこの二重ストレージは空間に固有のものではありませんが、ポリゴンジオメトリでは大量のデータになる可能性があり、さらに冗長な形式（GeoJSONやWKTなど）で保存することは避けたいでしょう。

[features] - LTRFeatureLoggerTransformerFactory

「LTR」プレフィックスは、学習ランキングを表します。このトランスフォーマーは、フィーチャの値を返し、フィーチャの抽出とフィーチャのロギングに使用できます。

fl=id,[features store=yourFeatureStore]

これは、yourFeatureStoreストアのフィーチャの値を返します。

fl=id,[features]&rq={!ltr model=yourModel}

[features]を学習ランキング再ランキングクエリと一緒に使用すると、再ランキングモデル（yourModel）のフィーチャの値が返されます。