使用搜索应用程序客户端构建搜索体验
编辑使用搜索应用程序客户端构建搜索体验编辑
本文档是如何使用 搜索应用程序 和 搜索应用程序客户端 构建搜索体验的操作指南。该客户端是一个 JavaScript 库,旨在在浏览器中使用。您需要将此库集成到您的 Web 应用程序中,以简化对搜索应用程序的查询。
目标编辑
本指南假设您想构建一个具有以下搜索功能的 Web 应用程序
- 具有自定义相关性的搜索栏和结果
- 控制结果的呈现方式,例如包含/排除字段和突出显示匹配的词条
- UI 控件,例如分面、过滤器、排序、分页
您可以将搜索应用程序视为持久保存对 Elasticsearch 所做更改的“服务器端”。您的 Web 应用程序充当查询搜索应用程序的“客户端”。您需要同时编辑搜索应用程序和 Web 应用程序才能完成实现。
先决条件编辑
要遵循本指南,您需要
-
一个 Elastic 部署,满足运行搜索应用程序的 先决条件。
- 如果您没有 Elastic 部署,请在 Elastic Cloud 上开始免费试用。
-
一个 搜索应用程序。
- 一个 Web 应用程序,用于使用 搜索应用程序客户端 查询您的搜索应用程序。
安装和配置客户端编辑
安装客户端编辑
使用 npm、yarn 或 CDN 安装 客户端。
选项 1:使用包管理器
要使用 npm 安装客户端,请运行以下命令
npm install @elastic/search-application-client
要使用 yarn 安装客户端,请运行以下命令
yarn add @elastic/search-application-client
选项 2:将 CDN 与 HTML <script>
标签一起使用
或者,您可以使用 CDN 安装客户端。将以下 <script>
标签添加到您的 Web 应用程序的 HTML 中
<script src="https://cdn.jsdelivr.net.cn/npm/@elastic/search-application-client@latest"></script>
导入和初始化客户端编辑
安装后,您可以将客户端导入您的 Web 应用程序。您需要以下信息来初始化客户端
- 搜索应用程序的 名称
- 搜索应用程序的 URL 端点
- 搜索应用程序的 API 密钥
在 Kibana UI 的 连接 页面上找到此信息。
选项 1:使用 JavaScript 模块编辑
使用以下导入语句
import SearchApplicationClient from '@elastic/search-application-client';
使用您的部署详细信息配置客户端以开始发出搜索请求。您可以在 Kibana UI 的 连接 页面上生成 API 密钥。转到 搜索 > 搜索应用程序 > <MY_SEARCH_APPLICATION> > 连接。您会发现以下信息已预先填充,用于初始化客户端
import Client from '@elastic/search-application-client' const request = Client( 'my-search-application', // search application name 'url-from-connect-page', // url-host 'api-key-from-connect-page', // api-key { // optional configuration } )
配置完成后,您就可以使用 客户端 API 向您的搜索应用程序发出搜索请求,如下所示
const results = await request() .query('star wars') .search()
选项 2:使用 CDN编辑
或者,如果您使用的是 CDN,则可以使用以下语句导入客户端
<script> const Client = window['SearchApplicationClient']; </script>
使用您的部署详细信息配置客户端以开始发出搜索请求。您可以在 Kibana UI 的 连接 页面上生成 API 密钥。转到 搜索 > 搜索应用程序 > <MY_SEARCH_APPLICATION> > 连接。您会发现以下信息已预先填充,用于初始化客户端
<script> const request = Client( 'my-example-app', // search application name 'url-from-connect-page', // url-host 'api-key-from-connect-page', // api-key { // optional configuration } ) </script>
配置完成后,您就可以使用 客户端 API 向您的搜索应用程序发出搜索请求,如下所示
<script> const results = await request() .query('star wars') .search() </script>
使用搜索模板编辑
搜索应用程序客户端旨在与您创建的任何 搜索模板 一起使用。您将使用搜索应用程序 API 来创建和管理您的搜索模板。
在使用搜索应用程序 API 管理模板时,我们使用 Kibana 控制台 语法提供 API 示例。
下面是一个示例模板
PUT _application/search_application/my-example-app { "indices": ["my-example-app"], "template": { "script": { "lang": "mustache", "source": """ { "query": { "bool": { "must": [ {{#query}} { "query_string": { "query": "{{query}}", "search_fields": {{#toJson}}search_fields{{/toJson}} } } {{/query}} ] } } } """, "params": { "query": "", "search_fields": "" } } } }
这将允许您将所需的任何模板参数添加到模板中,然后在客户端请求中提供这些值。使用 addParameter
将实际值注入到模板参数中。
例如,像这样为 search_fields
传递值
const results = await request() .query('star wars') // requires the template to use query parameter .addParameter('search_fields', ['title', 'description']) .search()
示例模板编辑
我们建议从客户端存储库中提供的 样板模板 开始。 查看此脚本 以了解如何使用它。 dictionary
参数用于传入 JSON 模式定义,该定义描述了请求对象的结构和验证规则。此模式很重要,因为它限制了 Elasticsearch 查询中某些功能的使用。 查看模式。
本指南中的每个搜索功能都需要此模板中包含的一项功能。这些功能要求模板中存在特定参数
- 查询:
query
- 过滤器:
_es_filters
- 分面:
_es_filters
和_es_aggs
- 排序:
_es_sort_fields
- 分页:
from
和size
搜索功能编辑
我们将探讨搜索体验所需的所有基本知识。您将学习如何使用搜索应用程序实现它们,以及如何使用客户端查询它们。
有关可用方法及其参数的信息,请参阅 客户端存储库。
自定义相关性编辑
我们的简单模板使用 query_string
在所有字段中搜索,但这可能不适合您的用例。您可以更新模板以提供更好的相关性召回率。
在下面的示例中,我们对模板使用 multi-match
查询,其中 best_fields
和 phrase_prefix
查询针对不同的搜索字段。
PUT _application/search_application/my-example-app { "indices": ["example-index"], "template": { "script": { "lang": "mustache", "source": """ { "query": { "bool": { "must": [ {{#query}} { "multi_match" : { "query": "{{query}}", "fields": [ "title^4", "plot", "actors", "directors" ] } }, { "multi_match" : { "query": "{{query}}", "type": "phrase_prefix", "fields": [ "title^4", "plot"] } }, {{/query}} ], "filter": {{#toJson}}_es_filters{{/toJson}} } }, "aggs": {{#toJson}}_es_aggs{{/toJson}}, "from": {{from}}, "size": {{size}}, "sort": {{#toJson}}_es_sort_fields{{/toJson}} } """, "params": { "query": "", "_es_filters": {}, "_es_aggs": {}, "_es_sort_fields": {}, "size": 10, "from": 0 }, "dictionary": { // add dictionary restricting // _es_filters, _es_sort_fields & _es_aggs params // Use example provided in repo: https://github.com/elastic/search-application-client/blob/main/bin/request_schema.json } } } }
请参阅以获取不同类型查询的示例,包括文本搜索、kNN 搜索、ELSER 搜索、使用 RRF 的混合搜索等的组合。
用例:我想动态调整搜索字段
如果您需要在查询请求时调整 search_fields
,您可以向模板添加一个新参数(例如:search_fields
),并使用 addParameter
方法将字段提供给模板。
用例:我想根据与用户的特定距离来提升结果
您可以添加其他模板参数以发送用户的地理坐标。然后使用 function_score
来提升与用户特定 geo_distance
匹配的文档。
结果字段编辑
默认情况下,所有字段都在 _source
字段中返回。要限制返回的字段,请在模板中指定字段。
PUT _application/search_application/my-example-app { "indices": ["example-index"], "template": { "script": { "lang": "mustache", "source": """ { "query": { "bool": { "must": [ {{#query}} // ... {{/query}} ], "filter": {{#toJson}}_es_filters{{/toJson}} } }, "_source": { "includes": ["title", "plot"] }, "aggs": {{#toJson}}_es_aggs{{/toJson}}, "from": {{from}}, "size": {{size}}, "sort": {{#toJson}}_es_sort_fields{{/toJson}} } """, "params": { "query": "", "_es_filters": {}, "_es_aggs": {}, "_es_sort_fields": {}, "size": 10, "from": 0 }, "dictionary": { // add dictionary restricting _es_filters and _es_aggs params // Use the dictionary example provided in repo: https://github.com/elastic/search-application-client/blob/main/bin/request_schema.json } } } }
用例:我想动态调整结果字段
如果您需要在查询请求时调整返回的字段,您可以向模板添加一个新参数(例如:result_fields
),并使用 addParameter
方法将字段提供给模板。
突出显示和片段编辑
突出显示支持很容易添加到模板中。使用 突出显示 API,您可以指定要为匹配项突出显示哪些字段。
在以下示例中,我们将 title
和 plot
指定为突出显示的字段。与 plot
(可变且往往更长)相比,title
的值长度通常较短。
我们将标题指定为 fragment_size
为 0
,以便在有突出显示时返回所有文本。我们将图指定为 fragment_size
为 200
,其中每个突出显示的片段最多为 200 个字符。
PUT _application/search_application/my-example-app { "indices": ["example-index"], "template": { "script": { "lang": "mustache", "source": """ { "query": { "bool": { "must": [ {{#query}} // ... {{/query}} ], "filter": {{#toJson}}_es_filters{{/toJson}} } }, "_source": { "includes": ["title", "plot"] }, "highlight": { "fields": { "title": { "fragment_size": 0 }, "plot": { "fragment_size": 200 } } }, "aggs": {{#toJson}}_es_aggs{{/toJson}}, "from": {{from}}, "size": {{size}}, "sort": {{#toJson}}_es_sort_fields{{/toJson}} } """, "params": { "query": "", "_es_filters": {}, "_es_aggs": {}, "_es_sort_fields": {}, "size": 10, "from": 0 }, "dictionary": { // add dictionary restricting _es_filters and _es_aggs params // Use the dictionary example provided in repo: https://github.com/elastic/search-application-client/blob/main/bin/request_schema.json } } } }
如果找到匹配项,则会返回带有高亮字段的结果。例如:
{ "hits": [ { "_index": "movies", "_type": "_doc", "_id": "1", "_score": 0.2876821, "_source": { "title": "The Great Gatsby", "plot": "The Great Gatsby is a novel by F. Scott Fitzgerald that follows the story of Jay Gatsby, a wealthy and mysterious man, as he tries to win back the love of his life, Daisy Buchanan." }, "highlight": { "title": ["The Great <em>Gatsby</em>"], "plot": [ "The Great <em>Gatsby</em> is a novel by F. Scott Fitzgerald that follows the story of <em>Jay</em> <em>Gatsby</em>, a wealthy and mysterious man, as he tries to win back the love of his life, Daisy Buchanan." ] } } ] }
高亮助手编辑
在前端显示字段时,您需要先确定该字段是否具有高亮显示。为了简化此操作,我们提供了一个助手。
import Client, { Highlight } from '@elastic/search-application-client' // example React component const ResultsList = ({ hits } ) => { return hits.map((hit) => ( <div className="result"> <div className="title">{Highlight(hit, "title")}</div> <div className="description">{Highlight(hit, "plot")}</div> </div> )) }
分页编辑
要使用分页,请设置页码和页面大小。默认情况下,页面大小为 10。size
和 from
参数允许您控制响应中返回的页面和命中次数。
我们可以使用客户端的 setSize
和 setFrom
方法来实现。
// page 1 const results = await request() .setSize(20) .setFrom(0) .search() // page 2 const results = await request() .setSize(20) .setFrom(20) .search()
排序编辑
要使用排序,请指定字段名称和排序顺序,或传递 _score
以按相关性排序。需要在搜索模板中使用 _es_sort_fields_fields
参数。请参阅我们的示例模板以了解如何使用它。
默认情况下,结果将按分数顺序排序。如果需要按分数以外的字段排序,请将 setSort
方法与对象数组一起使用。
const results = await request() .setSort([{ year: 'asc' }, '_score']) .search()
过滤编辑
搜索应用程序客户端还支持过滤器和分面。要使用它们,您需要添加两个参数:
-
_es_filters
-
_es_aggs
请参阅我们的示例模板以了解如何使用它们。
基本过滤编辑
使用配置为使用过滤器的模板,使用 setFilter
方法将过滤器添加到查询中。
样板模板架构仅支持 term、range、match、nested、geo_bounding_box 和 geo_distance 过滤器。如果需要使用特定子句,则可以更新模板架构。
以下是使用 setFilter
的示例。
// return only "star wars" movies that are rated PG const results = await request() .query('star wars') .setFilter({ term: { 'rated.enum': 'PG', }, }) .search()
分面编辑
客户端支持使用结果配置分面的功能。在客户端初始化调用中指定分面。例如,假设我们要为演员、导演和 IMDB 评级添加分面。
const request = Client( 'my-example-app', // search application name 'https://d1bd36862ce54c7b903e2aacd4cd7f0a.us-east4.gcp.elastic-cloud.com:443', // api-host 'api-key-from-connect-page', // api-key { facets: { actors: { type: 'terms', field: 'actors.keyword', disjunctive: true, }, directors: { type: 'terms', field: 'director.keyword', size: 20, disjunctive: true, }, imdbrating: { type: 'stats', field: 'imdbrating', }, }, } )
在 Elasticsearch 中,keyword
类型用于需要以其确切的、未修改的形式进行搜索的字段。这意味着这些查询区分大小写。我们将此类型用于分面,因为分面需要根据确切的值或术语聚合并过滤数据。
使用 addFacetFilter
方法将分面添加到查询中。
在以下示例中,我们只想返回以下电影:
- 由哈里森·福特主演
- 由乔治·卢卡斯或雷德利·斯科特执导
- IMBD 评级高于 7.5
const results = await request() .addFacetFilter('actors', 'Harrison Ford') .addFacetFilter('directors', 'George Lucas') .addFacetFilter('directors', 'Ridley Scott') .addFacetFilter('imdbrating', { gte: 7.5, }) .search()
您可以访问结果中的分面:
{ "took": 1, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 2, "relation": "eq" }, "max_score": 0, "hits": [ { "_index": "imdb_movies", "_id": "tt0076759", "_score": 0, "_source": { "title": "Star Wars: Episode IV - A New Hope", "actors": [ "Mark Hamill", "Harrison Ford", "Carrie Fisher", "Peter Cushing" ], "plot": "Luke Skywalker joins forces with a Jedi Knight, a cocky pilot, a wookiee and two droids to save the universe from the Empire's world-destroying battle-station, while also attempting to rescue Princess Leia from the evil Darth Vader.", "poster": "https://s3-eu-west-1.amazonaws.com/imdbimages/images/MV5BMTU4NTczODkwM15BMl5BanBnXkFtZTcwMzEyMTIyMw@@._V1_SX300.jpg" } }, { "_index": "imdb_movies", "_id": "tt0083658", "_score": 0, "_source": { "title": "Blade Runner", "actors": [ "Harrison Ford", "Rutger Hauer", "Sean Young", "Edward James Olmos" ], "plot": "Deckard, a blade runner, has to track down and terminate 4 replicants who hijacked a ship in space and have returned to Earth seeking their maker.", "poster": "https://s3-eu-west-1.amazonaws.com/imdbimages/images/MV5BMTA4MDQxNTk2NDheQTJeQWpwZ15BbWU3MDE2NjIyODk@._V1_SX300.jpg" } } ] }, "aggregations": {}, "facets": [ { "name": "imdbrating_facet", "stats": { "min": 8.300000190734863, "max": 8.800000190734863, "avg": 8.550000190734863, "sum": 17.100000381469727, "count": 2 } }, { "name": "actors_facet", "entries": [ { "value": "Harrison Ford", "count": 2 }, { "value": "Carrie Fisher", "count": 1 }, { "value": "Edward James Olmos", "count": 1 }, { "value": "Mark Hamill", "count": 1 }, { "value": "Peter Cushing", "count": 1 }, { "value": "Rutger Hauer", "count": 1 }, { "value": "Sean Young", "count": 1 } ] }, { "name": "directors_facet", "entries": [ { "value": "Steven Spielberg", "count": 3 }, { "value": "Andrew Davis", "count": 1 }, { "value": "George Lucas", "count": 1 }, { "value": "Irvin Kershner", "count": 1 }, { "value": "Richard Marquand", "count": 1 }, { "value": "Ridley Scott", "count": 1 } ] } ] }