使用搜索应用程序客户端构建搜索体验

编辑

使用搜索应用程序客户端构建搜索体验编辑

本文档是如何使用 搜索应用程序搜索应用程序客户端 构建搜索体验的操作指南。该客户端是一个 JavaScript 库,旨在在浏览器中使用。您需要将此库集成到您的 Web 应用程序中,以简化对搜索应用程序的查询。

提供了一个 沙盒环境,用于测试和试验 search-application-client 库。如果您想在不设置自己的 Web 应用程序的情况下试用该客户端,请跳转到那里。

克隆 存储库 并按照 README 中的说明开始操作。

目标编辑

本指南假设您想构建一个具有以下搜索功能的 Web 应用程序

  • 具有自定义相关性的搜索栏和结果
  • 控制结果的呈现方式,例如包含/排除字段和突出显示匹配的词条
  • UI 控件,例如分面、过滤器、排序、分页

您可以将搜索应用程序视为持久保存对 Elasticsearch 所做更改的“服务器端”。您的 Web 应用程序充当查询搜索应用程序的“客户端”。您需要同时编辑搜索应用程序和 Web 应用程序才能完成实现。

先决条件编辑

要遵循本指南,您需要

  • 一个 Elastic 部署,满足运行搜索应用程序的 先决条件

    • 如果您没有 Elastic 部署,请在 Elastic Cloud 上开始免费试用。
  • 一个 搜索应用程序

    • Kibana UI 中创建和管理搜索应用程序,或使用 API
  • 一个 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
  • 分页:fromsize

搜索功能编辑

我们将探讨搜索体验所需的所有基本知识。您将学习如何使用搜索应用程序实现它们,以及如何使用客户端查询它们。

有关可用方法及其参数的信息,请参阅 客户端存储库

自定义相关性编辑

我们的简单模板使用 query_string 在所有字段中搜索,但这可能不适合您的用例。您可以更新模板以提供更好的相关性召回率。

在下面的示例中,我们对模板使用 multi-match 查询,其中 best_fieldsphrase_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,您可以指定要为匹配项突出显示哪些字段。

在以下示例中,我们将 titleplot 指定为突出显示的字段。与 plot(可变且往往更长)相比,title 的值长度通常较短。

我们将标题指定为 fragment_size0,以便在有突出显示时返回所有文本。我们将图指定为 fragment_size200,其中每个突出显示的片段最多为 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。sizefrom 参数允许您控制响应中返回的页面和命中次数。

我们可以使用客户端的 setSizesetFrom 方法来实现。

// 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
        }
      ]
    }
  ]
}