配置 API

配置 API 允许使用类似 REST 的 API 调用来操作您的 solrconfig.xml 的各个方面。

此功能默认启用，并且在 SolrCloud、用户管理集群和单节点安装中工作方式类似。许多常用的编辑属性（例如缓存大小和提交设置）以及请求处理程序定义都可以使用此 API 进行更改。

使用此 API 时，不会更改 solrconfig.xml。相反，所有编辑的配置都存储在一个名为 configoverlay.json 的文件中。configoverlay.json 中的值会覆盖 solrconfig.xml 中的值。

配置 API 端点

所有配置 API 端点都是特定于集合的，这意味着此 API 一次可以检查或修改单个集合的配置。

  • collection/config：检索完整的有效配置，或修改配置。使用 GET 检索，使用 POST 执行命令。

  • collection/config/overlay：仅检索 configoverlay.json 中的详细信息，删除直接或通过默认值在 solrconfig.xml 中定义的任何选项。

  • collection/config/params：创建可以覆盖或代替 solrconfig.xml 中定义的参数的参数集。有关此端点的更多信息，请参阅 请求参数 API。

检索配置

可以通过向 /config 端点发送 GET 请求来检索所有配置项

  • V1 API

  • V2 API

https://127.0.0.1:8983/solr/techproducts/config
https://127.0.0.1:8983/api/collections/techproducts/config

响应将是合并 configoverlay.json 中的设置和 solrconfig.xml 中的设置后生成的 Solr 配置。

可以将返回的配置限制为顶级部分，例如 query、requestHandler 或 updateHandler。为此，请将该部分的名称附加到 config 端点。例如，要检索所有请求处理程序的配置

  • V1 API

  • V2 API

https://127.0.0.1:8983/solr/techproducts/config/requestHandler
https://127.0.0.1:8983/api/collections/techproducts/config/requestHandler

输出将是 solrconfig.xml 中定义的每个请求处理程序的详细信息，Solr 隐式定义的和使用此配置 API 存储在 configoverlay.json 中的定义的。要查看隐式请求处理程序的配置，请在请求中添加 expandParams=true。请参阅上面链接的隐式请求处理程序的文档，以获取使用此命令的示例。

可以作为路径参数添加的可用顶级部分是：query、requestHandler、searchComponent、updateHandler、queryResponseWriter、initParams、znodeVersion、listener、directoryFactory、indexConfig 和 codecFactory。

要进一步将请求限制为顶级部分中的单个组件，请使用 componentName 请求参数。

例如，要返回 /select 请求处理程序的配置

  • V1 API

  • V2 API

https://127.0.0.1:8983/solr/techproducts/config/requestHandler?componentName=/select
https://127.0.0.1:8983/api/collections/techproducts/config/requestHandler?componentName=/select

此命令的输出将类似于

{
  "config":{"requestHandler":{"/select":{
        "name": "/select",
        "class": "solr.SearchHandler",
        "defaults":{
          "echoParams": "explicit",
          "rows":10
        }}}}
}

限制为顶级部分内的对象的能力仅限于请求处理程序 (requestHandler)、搜索组件 (searchComponent) 和响应写入器 (queryResponseWriter)。

修改配置的命令

此 API 使用带有 POST 请求的特定命令来告知 Solr 将哪个属性或属性类型添加到 configoverlay.json 中或进行修改。这些命令与要添加或修改的属性或组件的数据一起传递。

用于修改的 Config API 命令分为 3 种类型，每种类型都会操作 solrconfig.xml 中的特定数据结构。这些类型是：

常用属性的命令

常用属性是在 Solr 实例中经常自定义的属性。它们使用两个命令进行操作：

  • set-property：设置已知的属性。属性的名称是预定义的，并且是固定的。如果已设置该属性，则此命令将覆盖之前的设置。

  • unset-property：删除使用 set-property 命令设置的属性。

