共通クエリパラメータ

いくつかのクエリパーサーは、サポートされているクエリパラメーターを共有します。

次のセクションでは、検索リクエストハンドラーでサポートされている、Solr の共通クエリパラメーターについて説明します。

defType パラメーター

defType パラメーターは、リクエスト内のメインのクエリパラメーター（q）を処理するために Solr が使用するクエリパーサーを選択します。例：

defType=dismax

defType パラメーターが指定されていない場合、デフォルトでは、標準クエリパーサーが使用されます。（例：defType=lucene）

sort パラメーター

sort パラメーターは、検索結果を昇順（asc）または降順（desc）で並べ替えます。このパラメーターは、数値またはアルファベットのコンテンツで使用できます。方向は、すべて小文字またはすべて大文字で入力できます（つまり、asc と ASC の両方が受け入れられます）。

Solr は、クエリ応答を次のように並べ替えることができます。

  • ドキュメントスコア

  • 関数の結果

  • docValues="true" を持つ（または multiValued="false" および indexed="true" を持つ）プリミティブフィールド（数値、文字列、ブール値、日付など）の値。この場合、インデックス付きのタームは、実行時に DocValue のような構造を動的に構築するために使用されます。

  • 検索に使用されるアナライザーに関係なく、元の入力文字列でソートできるように、デフォルトで docValues="true" を暗黙的に使用する SortableTextField。

  • ドキュメントごとに 1 つのタームのみを生成するアナライザー（KeywordTokenizer など）を使用する単一値の TextField。TextField は docValues="true" をサポートしていませんが、DocValue のような構造が実行時に動的に構築されます。

    • 注：検索を容易にするためにトークン化したいフィールドでソートできるようにする場合は、スキーマで copyField ディレクティブを使用してフィールドを複製します。次に、フィールドを検索し、そのクローンでソートします。

プリミティブフィールド、またはmultiValued="true"であるSortableTextFieldの場合、ソートに使用される各ドキュメントの代表値は、ソートの方向によって異なります。昇順（asc）ソートの場合、各ドキュメントの最小値が使用され、降順（desc）ソートの場合、各ドキュメントの最大値が使用されます。このデフォルトの動作は、2つの引数を持つfield()関数を使用して明示的にソートする場合と同等です。sort=field(name,min) ascおよびsort=field(name,max) desc

以下の表は、sortパラメータのさまざまな設定に対するSolrの応答を説明しています。

例 結果

sortパラメータが省略された場合、パラメータがscore descに設定されているかのようにソートが実行されます。

score desc

スコアの高い順から低い順に降順でソートします。

price asc

priceフィールドの昇順でソートします。

div(popularity,price) desc

関数popularity / priceの結果の降順でソートします。

inStock desc, price asc

inStockフィールドの内容で降順にソートし、複数のドキュメントのinStockフィールドの値が同じ場合は、priceフィールドの内容で昇順にソートします。

categories asc, price asc

(複数値を持つ)categoriesフィールドの最小値を昇順にソートし、複数のドキュメントのcategoriesの最小値が同じ場合は、priceフィールドの内容で昇順にソートします。

sortパラメータの引数について

  • ソート順序には、フィールド名（または擬似フィールドとしてのscore）の後に、空白（URL文字列では+または%20としてエスケープ）、続いてソート方向（ascまたはdesc）を含める必要があります。

  • 複数のソート順序は、次の構文を使用してコンマで区切ることができます。sort=<フィールド名><方向>,<フィールド名><方向>],…​

    • 複数のソート基準が指定されている場合、最初の基準が同点の場合にのみ、2番目の基準が使用されます。3番目の基準がある場合は、最初と2番目の基準が同点の場合にのみ使用されます。以下同様です。

    • ドキュメントが明示的なソート基準のすべてで同点の場合、Solrは各ドキュメントのLuceneドキュメントIDを最終的なタイブレーカーとして使用します。この内部プロパティは、セグメントのマージやドキュメントの更新中に変更される可能性があり、予期しない結果の順序変更につながる可能性があります。この動作を回避したいユーザーは、同点が発生しないように、idなどの一意またはほとんど共有されないフィールドに追加のソート基準を定義できます（例：price desc,id asc）。

