常用查詢參數

幾個查詢剖析器共用支援的查詢參數。

以下章節說明 Solr 的常用查詢參數，這些參數由搜尋請求處理器支援。

defType 參數

選用

預設值：lucene

defType 參數選擇查詢剖析器來處理請求中的主要查詢參數 (q)。可接受的值包括：lucene (標準查詢剖析器)、dismax (DisMax 查詢剖析器)、edismax (擴充 DisMax (eDisMax) 查詢剖析器) 或其他查詢剖析器之一。

sort 參數

選用

預設值：score desc

sort 參數指定傳回文件的順序。

以下是一些範例排序值

範例 結果

score desc

依分數由高到低排序。

price asc

依價格欄位由低到高排序。

div(popularity,price) desc

依函數 popularity / price 的結果由高到低排序。

inStock desc, price asc

依 inStock 欄位的內容由高到低排序，然後當多個文件的 inStock 欄位值相同時，這些結果會依 price 欄位的內容由低到高排序。

categories asc

由於 categories 是一個多值欄位，而且我們是升冪排序，因此會依 categories 欄位的最低值升冪排序。這相當於 field(categories,min) asc

更具體來說，Solr 可以根據以下內容排序查詢回應

  • 文件分數

  • 函數結果

  • 具有 docValues="true" 的單值基本欄位（數值、字串、布林值、日期等）（或 indexed="true"，在這種情況下，索引詞會在執行階段即時用來建立類似 DocValue 的結構）。

  • 單值 SortableTextField 預設會隱含使用 docValues="true"，允許依原始輸入字串排序，而不考慮用於搜尋的分析器。

  • 單值 TextField，它具有一個分析器（例如 KeywordTokenizer），每個文件只產生一個詞。由於 TextField 不支援 docValues="true"，因此會在執行階段即時建立類似 DocValue 的結構。

    • 注意：如果您想要能夠依要標記化內容以方便搜尋的欄位排序，請在 Schema 中使用 copyField 指示來複製該欄位。然後在該欄位上搜尋，並依其複製的欄位排序。

  • 具有 docValues="true" 或 SortableTextFields 的多值基本欄位。在這種情況下，會根據排序方向為每個文件使用一個代表值。升冪時會使用最小值。降冪時會使用最大值。這相當於使用 2 個參數的 field() 函數明確排序：sort=field(name,min) asc 和 sort=field(name,max) desc。

您可以透過逗號分隔來指定多個排序順序，例如 inStock desc, price asc。當提供多個排序準則時，只有在第一個項目產生平手時才會使用第二個項目。如果存在第三個項目，只有在第一個和第二個項目都平手時才會使用。以此類推。

如果文件符合所有明確的排序條件，Solr 會使用每個文件的 Lucene 文件 ID 作為最終的平手打破規則。這個內部屬性在段落合併和文件更新期間可能會變更，這可能會導致非預期的結果排序變更。希望避免這種行為的使用者可以在唯一的或很少共享的欄位（例如 id）上定義額外的排序條件，以防止出現平手的情況 (例如，price desc,id asc)。

排序順序必須始終包含欄位名稱（或作為偽欄位的 score），後接空白 (在 URL 字串中會以 + 或 %20 跳脫)，然後是排序方向 (asc 或 desc，不區分大小寫)。

start 參數

選用

預設值：0

start 參數指定查詢結果集中的偏移量，並指示 Solr 從此偏移量開始顯示結果。

換句話說，將 start 參數設定為 0 以外的數字，例如 3，會導致 Solr 跳過前 3 筆記錄，並從偏移量所識別的文件開始。

您可以透過這種方式使用 start 參數進行分頁。例如，如果 rows 參數設定為 10，您可以透過將 start 設定為 0 來顯示三個連續的結果頁面，然後重新發出相同的查詢並將 start 設定為 10，然後再次發出查詢並將 start 設定為 20。

rows 參數

選用

預設值：10

rows 參數指定在回應中傳回的完整結果中文件數量。您可以使用 rows 參數來分頁查詢結果。

canCancel 參數

選用

預設值：false

canCancel 參數指定是否可以在執行期間使用任務管理介面取消查詢。

queryUUID 參數

選用

預設值：無

對於可取消的查詢，queryUUID 參數允許指定自訂 UUID 來識別查詢。否則，將會指派自動產生的 UUID。

當使用 queryUUID 時，確保 UUID 唯一性的責任在於呼叫者。如果當原始查詢 UUID 仍然作用中時重複使用查詢 UUID，則會導致第二個查詢擲回例外狀況。

建議您使用所有自訂 UUID 或完全依賴系統產生 UUID，以避免 UUID 衝突。

fq (篩選查詢) 參數

選用

預設值：無