可以使用 set-property 和 unset-property 配置的属性是预定义的，并在下面列出。这些属性的名称来自它们在 solrconfig.xml 中找到的 XML 路径。

更新处理程序设置

有关这些设置的默认值和可接受的值，请参见提交和事务日志。

  • updateHandler.autoCommit.maxDocs

  • updateHandler.autoCommit.maxTime

  • updateHandler.autoCommit.openSearcher

  • updateHandler.autoSoftCommit.maxDocs

  • updateHandler.autoSoftCommit.maxTime

  • updateHandler.commitWithin.softCommit

查询设置

有关这些设置的默认值和可接受的值，请参见缓存和查询预热。

缓存和缓存大小

  • query.filterCache.class

  • query.filterCache.size

  • query.filterCache.initialSize

  • query.filterCache.autowarmCount

  • query.filterCache.maxRamMB

  • query.filterCache.regenerator

  • query.queryResultCache.class

  • query.queryResultCache.size

  • query.queryResultCache.initialSize

  • query.queryResultCache.autowarmCount

  • query.queryResultCache.maxRamMB

  • query.queryResultCache.regenerator

  • query.documentCache.class

  • query.documentCache.size

  • query.documentCache.initialSize

  • query.documentCache.autowarmCount

  • query.documentCache.regenerator

  • query.fieldValueCache.class

  • query.fieldValueCache.size

  • query.fieldValueCache.initialSize

  • query.fieldValueCache.autowarmCount

  • query.fieldValueCache.regenerator

查询大小和预热

  • query.maxBooleanClauses

  • query.enableLazyFieldLoading

  • query.useFilterForSortedQuery

  • query.queryResultWindowSize

  • query.queryResultMaxDocCached

查询断路器

有关更多详细信息，请参见断路器

  • query.memEnabled

  • query.memThreshold

RequestDispatcher 设置

有关这些设置的默认值和可接受的值，请参见RequestDispatcher。

  • requestDispatcher.handleSelect

  • requestDispatcher.requestParsers.multipartUploadLimitInKB

  • requestDispatcher.requestParsers.formdataUploadLimitInKB

  • requestDispatcher.requestParsers.addHttpRequestToContext

常用属性示例

构造用于修改或添加这些属性之一的命令遵循以下模式：

{"set-property":{"<property>": "<value>"}}

增加 updateHandler.autoCommit.maxTime 的请求如下所示：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type: application/json' -d '{"set-property":{"updateHandler.autoCommit.maxTime":15000}}' https://127.0.0.1:8983/api/collections/techproducts/config

您可以使用 config/overlay 端点来验证该属性是否已添加到 configoverlay.json 中

  • V1 API

  • V2 API

curl https://127.0.0.1:8983/solr/techproducts/config/overlay?omitHeader=true
curl https://127.0.0.1:8983/api/collections/techproducts/config/overlay?omitHeader=true

输出：

{
  "overlay": {
    "znodeVersion": 1,
    "props": {
      "updateHandler": {
        "autoCommit": {"maxTime": 15000}
      }
}}}

要取消设置该属性：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type: application/json' -d '{"unset-property": "updateHandler.autoCommit.maxTime"}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type: application/json' -d '{"unset-property": "updateHandler.autoCommit.maxTime"}' https://127.0.0.1:8983/api/collections/techproducts/config

处理程序和组件的命令

可以使用特定于要修改的组件类型的命令来添加、更新和删除请求处理程序、搜索组件和其他类型的本地化 Solr 组件（例如，查询解析器、更新处理器等）。

在每种情况下，语法都类似：add-<_component-name_>、update-<_component-name_> 和 delete-<_component-name_>。命令名称不区分大小写，因此 Add-RequestHandler、ADD-REQUESTHANDLER 和 add-requesthandler 是等效的。

在每种情况下，add- 命令都会向 configoverlay.json 添加新的配置，这将覆盖 solrconfig.xml 中该组件的任何其他设置。

