文档

文档是由一个或多个字段组成的对象。每个字段包含一个属性及其关联的值。文档作为组织数据的容器，是 Meilisearch 数据库的基本构建单元。要搜索文档，必须首先将其添加到索引中。

如果两个索引包含完全相同的文档，它们之间不会共享任何内容。相反，这两个文档将被视为不同的文档。根据索引设置，这些文档可能有不同的大小。

​

结构

​

重要术语

• 文档(Document): 包含一个或多个字段数据的对象
• 字段(Field): 两个相关联的数据项组成的集合：属性和值
• 属性(Attribute): 字段的第一部分，作为其关联值的名称或描述
• 值(Value): 字段的第二部分，包含任何有效JSON类型的数据
• 主字段(Primary Field): 所有文档中必须包含的特殊字段，包含主键和文档标识符

​

字段

字段是由两个相互关联的数据项组成的集合：属性(attribute)和值(value)。文档由多个字段构成。

属性是一个区分大小写的字符串，作为字段的名称，用于存储、访问和描述数据。

字段的实际数据称为值。每个字段的数据类型由其值决定。所有值都必须是有效的JSON数据类型。

如果值是字符串，它**最多可包含65535个字符位置**。超过65535个字符限制的单词将被忽略。

如果字段包含对象(object)，Meilisearch在索引时会使用点标记法将其扁平化，并将对象的键和值提升到文档的根层级。这种扁平化表示只是中间形态——在搜索时您仍会获得原始结构。更多细节请参阅我们的专门指南。

通过排序规则，您可以决定哪些字段比其他字段更重要。例如，您可以设定较新的电影应该比较旧的电影相关性更高。您还可以指定某些字段为可显示字段或可搜索字段。

​

显示字段与可搜索字段

默认情况下，文档中的所有字段既会被显示也会被搜索。显示字段包含在每个匹配文档的返回结果中，而可搜索字段则用于匹配查询词。

您可以通过更新设置端点，或分别使用显示属性和可搜索属性的更新端点来修改此行为，使字段具备以下特性：

• 可搜索但不可见
• 可见但不可搜索
• 既不可见也不可搜索

在最后一种情况下，该字段在搜索过程中会被完全忽略。不过，它仍会被存储在文档中。

要了解更多信息，请参阅我们的显示与可搜索属性指南。

​

主字段

主字段是一个特殊字段，必须存在于所有文档中。它的属性是主键，其值是文档ID。如果您尝试索引一个文档时缺少主键或使用了错误的主键，将会导致错误且不会添加任何文档。

要了解更多信息，请参阅主键说明。

​

上传文档

默认情况下，Meilisearch 将所有有效载荷（包括文档上传）的大小限制为 100MB。您可以在运行时使用 http-payload-size-limit 选项来修改有效载荷大小限制。

Meilisearch 在索引文档时会消耗大量内存。随着批量大小的增加，请注意您的可用内存情况，因为这可能导致 Meilisearch 崩溃。

使用添加新文档端点时，请确保：

• 有效载荷格式正确。没有多余的逗号、不匹配的括号、缺失的引号等
• 所有文档都以数组形式发送，即使只有一个文档

​

数据集格式

Meilisearch 接受以下格式的数据集：

• JSON
• NDJSON
• CSV

​

JSON 格式

JSON 格式的文档是由花括号包裹的键值对对象。因此，所有适用于 JSON 对象格式的规则同样适用于 Meilisearch 文档。例如，属性必须是字符串，而值必须是有效的 JSON 数据类型。

Meilisearch 仅在接收到 application/json 内容类型头时才会接受 JSON 文档。

举例来说，假设您正在创建一个包含电影信息的索引。一个示例文档可能如下所示：

{
  "id": 1564,
  "title": "Kung Fu Panda",
  "genres": "Children's Animation",
  "release-year": 2008,
  "cast": [
    { "Jack Black": "Po" },
    { "Jackie Chan": "Monkey" }
  ]
}

在上面的示例中：

• "id", "title", "genres", "release-year" 和 "cast" 是属性
• 每个属性都关联一个值，例如 "Kung Fu Panda" 是 "title" 的值
• 文档包含一个主键属性和唯一文档 ID 作为其值："id": "1564"

​

NDJSON 格式

NDJSON 或 jsonlines 对象由多行组成，其中每一行都是有效的 JSON 文本，且每行以换行符分隔。任何适用于 NDJSON 格式的规则同样适用于 Meilisearch 文档。

Meilisearch 仅在接收到 application/x-ndjson 内容类型头时才会接受 NDJSON 文档。

与 JSON 相比，NDJSON 具有更好的写入性能，CPU 和内存消耗更低。它更易于验证，并且与 CSV 不同，可以处理嵌套结构。

上述 JSON 文档在 NDJSON 中会如下所示：

{ "id": 1564, "title": "Kung Fu Panda", "genres": "Children's Animation", "release-year": 2008, "cast": [{ "Jack Black": "Po" }, { "Jackie Chan": "Monkey" }] }

​

CSV 格式

CSV 文件通过分隔符将数据表示为一系列值。Meilisearch 接受 CSV 文档中的 string（字符串）、boolean（布尔值）和 number（数字）数据类型。如果未为属性指定数据类型，则默认为 string。空字段如 ,, 和 , , 将被视为 null。

默认情况下，Meilisearch 使用单个逗号 (,) 作为分隔符。可以通过 添加或更新文档 或 添加或替换文档 端点配合 csvDelimiter 查询参数来设置不同的分隔符。所有 适用于 CSV 格式化的规则 同样适用于 Meilisearch 文档。

只有当收到 text/csv 内容类型头时，Meilisearch 才会接受 CSV 文档。

与 JSON 相比，CSV 具有更好的写入性能，且 CPU 和内存消耗更低。

上述 JSON 文档在 CSV 中会呈现如下：

  "id:number","title:string","genres:string","release-year:number"
  "1564","Kung Fu Panda","Children's Animation","2008"

由于 CSV 不支持数组或嵌套对象，因此 cast 字段无法转换为 CSV 格式。

​

自动批处理

自动批处理将相似的连续操作合并为单个批次并一起处理，这能显著加快索引过程。

当以下条件满足时，Meilisearch 会对文档添加和删除等操作进行批处理：

• 针对同一个索引
• 操作是连续发生的

同一批次中的任务共享相同的 startedAt、finishedAt 和 duration 值。

如果某个任务因文档无效而失败，它将被从批次中移除，其余批次仍会正常处理。如果发生 internal 错误，整个批次将失败，其中的所有任务将共享相同的 error 对象。

​

自动批处理与任务取消

如果您要取消的任务属于某个批次，Meilisearch 会中断整个处理过程，丢弃所有进度，并取消该任务。然后，它会自动创建一个不包含已取消任务的新批次，并立即开始处理该批次。