fq 參數定義一個可以用來限制可傳回的文件超集的查詢，而不會影響分數。它對於加速複雜查詢非常有用，因為使用 fq 指定的查詢會獨立於主要查詢進行快取。當稍後的查詢使用相同的篩選器時，會發生快取命中，並且篩選結果會從快取中快速傳回。

當使用 fq 參數時，請記住以下幾點

  • fq 參數可以在查詢中指定多次。只有當文件位於參數每個執行個體所產生的文件集的交集中時，才會將文件包含在結果中。在下面的範例中，只有受歡迎程度大於 10 且部分為 0 的文件才會符合。

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

  • 篩選查詢可以包含複雜的布林查詢。上面的範例也可以寫成具有兩個強制子句的單一 fq，如下所示

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

  • 每個篩選查詢的文件集都會獨立快取。因此，關於先前的範例：如果這些子句經常一起出現，請使用包含兩個強制子句的單一 fq，如果它們相對獨立，則使用兩個單獨的 fq 參數。（若要了解調整快取大小並確保篩選快取實際存在，請參閱快取。）

  • 也可以在 fq 內部使用 filter(條件) 語法，個別快取子句，並且（除其他外）實現快取篩選查詢的聯集。

  • 與所有參數一樣：URL 中的特殊字元需要正確跳脫並編碼為十六進位值。您可以使用線上工具來協助您進行 URL 編碼。例如：http://meyerweb.com/eric/tools/dencoder/。

快取本地參數

Solr 預設會在篩選快取中快取篩選查詢的結果。若要停用它，請使用布林值 cache local param，例如 fq={!geofilt cache=false}…​。當您認為查詢不太可能重複時，請執行此操作。

未快取的篩選查詢也支援 cost 本地參數，以提供有關評估順序的提示。這可讓您在昂貴的未快取篩選器之前排序較不昂貴的未快取篩選器。在 Lucene 層，如果查詢有 TPI，則會對應到 TwoPhaseIterator.matchCost。

後置篩選器：對於成本非常高的篩選器，如果 cache=false且 cost>=100，且查詢實作 PostFilter 介面，則將從該查詢請求收集器，並在文件與主要查詢和所有其他篩選查詢相符後，使用收集器來篩選文件。可以有多個後置篩選器；它們也會依成本排序。

對於大多數查詢，預設行為為 cost=0，但某些類型的查詢（例如 {!frange}）預設為 cost=100，因為它們在用作 PostFilter 時最有效率。

這是一個 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 欄位，以及 dv_field_name 中的 docValues，即使它具有 useDocValuesAsStored="false"。

具有 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：傳回有關分數結果的偵錯資訊 (也稱為「說明」)。

    • 依預設，分數說明會以大型字串值傳回，使用換行符號和 Tab 縮排來表示結構和易讀性，但是可以指定額外的 debug.explain.structured=true 參數，以原生於 wt 所請求的回應格式的巢狀資料結構來傳回此資訊。

  • debug=all：傳回有關請求的所有可用偵錯資訊。另一種用法是 debug=true。

為了與舊版 Solr 回溯相容，可以使用 debugQuery=true 作為替代方法來表示 debug=all。

預設行為是不包含偵錯資訊。

explainOther 參數

選用

預設值：無

explainOther 參數指定 Lucene 查詢，以識別一組文件。如果包含此參數並將其設定為非空白值，則查詢將傳回偵錯資訊，以及與主要查詢 (由 q 參數指定) 相關的每個符合 Lucene 查詢的文件「說明資訊」。例如

q=supervillains&debug=all&explainOther=id:juggernaut

上面的查詢可讓您檢查最符合文件的評分說明資訊，將其與符合 id:juggernaut 的文件的說明資訊進行比較，並判斷排名不如預期的原因。

此參數的預設值為空白，這會導致不傳回額外的「說明資訊」。

partialResults 參數

選用

預設值：true

當查詢執行達到限制時 (例如 timeAllowed 或 cpuAllowed)，此參數會控制 Solr 的行為。

當此參數設定為 true (預設) 時，即使達到限制會終止進一步的查詢處理，Solr 仍然會嘗試傳回到目前為止收集的部分結果。這些結果可能會以不確定的方式不完整 (例如，只有一些符合的文件、沒有欄位的文件、遺失的刻面或樞紐、沒有拼字檢查結果等)。

當此參數設定為 false 時，達到限制將會產生例外狀況，且到目前為止收集的任何部分結果都會被捨棄。

timeAllowed 參數

選用

預設值：無

此參數指定允許搜尋完成的時間量 (以毫秒為單位)。如果此時間在搜尋完成之前過期，則會傳回任何部分結果，但諸如 numFound、刻面計數和結果統計資料等值可能不適用於整個結果集。如果過期，如果未將 omitHeader 設定為 true，則回應標頭包含一個名為 partialResults 的特殊旗標。當結合 cursorMark 使用 timeAllowed，且存在 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 篩選和分析組件會根據此參數放棄請求。