update- 命令会覆盖 configoverlay.json 中的现有设置。

delete- 命令会从 configoverlay.json 中删除该设置。

如果从 configoverlay.json 中删除的设置恰好在 solrconfig.xml 中重复，则不会从 solrconfig.xml 中删除这些设置。

下面列出了可用的完整命令列表：

组件的基本命令

这些命令是最常用的命令：

  • add-requesthandler

  • update-requesthandler

  • delete-requesthandler

  • add-searchcomponent

  • update-searchcomponent

  • delete-searchcomponent

  • add-initparams

  • update-initparams

  • delete-initparams

  • add-queryresponsewriter

  • update-queryresponsewriter

  • delete-queryresponsewriter

组件的高级命令

这些命令允许向 Solr 注册更高级的自定义：

  • add-queryparser

  • update-queryparser

  • delete-queryparser

  • add-valuesourceparser

  • update-valuesourceparser

  • delete-valuesourceparser

  • add-transformer

  • update-transformer

  • delete-transformer

  • add-updateprocessor

  • update-updateprocessor

  • delete-updateprocessor

  • add-queryconverter

  • update-queryconverter

  • delete-queryconverter

  • add-listener

  • update-listener

  • delete-listener

  • add-expressible

  • update-expressible

  • delete-expressible

处理程序和组件命令示例

要创建请求处理程序，我们可以使用 add-requesthandler 命令

curl -X POST -H 'Content-type:application/json'  -d '{
  "add-requesthandler": {
    "name": "/mypath",
    "class": "solr.DumpRequestHandler",
    "defaults":{ "x": "y" ,"a": "b", "rows":10 },
    "useParams": "x"
  }
}' https://127.0.0.1:8983/solr/techproducts/config

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{
  "add-requesthandler": {
    "name": "/mypath",
    "class": "solr.DumpRequestHandler",
    "defaults": { "x": "y" ,"a": "b", "rows":10 },
    "useParams": "x"
  }
}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{
  "add-requesthandler": {
    "name": "/mypath",
    "class": "solr.DumpRequestHandler",
    "defaults": { "x": "y" ,"a": "b", "rows":10 },
    "useParams": "x"
  }
}' https://127.0.0.1:8983/api/collections/techproducts/config

调用新的请求处理程序以检查它是否已注册

$ curl https://127.0.0.1:8983/solr/techproducts/mypath?omitHeader=true

您应该看到以下输出：

{
  "params":{
    "indent": "true",
    "a": "b",
    "x": "y",
    "rows": "10"},
  "context":{
    "webapp": "/solr",
    "path": "/mypath",
    "httpMethod": "GET"}}

要更新请求处理程序，应使用 update-requesthandler 命令：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{
  "update-requesthandler": {
    "name": "/mypath",
    "class": "solr.DumpRequestHandler",
    "defaults": {"x": "new value for X", "rows": "20"},
    "useParams": "x"
  }
}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{
  "update-requesthandler": {
    "name": "/mypath",
    "class": "solr.DumpRequestHandler",
    "defaults": {"x": "new value for X", "rows": "20"},
    "useParams": "x"
  }
}' https://127.0.0.1:8983/api/collections/techproducts/config

作为第二个示例，我们将创建另一个请求处理程序，这次将“terms”组件作为定义的一部分添加：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{
  "add-requesthandler": {
    "name": "/myterms",
    "class": "solr.SearchHandler",
    "defaults": {"terms": true, "distrib":false},
    "components": ["terms"]
  }
}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{
  "add-requesthandler": {
    "name": "/myterms",
    "class": "solr.SearchHandler",
    "defaults": {"terms": true, "distrib":false},
    "components": ["terms"]
  }
}' https://127.0.0.1:8983/api/collections/techproducts/config