startパラメータ

指定した場合、startパラメータはクエリの結果セットへのオフセットを指定し、Solrにこのオフセットから結果の表示を開始するように指示します。

デフォルト値は0です。つまり、デフォルトでは、Solrは結果自体が始まる場所からオフセットなしで結果を返します。

startパラメータを3などの他の数値に設定すると、Solrは先行するレコードをスキップし、オフセットで識別されたドキュメントから開始します。

startパラメータは、ページングに使用できます。たとえば、rowsパラメータが10に設定されている場合、startを0に設定して3ページの結果を表示し、同じクエリを再発行してstartを10に設定し、再度クエリを発行してstartを20に設定できます。

rowsパラメータ

rowsパラメータを使用して、クエリの結果をページ分割できます。このパラメータは、Solrが一度にクライアントに返す、結果セット全体からのドキュメントの最大数を指定します。

デフォルト値は10です。つまり、デフォルトでは、Solrはクエリへの応答として一度に10個のドキュメントを返します。

canCancelパラメータ

このパラメータは、タスク管理インターフェイスを使用して、このクエリが実行中にキャンセル可能かどうかを定義します。

queryUUIDパラメータ

キャンセル可能なクエリの場合、これにより、クエリを識別するためのカスタムUUIDを指定できます。canCancelが指定されていて、queryUUIDが設定されていない場合、自動生成されたUUIDがクエリに割り当てられます。

queryUUIDが指定されている場合、このUUIDがクエリの識別に使用されます。queryUUIDを使用する場合、UUIDの一意性を保証する責任は呼び出し側にあることに注意してください。元のクエリUUIDがまだアクティブな間にクエリUUIDが再利用された場合、2番目のクエリで例外がスローされます。

ユーザーは、すべてのカスタムUUIDを使用するか、システムがUUIDを生成することに完全に依存することをお勧めします。この2つを混在させると、UUIDの競合が発生する可能性があります。

fq（フィルタークエリ）パラメータ

fqパラメータは、スコアに影響を与えることなく、返されるドキュメントのスーパーセットを制限するために使用できるクエリを定義します。fqで指定されたクエリはメインクエリとは独立してキャッシュされるため、複雑なクエリを高速化するのに非常に役立ちます。後のクエリが同じフィルターを使用すると、キャッシュヒットが発生し、フィルター結果はキャッシュから迅速に返されます。

fqパラメータを使用する場合は、次の点に注意してください。

  • fqパラメータは、クエリ内で複数回指定できます。ドキュメントは、パラメータの各インスタンスから得られるドキュメントセットの交差部分に含まれている場合にのみ、結果に含まれます。以下の例では、人気度が10より大きく、セクションが0のドキュメントのみが一致します。

    fq=popularity:[10 TO *]&fq=section:0

  • フィルタークエリには、複雑なブールクエリを含めることができます。上記の例は、次のように、2つの必須句を持つ単一のfqとしても記述できます。

    fq=+popularity:[10 TO *] +section:0

  • 各フィルタークエリからのドキュメントセットは、独立してキャッシュされます。したがって、前の例に関して言えば、それらの句が頻繁に一緒に表示される場合は、2つの必須句を含む単一のfqを使用し、比較的独立している場合は、2つの別々のfqパラメータを使用します。（キャッシュサイズの調整と、フィルターキャッシュが実際に存在することの確認については、キャッシュを参照してください。）

  • filter(condition)構文をfq内で使用して、句を個別にキャッシュし、特に、キャッシュされたフィルタークエリの和集合を実現することもできます。

  • すべてのパラメータと同様に、URL内の特殊文字は適切にエスケープされ、16進数値としてエンコードされる必要があります。URLエンコードに役立つオンラインツールがあります。たとえば、http://meyerweb.com/eric/tools/dencoder/。

