gatsby plugin meilisearch
v0.3.1 ?
一个基于 graphQL 查询将 Gatsby 内容索引到 Meilisearch 的插件
要了解 Meilisearch 及其工作原理，请参阅 Meilisearch 的文档。
要了解 Gatsby 及其工作原理，请参阅 Gatsby 的文档。
使用美丽搜索云，告别服务器部署和手动更新。开始 14 天免费试用！无需信用卡。
在您的 Gatsby 应用程序中，添加包：
使用npm ：
npm install gatsby-plugin-meilisearch用yarn ：
yarn add gatsby-plugin-meilisearch有很多简单的方法可以下载和运行Meilisearch实例。
例如，如果您使用 Docker：
docker pull getmeili/meilisearch:latest # Fetch the latest version of Meilisearch image from Docker Hub
docker run -it --rm -p 7700:7700 getmeili/meilisearch:latest meilisearch --master-key=masterKey使用此命令，您的Meilisearch实例host为http://localhost:7700 ，您的主密钥为masterKey
如果您没有正在运行的 Gatsby，您可以启动 [此项目中存在的 Playground](./playground/README.md) 或创建一个 Gatsby 项目。
如果您的应用程序尚未运行，请运行它：
gatsby develop现在您的 Gatsby 应用程序正在运行，您可以访问以下 URL：
http://localhost:8000/ Web 应用程序的 URL。http://localhost:8000/___graphql ：GraphiQL 工具的 URL，您可以在 Playground 上构建 graphQL 查询并请求它们。 现在您应该有一个正在运行的 Gatsby 应用程序，并且安装了gatsby-plugin-meilisearch和一个正在运行的 Meilisearch 实例。
让我们配置我们的插件以使其工作！在此示例中，我们将获取 Gatsby 网站每个页面的 URL，并将它们索引到 Meilisearch。
要使插件正常工作，请打开位于 Gatsby 项目根目录的gatsby-config.js配置文件。所有配置都发生在该文件中。
首先，您需要添加您的 Meilisearch 凭据。
凭证由以下部分组成：
host ：正在运行的 Meilisearch 实例的 url。api_key ： master密钥或具有在美丽搜索中添加文档权限的其他key 。有关权限和 API 密钥的更多信息，请参见此处。search以外权限的密钥。对于搜索，请使用key路由上可用的Default Search Key密钥，或创建仅具有搜索权限的自定义 API 密钥。
按以下方式在gatsby-config.js文件中添加凭据：
{
plugins : [
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
} ,
} ,
]
}如果您不知道自己的凭据是什么，请参阅本部分。
下一步是定义我们要在美丽搜索中添加哪些数据以及如何添加。这发生在indexes字段中。
indexes字段是一个数组，可以由多个索引对象组成。每个索引对象包含以下信息：
indexUid ：添加数据的索引的名称。
让我们将索引 uid 定义为pages_url 。在构建时， pages_url索引是在Meilisearch 内部创建的。
indexUid: ' pages_url '如果pages_url已经存在，它将被删除并在构建时重新创建
query ：GraphQL 查询获取要添加到 Meilisearch 中的数据
让我们提供 graphQL 查询来检索应用程序页面的 URL。
query : `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` ,执行此查询后，我们收到一个包含以下内容的data对象：
{
data : {
allSitePage : {
nodes : [
{
path : '/404/'
} ,
{
path : '/404.html'
} ,
{
path : '/'
}
]
}
}
} transformer ：将获取的数据转换为与美丽搜索兼容的格式。
现在我们已经通过query字段获取了数据，但还没有准备好发送到Meilisearch。
使用transformer函数，我们可以将获取的数据转换为兼容的格式。
获取数据的第一个问题是发送到Meilisearch的文档是嵌套的，而它们应该位于数组的根部。所以nodes的内容应该位于根。
{
data : {
allSitePages : {
nodes : [
{
'path' : '/404/'
} ,
]
}
}
}应该变成：
[
{
'path' : '/404/'
} ,
{
'path' : '/'
} ,
]第二个问题是美丽搜索中的每个文档都需要一个唯一的标识符，称为主键。
因此，每个文档都需要一个名为id的唯一字段。例如：
{
'id' : 1
'path' : '/404/'
} ,为此，我们需要使用转换器方法来创建最终兼容的对象数组：
{
transformer : data =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,
}在此函数中，我们映射data.allSitePage.nodes以返回可由 Meilisearch 索引的对象数组。我们添加一个id字段，因为 Meilisearch 需要它来进行索引。由于这里没有任何可用作id字段，因此我们使用数组中当前元素的索引。
如果您想了解有关这些选项（ indexUid 、 query和transformer ）的更多信息，请参阅索引选项
填写这些字段后，您的 Meilisearch 配置应如下所示：
plugins: [
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
indexes : [
{
indexUid : 'pages_url' ,
transformer : ( data ) =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,
query : `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` ,
} ,
] ,
} ,
} ,
] ;gatsby-plugin-meilisearch获取您的数据并将其添加到 Gatsby 构建上的 Meilisearch。
gatsby build构建完成后，终端中会显示一条消息，确认您的内容已成功编入索引：
success gatsby-plugin-meilisearch - x.xxxs - Documents added to Meilisearch如果您需要工具在您的应用程序上集成搜索体验，我们的工具可以帮助您：
在 gatsby-config.js 文件中，Meilisearch 插件接受以下选项：
host （必填） host字段是您的Meilisearch实例运行的地址。 gatsby-plugin-meilisearch需要它才能与您的 Meilisearch 实例通信并向其发送数据。
apiKey （可选）如果 Meilisearch 实例受密码保护，则apiKey字段包含 API 密钥。
skipIndexing （可选）此选项允许您构建网站而无需索引到 Meilisearch。默认为 false
batchSize （可选）每批应包含的文件数量。默认为 1000
settings （可选）如果您想将设置传递到您的Meilisearch实例，您可以在此处进行。了解有关美丽搜索设置的更多信息
indexes （必填） indexes字段是一个对象数组，每个对象代表如何将数据添加到特定索引
indexes中可以有一个或多个index对象，如果您想在不同索引中索引不同内容（或将多个不同数据索引到同一索引），这会很有用。
每个index对象应包含以下字段：
indexUid （必填）
这是您的 Meilisearch 索引的名称。这是必填字段，因为检索到的数据将添加到 Meilisearch 中。例如，如果您的indexUid是pages_url ，您的内容将被索引到Meilisearch的pages_url索引中。如果您提供的索引名称已存在，则该索引将被删除并重新创建。
例子：
indexUid: ' pages_url '您可以在我们的文档中了解有关索引的更多信息。
query （必填）
这是为了检索数据而执行的 graphQL 查询。根据您使用的插件，您的查询可能非常具体。如果您不确定您的查询，您可以使用 Gatsby 在开发模式下提供的 GraphiQL 工具（http://localhost:8000/___graphql）来帮助您构建它。
例子：
query: `
query MyQuery {
allSitePage {
nodes {
path
}
}
}
` ,您还可以检查我们的 Playground 的配置文件，以获取使用gatsby-plugin-mdx插件的 graphQL 查询示例。
transformer （必需）
这是一个在将获取的数据发送到Meilisearch 之前对其进行转换的函数。
执行 graphQL 查询后，会收到一个数据对象，其结构可能因项目而异，具体取决于您提供的查询。由于Meilisearch需要在每个文档的根部有一个唯一的标识符，并且它应该避免嵌套对象，因此您需要相应地转换您的数据对象。 transformer函数是执行此操作的正确位置。
例子：
transformer : data =>
data . allSitePage . nodes . map ( ( node , index ) => ( {
id : index ,
... node ,
} ) ) ,如果不使用transformer函数，数据将如下所示：
{
data : {
allSitePage : {
nodes : [
{
path : '/404/'
} ,
{
path : '/404.html'
} ,
{
path : '/'
}
]
}
}
}如上例所示使用transformer函数后，数据将如下所示，并准备好进行索引：
[
{
id : 0 ,
path : '/404/' ,
} ,
{
id : 1 ,
path : '/404.html' ,
} ,
{
id : 2 ,
path : '/' ,
} ,
] ;如果您想了解更多关于Meilisearch的文档结构，您可以在我们的文档中进行。
完整用法示例：
{
resolve : 'gatsby-plugin-meilisearch' ,
options : {
host : 'http://localhost:7700' ,
apiKey : 'masterKey' ,
skipIndexing : false ,
batchSize : 1000 ,
options : {
settings : {
searchableAttributes : [ "*" ] ,
} ,
} ,
indexes : [
{
indexUid : 'my_index' ,
transformer : ( ) => { } ,
query : ``
} ,
] ,
} 支持的 Gatsby 版本：
（此插件可能适用于较旧的 Gatsby 版本，但目前尚未测试或正式支持。）
支持的美丽搜索版本：
该软件包保证与Meilisearch v1.x版本兼容，但某些功能可能不存在。请检查问题以获取更多信息。
节点/NPM 版本：
我们建议始终使用最新版本的 Gatsby 来启动您的新项目。
我们非常欢迎任何新的贡献加入到这个项目中！
如果您想了解更多有关开发工作流程或想要做出贡献，请访问我们的贡献指南以获取详细说明！