最后，我们将通过 delete-requesthandler 命令删除该请求处理程序：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{
  "delete-requesthandler": "/myterms"
}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{
  "delete-requesthandler": "/myterms"
}' https://127.0.0.1:8983/api/collections/techproducts/config

用户定义属性的命令

Solr 允许用户使用占位符格式 ${variable_name:default_val} 对 solrconfig.xml 进行模板化。您可以使用系统属性来设置值，例如 -Dvariable_name= my_customvalue。可以使用以下命令在运行时实现相同的目的：

  • set-user-property：设置用户定义的属性。如果已设置该属性，则此命令将覆盖之前的设置。

  • unset-user-property：删除用户定义的属性。

请求的结构与其他使用其他命令的请求的结构类似，格式为 "command":{"variable_name": "property_value"}。如果需要，您可以一次添加多个变量。

有关用户定义属性的更多信息，请参阅core.properties 中的用户定义属性部分。

另请参阅下面的创建和更新用户定义的属性部分，了解如何使用此类命令的示例。

创建和更新用户定义的属性

此命令设置用户属性：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{"set-user-property": {"variable_name": "some_value"}}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{"set-user-property": {"variable_name": "some_value"}}' https://127.0.0.1:8983/api/collections/techproducts/config

同样，我们可以使用 /config/overlay 端点来验证是否已进行更改

  • V1 API

  • V2 API

curl https://127.0.0.1:8983/solr/techproducts/config/overlay?omitHeader=true
curl https://127.0.0.1:8983/api/collections/techproducts/config/overlay?omitHeader=true

我们希望看到如下输出：

{"overlay":{
   "znodeVersion":5,
   "userProps":{
     "variable_name": "some_value"}}
}

要取消设置该变量，请发出如下命令：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{"unset-user-property": "variable_name"}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{"unset-user-property": "variable_name"}' https://127.0.0.1:8983/api/collections/techproducts/config

updateRequestProcessorChain 元素

Config API 不允许您创建或编辑 updateRequestProcessorChain 元素。但是，可以创建 updateProcessor 条目并通过名称使用它们来创建链。

例如：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{"add-updateprocessor":
  {"name": "firstFld",
  "class": "solr.FirstFieldValueUpdateProcessorFactory",
  "fieldName": "test_s"}
}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{"add-updateprocessor":
  {"name": "firstFld",
  "class": "solr.FirstFieldValueUpdateProcessorFactory",
  "fieldName": "test_s"}
}' https://127.0.0.1:8983/api/collections/techproducts/config

您可以通过在 updateRequestProcessorChain 中为名为 processor=firstFld 的特定更新处理器添加参数，在请求中直接使用它。

如何将 solrconfig.xml 属性映射到 JSON

通过使用此 API，您将生成 solrconfig.xml 中定义的属性的 JSON 表示形式。要了解如何使用 API 表示属性，让我们来看几个示例。

以下是请求处理程序在 solrconfig.xml 中的外观：

<requestHandler name="/query" class="solr.SearchHandler">
  <lst name="defaults">
    <str name="echoParams">explicit</str>
    <int name="rows">10</str>
  </lst>
</requestHandler>

使用 Config API 定义的同一请求处理程序如下所示：

{
  "add-requesthandler":{
    "name": "/query",
    "class": "solr.SearchHandler",
    "defaults":{
      "echoParams": "explicit",
      "rows": 10
    }
  }
}

solrconfig.xml 中的 QueryElevationComponent 搜索组件如下所示：

<searchComponent name="elevator" class="solr.QueryElevationComponent" >
  <str name="queryFieldType">string</str>
  <str name="config-file">elevate.xml</str>
</searchComponent>

使用 Config API 的同一搜索组件如下：

{
  "add-searchcomponent":{
    "name": "elevator",
    "class": "solr.QueryElevationComponent",
    "queryFieldType": "string",
    "config-file": "elevate.xml"
  }
}

使用 Config API 删除搜索组件：

{
  "delete-searchcomponent": "elevator"
}