cacheローカルパラメータ

Solrは、デフォルトでフィルターキャッシュにフィルタークエリの結果をキャッシュします。無効にするには、fq={!geofilt cache=false}…​のように、ブール値のcacheローカルパラメータを使用します。クエリが繰り返される可能性が低いと思われる場合は、これを行います。

キャッシュされないフィルタークエリも、評価順序に関するヒントを提供するcostローカルパラメータをサポートします。これにより、高価なキャッシュされないフィルターの前に、安価なキャッシュされないフィルターを順序付けることができます。Luceneレイヤーでは、これは、クエリにTPIがある場合はTwoPhaseIterator.matchCostにマップされます。

ポストフィルター：非常にコストの高いフィルターの場合、cache=falseおよびcost>=100、およびクエリがPostFilterインターフェイスを実装している場合、そのクエリからコレクターが要求され、メインクエリと他のすべてのフィルタークエリに一致した後、ドキュメントをフィルター処理するために使用されます。複数のポストフィルターが存在する可能性があります。これらもコストによって順序付けられます。

ほとんどのクエリでは、デフォルトの動作はcost=0ですが、一部のタイプのクエリ（{!frange}など）は、PostFilterとして使用する場合に最も効率的であるため、デフォルトでcost=100になります。

これは、3つの通常のフィルターの例です。各フィルターによって生成された一致するすべてのドキュメントは、事前に計算され、独立してキャッシュされます。

q=some keywords
fq=quantity_in_stock:[5 TO *]
fq={!frange l=10 u=100}mul(popularity,price)
fq={!frange cost=200 l=0}pow(mul(sum(1, query('tag:smartphone')), div(1,avg_rating)), 2.3)

これらは、キャッシュなしで実行される同じフィルターです。quantity_in_stockフィールドに対する単純な範囲クエリは、従来のLuceneフィルターのようにメインクエリと並行して実行されますが、2つのfrangeフィルターは、各ドキュメントがすでにメインクエリとquantity_in_stock範囲クエリに一致した場合にのみチェックされます。最初に、より単純なmul(popularity,price)（暗黙的なcost=100のため）がチェックされ、一致した場合にのみ、最終的な非常に複雑なフィルター（より高いcost=200を持つ）がチェックされます。

q=some keywords
fq={!cache=false}quantity_in_stock:[5 TO *]
fq={!frange cache=false l=10 u=100}mul(popularity,price)
fq={!frange cache=false cost=200 l=0}pow(mul(sum(1, query('tag:smartphone')), div(1,avg_rating)), 2.3)

fl（フィールドリスト）パラメータ

flパラメータは、クエリ応答に含まれる情報を、指定されたフィールドのリストに制限します。フィールドは、stored="true"またはdocValues="true"``のいずれかである必要があります。

フィールドリストは、スペース区切りまたはコンマ区切りのフィールド名のリストとして指定できます。文字列 "score" を使用して、特定のクエリに対する各ドキュメントのスコアをフィールドとして返すことを示すことができます。ワイルドカード文字*は、stored="true"またはdocValues="true"およびuseDocValuesAsStored="true"（docValuesが有効な場合のデフォルト）のいずれかであるドキュメント内のすべてのフィールドを選択します。ワイルドカード文字をフィールド名と組み合わせて、複数のフィールド名に一致するglobパターンを作成します。

疑似フィールド、関数、およびトランスフォーマーをフィールドリストリクエストに追加することもできます。

この表は、flの基本的な使用例を示しています。

フィールドリスト 結果

id name price

id、name、およびpriceフィールドのみを返します。

id,name,price

id、name、およびpriceフィールドのみを返します。

id name, price

id、name、およびpriceフィールドのみを返します。