cpuAllowed 參數

選用

預設值：無

此參數指定允許搜尋完成的 CPU 時間量（以毫秒為單位）。與 timeAllowed 不同，此參數會監控執行查詢的執行緒的實際 CPU 使用率。相同的 CPU 使用率限制會套用至查詢協調器以及參與分散式搜尋的每個複本（儘管不太可能在查詢協調器中先達到此限制）。如果任何複本在本地超出允許的 CPU 時間，則整個分散式搜尋將會終止（透過取消對其他分片的請求）。

注意：相同的 CPU 限制會套用至分散式查詢處理中的每個階段。通常這涉及兩個或多個階段（例如，取得最上面的文件 ID、擷取它們的欄位，篩選、分組等可能需要其他階段）。例如，設定 cpuAllowed=500 會限制每個階段最多使用 500 毫秒的 CPU 時間，這表示查詢的 CPU 總使用量可能會達到 cpuAllowed 值的倍數，具體取決於階段的數量。

關於 timeAllowed 參數所列出的部分結果的所有其他考量因素也適用於此處。

segmentTerminateEarly 參數

選用

預設值：false

如果設定為 true，且此集合的 mergePolicyFactory 為 SortingMergePolicyFactory，其使用與此查詢指定的 sort 參數相容的 sort 選項，則 Solr 將能夠在每個區段的基礎上略過絕對不是目前結果頁面候選文件的文件。

如果使用提早終止，則 segmentTerminatedEarly 標頭將包含在 responseHeader 中。

與使用 timeAllowed 參數類似，當發生提早區段終止時，numFound、Facet 計數和結果 Stats 等值對於整個結果集可能不準確。

multiThreaded 參數

選用

預設值：false

此參數設定為 true 或 false，以控制 Solr 是否可以使用多個執行緒來滿足請求。true 值目前允許 IndexSearcher 並行搜尋 Lucene 的區段，並且可以在 solr.xml 檔案中自訂 indexSearcherExecutorThreads 值。如果存在 &segmentsTerminateEarly=true，則會忽略此參數（未來可能會啟用）。這是一個新的參數，被認為是實驗性的，並且可能會在後續版本中變更或移除。請在我們的郵件清單上分享您對它的回饋和經驗。

omitHeader 參數

選用

預設值：false

如果設定為 true，則 omitHeader 參數會從傳回的結果中排除標頭。標頭包含有關請求的資訊，例如完成所需的時間。

當使用 timeAllowed 和 shards.tolerant 等可能會導致部分結果的參數時，建議保留標頭，以便可以檢查 partialResults 標誌，並在部分結果的上下文中解讀 numFound、nextCursorMark、Facet 計數和結果 Stats 等值。

wt 參數

選用

預設值：json

wt 參數會選取 Solr 應使用的 Response Writer 來格式化查詢的回應。如需 Response Writer 的詳細說明，請參閱 Response Writers。

如果您未在查詢中定義 wt 參數，則將傳回 JSON 作為回應的格式。

logParamsList 參數

選用

預設值：所有參數

預設情況下，Solr 會記錄每個請求上的所有查詢參數。logParamsList 參數允許使用者指定應該記錄的參數名稱的逗號分隔「允許清單」，以覆寫此行為。這可能有助於控制僅記錄對您的組織重要的參數。

logParamsList 僅管理查詢參數的記錄。它不適用於在請求路徑、主體等中指定的參數。

例如，您可以這樣定義：

logParamsList=q,fq

並且只會記錄 'q' 和 'fq' 參數。

如果應不記錄任何參數，您可以將 logParamsList 作為空值傳送（即，logParamsList=）。

此參數不僅適用於查詢請求，也適用於對 Solr 的任何類型的請求。

echoParams 參數

選用

預設值：none 或 solrconfig.xml 中的預設值

echoParams 參數會控制回應標頭中包含哪些有關請求參數的資訊。

echoParams 參數接受下列值：

  • explicit：只有實際請求中包含的參數會新增至回應標頭的 params 區段中。

  • all：包含有助於查詢的所有請求參數。這將包含在 solrconfig.xml 中找到的請求處理常式定義中定義的所有內容，以及與請求一起包含的參數，再加上 _ 參數。如果參數同時包含在請求處理常式定義和請求中，則它將在回應標頭中多次出現。

  • none：完全移除回應標頭的 params 區段。回應中將不會提供有關請求參數的資訊。

預設值為 none，但許多 solrconfig.xml 處理常式將預設值設定為 explicit。以下是一個 JSON 回應的範例，其中 echoParams 參數設定在該 SearchHandler 的預設值中，因此它本身不會被回顯，而是只有請求本身的三個參數 - q、wt 和 indent：

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

如果傳送類似的請求，該請求將 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 略過要傳回回應的文件，它只會允許 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 的文件中傳回相同數量的文件。