一个简单的突出显示器在 solrconfig.xml 中如下所示（为了节省空间，已截断示例）：

<searchComponent class="solr.HighlightComponent" name="highlight">
    <highlighting>
      <fragmenter name="gap"
                  default="true"
                  class="solr.highlight.GapFragmenter">
        <lst name="defaults">
          <int name="hl.fragsize">100</int>
        </lst>
      </fragmenter>

      <formatter name="html"
                 default="true"
                 class="solr.highlight.HtmlFormatter">
        <lst name="defaults">
          <str name="hl.simple.pre"><![CDATA[<em>]]></str>
          <str name="hl.simple.post"><![CDATA[</em>]]></str>
        </lst>
      </formatter>

      <encoder name="html" class="solr.highlight.HtmlEncoder" />
...
    </highlighting>
</searchComponent>

使用 Config API 的同一突出显示器如下：

{
    "add-searchcomponent": {
        "name": "highlight",
        "class": "solr.HighlightComponent",
        "": {
            "gap": {
                "default": "true",
                "name": "gap",
                "class": "solr.highlight.GapFragmenter",
                "defaults": {
                    "hl.fragsize": 100
                }
            }
        },
        "html": [{
            "default": "true",
            "name": "html",
            "class": "solr.highlight.HtmlFormatter",
            "defaults": {
                "hl.simple.pre": "before-",
                "hl.simple.post": "-after"
            }
        }, {
            "name": "html",
            "class": "solr.highlight.HtmlEncoder"
        }]
    }
}

在 solrconfig.xml 中设置 autoCommit 属性：

<autoCommit>
  <maxTime>15000</maxTime>
  <openSearcher>false</openSearcher>
</autoCommit>

使用 Config API 定义相同的属性：

{
  "set-property": {
    "updateHandler.autoCommit.maxTime":15000,
    "updateHandler.autoCommit.openSearcher":false
  }
}

为 Config API 命名组件

Config API 始终允许按名称更改任何组件的配置。但是，某些配置（例如 listener 或 initParams）在 solrconfig.xml 中不需要名称。为了能够 update 和 delete configoverlay.json 中的同一项，name 属性成为强制性的。

Config API 的工作原理

当使用 SolrCloud 时，每个核心都会监视 ZooKeeper 目录，以查找该核心使用的 configset。如果同一节点中有多个核心使用同一 configset，则仅使用一个 ZooKeeper 监视。

提示

在用户管理的集群或单节点安装中，没有监视（因为 ZooKeeper 未运行）。

例如，如果核心使用了 configset "myconf"，则节点将监视 /configs/myconf。通过 API 执行的每个写入操作都会“触摸”该目录，并且会通知所有监视器。每个核心都会通过比较 znode 版本来检查架构文件、solrconfig.xml 或 configoverlay.json 是否已被修改。如果任何一个被修改，则会重新加载核心。

如果修改了 params.json，则只会更新 params 对象，而不会重新加载核心（有关 params.json 的更多信息，请参阅请求参数 API）。

空命令

如果将空命令发送到 /config 端点，则将在此 configset 中对所有核心触发监视。例如：

  • V1 API

  • V2 API

curl -X POST -H 'Content-type:application/json' -d '{}' https://127.0.0.1:8983/solr/techproducts/config
curl -X POST -H 'Content-type:application/json' -d '{}' https://127.0.0.1:8983/api/collections/techproducts/config

直接编辑任何文件而不“触摸”该目录将不会使其对所有节点可见。

组件可以通过使用 SolrCore#registerConfListener() 注册侦听器来监视 configset “触摸”事件。

侦听配置更改

任何组件都可以使用以下命令注册侦听器：

SolrCore#addConfListener(Runnable listener)

以接收配置更改通知。如果修改的文件导致核心重新加载（即 configoverlay.xml 或架构），则此操作不是很有用。组件可以使用它来重新加载它们感兴趣的文件。