id na* price

id、name、name_exact、およびpriceフィールドを返します。

id na*e price

id、name、およびpriceフィールドを返します。

id score

idフィールドとスコアを返します。

*

各ドキュメント内のすべてのstoredフィールドと、useDocValuesAsStored="true"を持つdocValuesフィールドを返します。これは、flパラメータのデフォルト値です。

* score

各ドキュメント内のすべてのフィールドと、各フィールドのスコアを返します。

*,dv_field_name

各ドキュメント内のすべてのstoredフィールドと、useDocValuesAsStored="true"を持つdocValuesフィールド、およびuseDocValuesAsStored="false"の場合でも、dv_field_nameからのdocValuesを返します。

flでの関数

関数クエリは、結果内の各ドキュメントに対して計算され、擬似フィールドとして返されます。

fl=id,title,product(price,popularity)

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

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

fl=id,title,[explain]

フィールド名エイリアス

displayName:値をプレフィックスとして追加することにより、フィールド、関数、またはトランスフォーマーのレスポンスで使用されるキーを変更できます。

たとえば、why_scoreは以下の表示名です。

fl=id,sales_price:price,secret_sauce:prod(price,popularity),why_score:[explain style=nl]
{
"response": {
    "numFound": 2,
    "start": 0,
    "docs": [{
        "id": "6H500F0",
        "secret_sauce": 2100.0,
        "sales_price": 350.0,
        "why_score": {
            "match": true,
            "value": 1.052226,
            "description": "weight(features:cache in 2) [DefaultSimilarity], result of:",
            "details": [{
                "..."
}]}}]}}

debugパラメータ

debugパラメータは複数回指定でき、次の引数をサポートします。

  • debug=query：クエリに関するデバッグ情報のみを返します。

  • debug=timing：クエリの処理にかかった時間に関するデバッグ情報を返します。

  • debug=results：スコアの結果（「説明」とも呼ばれます）に関するデバッグ情報を返します。

    • デフォルトでは、スコアの説明は、構造と読みやすさのために改行とタブインデントを使用して、大きな文字列値として返されますが、追加のdebug.explain.structured=trueパラメータを指定して、この情報をwtで要求された応答形式にネイティブなネストされたデータ構造として返すことができます。

  • debug=all：リクエストに関する利用可能なすべてのデバッグ情報を返します。別の使用法はdebug=trueです。

Solrの古いバージョンとの下位互換性のために、debugQuery=trueをdebug=allを示す別の方法として代わりに指定できます。

デフォルトの動作は、デバッグ情報を含めないことです。

explainOther パラメーター

explainOther パラメーターは、ドキュメントのセットを特定するための Lucene クエリを指定します。このパラメーターが含まれており、空白以外の値に設定されている場合、クエリはデバッグ情報と、メインクエリ（q パラメーターで指定）に対する、Lucene クエリに一致する各ドキュメントの「explain info」を返します。例:

q=supervillains&debugQuery=on&explainOther=id:juggernaut

上記のクエリを使用すると、上位に一致するドキュメントのスコアリング explain info を調べ、id:juggernaut に一致するドキュメントの explain info と比較して、ランキングが期待どおりでない理由を特定できます。

このパラメーターのデフォルト値は空白であり、追加の「explain info」は返されません。

timeAllowed パラメーター

このパラメーターは、検索の完了に許容される時間（ミリ秒単位）を指定します。この時間が検索完了前に経過した場合、部分的な結果が返されますが、numFound、ファセットカウント、結果の統計などの値は、結果セット全体に対して正確ではない場合があります。タイムアウトの場合、omitHeader が true に設定されていない場合、レスポンスヘッダーには partialResults という特別なフラグが含まれます。timeAllowed を cursorMark と組み合わせて使用し、partialResults フラグが存在する場合、結果セットで一部の一致するドキュメントがスキップされている可能性があります。さらに、partialResults フラグが存在する場合、結果がさらに存在する可能性があっても、cursorMark が nextCursorMark と一致することがあります。

{
  "responseHeader": {
    "status": 0,
    "zkConnected": true,
    "partialResults": true,
    "QTime": 20,
    "params": {
      "q": "*:*"
    }
  },
  "response": {
    "numFound": 77,
    "start": 0,
    "docs": [ "..." ]
  }
}

この値は、次の時点でのみチェックされます。

  1. クエリ展開、および

  2. ドキュメント収集

  3. Doc Values の読み込み

このチェックは定期的に実行されるため、リクエストが中止されるまでに処理できる実際の時間は、timeAllowed の値以上になります。リクエストが他の段階、カスタムコンポーネントなどでより多くの時間を消費する場合、このパラメーターはリクエストを中止することを目的としていません。通常の検索、JSON ファセット、およびアナリティクスコンポーネントは、このパラメーターに従ってリクエストを中止します。

segmentTerminateEarly パラメーター

このパラメーターは、true または false のいずれかに設定できます。

true に設定され、このコレクションの mergePolicyFactory が、このクエリに指定された sort パラメーターと互換性のある sort オプションを使用する SortingMergePolicyFactory である場合、Solr は現在の結果ページ候補ではないドキュメントをセグメントごとにスキップできます。

早期終了が使用されている場合、segmentTerminatedEarly ヘッダーが responseHeader に含まれます。

timeAllowed パラメーターの使用と同様に、早期セグメント終了が発生すると、numFound、ファセットカウント、結果の統計などの値は、結果セット全体に対して正確ではない場合があります。

このパラメーターのデフォルト値は false です。

omitHeader パラメーター

このパラメーターは、true または false のいずれかに設定できます。

true に設定した場合、このパラメーターは返される結果からヘッダーを除外します。ヘッダーには、完了にかかった時間などのリクエストに関する情報が含まれています。このパラメーターのデフォルト値は false です。timeAllowed、shards.tolerant など、部分的な結果につながる可能性があるパラメーターを使用する場合は、ヘッダーを保持して、partialResults フラグをチェックできるようにし、numFound、nextCursorMark、ファセットカウント、結果の統計などの値を部分的な結果のコンテキストで解釈できるようにすることをお勧めします。

wt パラメーター

wt パラメーターは、Solr がクエリのレスポンスのフォーマットに使用するレスポンスライターを選択します。レスポンスライターの詳細については、レスポンスライターを参照してください。

クエリで wt パラメーターを定義しない場合、レスポンスの形式として JSON が返されます。

logParamsList パラメーター

デフォルトでは、Solr は各リクエストのすべてのクエリパラメーターをログに記録します。このパラメーターを使用すると、ログに記録する必要があるパラメーター名のコンマ区切りの「許可リスト」を指定することで、ユーザーはこの動作をオーバーライドできます。これにより、組織にとって重要と考えられるパラメーターのみにログを制御できます。

logParamsList は、クエリパラメーターのロギングのみを制御します。リクエストパス、本文などで指定されたパラメーターには適用されません。

たとえば、次のように定義できます。

logParamsList=q,fq

そして、'q' および 'fq' パラメーターのみがログに記録されます。

パラメーターをログに記録しない場合は、logParamsList を空として送信できます（つまり、logParamsList=）。

このパラメーターは、クエリリクエストだけでなく、Solr へのあらゆる種類のリクエストに適用されます。

echoParams パラメーター

echoParams パラメーターは、リクエストパラメーターに関するどの情報をレスポンスヘッダーに含めるかを制御します。

echoParams パラメーターは、次の値を受け入れます。

  • explicit: 実際のリクエストに含まれるパラメーターのみが、レスポンスヘッダーの params セクションに追加されます。

  • all: クエリに寄与したすべてのリクエストパラメーターを含めます。これには、リクエストに含まれるパラメーターに加えて、solrconfig.xml にあるリクエストハンドラー定義で定義されているすべてと、_ パラメーターが含まれます。パラメーターがリクエストハンドラー定義とリクエストの両方に含まれている場合、レスポンスヘッダーに複数回表示されます。

  • none: レスポンスヘッダーの params セクションを完全に削除します。リクエストパラメーターに関する情報はレスポンスでは利用できません。

デフォルト値は none ですが、多くの solrconfig.xml ハンドラーはデフォルトを explicit に設定します。これは、echoParams パラメーターがその SearchHandler のデフォルトに設定されていたため、それ自体はエコーされず、リクエスト自体からの 3 つのパラメーター（q、wt、および indent）のみがエコーされた JSON レスポンスの例です。

{
  "responseHeader": {
    "status": 0,
    "QTime": 0,
    "params": {
      "q": "solr",
      "indent": "true",
      "wt": "json",
      "_": "1458227751857"
    }
  },
  "response": {
    "numFound": 0,
    "start": 0,
    "docs": []
  }
}

これは、前の例で使用した 3 つのパラメーターに echoParams=all を追加する同様のリクエストを送信した場合に発生することです。

{
  "responseHeader": {
    "status": 0,
    "QTime": 0,
    "params": {
      "q": "solr",
      "df": "text",
      "indent": "true",
      "echoParams": "all",
      "rows": "10",
      "wt": "json",
      "_": "1458228887287"
    }
  },
  "response": {
    "numFound": 0,
    "start": 0,
    "docs": []
  }
}

minExactCount パラメーター

このパラメーターを使用すると、Solr は少なくともこの値まで正確にヒット数をカウントします。その後、Solr は上位 N に入るのに十分なスコアを持たないドキュメントをスキップできます。これにより、検索クエリのパフォーマンスを大幅に向上させることができます。一方で、このパラメーターを使用すると、numFound は正確ではなく、代わりに概算になる可能性があります。numFoundExact ブール属性は、numFound 値が正確か概算かを示すために、すべてのレスポンスに含まれます。概算の場合、クエリの実際のヒット数は、numFound 以上であることが保証されます。

概算ドキュメントカウントと minExactCount の詳細

  • レスポンスで返されるドキュメントは、上位スコアを持つドキュメントであることが保証されています。このパラメーターは、Solr がレスポンスで返されるドキュメントをスキップすることはなく、クエリに一致するものの、スコアが上位 N に入らないほど低いドキュメントのカウントのみをスキップできるようにします。

  • minExactCount を提供しても、Solr が概算ヒットカウントを使用する（したがって、高速化を提供する）ことは保証されません。一部のタイプのクエリ、または他のパラメーター（ファセットが要求された場合など）では、正確なカウントが必要です。

  • 概算カウントは、最初に score desc でソートする場合（これは Solr のデフォルトのソートです）にのみ使用できます。score desc の後に他のフィールドを使用できますが、スコアの前で他の種類のソートを使用すると、概算は適用されません。

  • 複数のシャードにわたる分散クエリを実行する場合、各シャードは minExactCount まで正確にヒット数をカウントします（つまり、クエリは numShards * minExactCount 個のドキュメントにヒットし、レスポンスの numFound は引き続き正確である可能性があります）。たとえば

q=quick brown fox&minExactCount=100&rows=10
"response": {
    "numFound": 153,
    "start": 0,
    "numFoundExact": false,
    "docs": [{"doc1"}]
}

numFoundExact=false であるため、クエリに一致するドキュメントの数が 153 以上であることがわかります。minExactCount により高い値を指定した場合

q=quick brown fox&minExactCount=200&rows=10
"response": {
    "numFound": 163,
    "start": 0,
    "numFoundExact": true,
    "docs": [{"doc1"}]
}

この場合、163 がクエリの正確なヒット数であることがわかります。両方のクエリは、上位 10 件で同じ数のドキュメントを返す必要があります。