记录与字段 #

记录基础 #

什么是记录？ #

记录（Record）是Algolia索引中的基本数据单元，以JSON格式存储。每条记录代表一个可搜索的实体。

json 
{
  "objectID": "product-001",
  "name": "iPhone 15 Pro",
  "brand": "Apple",
  "price": 999,
  "inStock": true,
  "tags": ["phone", "5g", "apple"]
}

记录结构 #

text 
Record
├── objectID (必需)
├── 搜索属性 (searchableAttributes)
├── 分面属性 (attributesForFaceting)
├── 排名属性 (customRanking)
├── 展示属性 (用于前端显示)
└── 内部属性 (不参与搜索)

字段类型 #

基本类型 #

类型 示例 说明
字符串 "iPhone" 文本数据
数字 999 整数或浮点数
布尔 true true/false
数组 ["tag1", "tag2"] 值列表
对象 {"key": "value"} 嵌套结构
null null 空值

字符串字段 #

json 
{
  "name": "iPhone 15 Pro",
  "description": "Latest iPhone with A17 Pro chip",
  "sku": "IPHONE-15-PRO-256"
}

数字字段 #

json 
{
  "price": 999.99,
  "stock": 50,
  "rating": 4.8,
  "discount": 10
}

注意：数字字段可用于数值比较和排序：

javascript 
// 搜索时过滤
filters: 'price < 1000 AND stock > 0'

布尔字段 #

json 
{
  "inStock": true,
  "featured": false,
  "published": true
}

搜索时使用：

javascript 
filters: 'inStock:true AND featured:true'

数组字段 #

json 
{
  "tags": ["phone", "5g", "apple"],
  "colors": ["black", "white", "blue"],
  "sizes": [64, 128, 256]
}

搜索时匹配数组中任意元素：

javascript 
// 匹配包含"phone"的记录
filters: 'tags:phone'

// 匹配多个标签
filters: 'tags:phone OR tags:5g'

嵌套对象 #

嵌套结构 #

json 
{
  "objectID": "product-001",
  "name": "iPhone 15 Pro",
  "specs": {
    "display": "6.1 inch",
    "chip": "A17 Pro",
    "camera": {
      "main": "48MP",
      "front": "12MP"
    }
  },
  "dimensions": {
    "width": 70.6,
    "height": 146.6,
    "depth": 8.25
  }
}

访问嵌套属性 #

使用点号访问嵌套属性：

javascript 
// 设置可搜索属性
searchableAttributes: [
  'name',
  'specs.display',
  'specs.chip',
  'specs.camera.main'
]

// 过滤嵌套属性
filters: 'specs.dimensions.width < 75'

嵌套数组 #

json 
{
  "objectID": "product-001",
  "name": "iPhone 15 Pro",
  "variants": [
    { "color": "black", "price": 999, "stock": 50 },
    { "color": "white", "price": 999, "stock": 30 },
    { "color": "blue", "price": 1099, "stock": 20 }
  ]
}

字段设计原则 #

1. 扁平化优先 #

json 
// ❌ 不推荐：深层嵌套
{
  "product": {
    "info": {
      "details": {
        "name": "iPhone"
      }
    }
  }
}

// ✅ 推荐：扁平结构
{
  "name": "iPhone",
  "productName": "iPhone 15 Pro"
}

2. 预计算值 #

json 
// ❌ 不推荐：搜索时计算
{
  "price": 100,
  "discount": 10
}

// ✅ 推荐：预计算
{
  "price": 100,
  "discount": 10,
  "finalPrice": 90
}

3. 合理的属性数量 #

text 
推荐结构：
├── 核心属性 (5-10个) - 参与搜索和排名
├── 展示属性 (10-20个) - 用于前端展示
└── 辅助属性 (5-10个) - 用于过滤和排序

总属性数建议不超过50个

字段用途分类 #

可搜索属性 #

参与全文搜索的字段：

javascript 
searchableAttributes: [
  'name',           // 商品名称
  'description',    // 描述
  'brand',          // 品牌
  'category'        // 分类
]

分面属性 #

用于筛选和分类统计：

javascript 
attributesForFaceting: [
  'brand',          // 品牌筛选
  'category',       // 分类筛选
  'price',          // 价格区间
  'inStock'         // 库存状态
]

排名属性 #

用于自定义排序：

javascript 
customRanking: [
  'desc(rating)',     // 评分高的排前面
  'desc(popularity)', // 人气高的排前面
  'asc(price)'        // 价格低的排前面
]

展示属性 #

仅用于前端显示：

json 
{
  "name": "iPhone 15 Pro",
  "imageUrl": "https://example.com/iphone.jpg",
  "productUrl": "/products/iphone-15-pro",
  "description": "..."
}

隐藏属性 #

不返回给前端：

javascript 
unretrievableAttributes: [
  'internalId',
  'costPrice',
  'supplierInfo'
]

数据建模示例 #

电商商品 #

json 
{
  "objectID": "prod-001",
  
  "name": "iPhone 15 Pro 256GB",
  "description": "Apple iPhone 15 Pro with A17 Pro chip...",
  "brand": "Apple",
  "category": "Smartphones",
  "subcategory": "Flagship Phones",
  
  "price": 999,
  "originalPrice": 1099,
  "discount": 100,
  "currency": "USD",
  
  "rating": 4.8,
  "reviewCount": 1250,
  "popularity": 8500,
  "salesCount": 15000,
  
  "inStock": true,
  "stock": 50,
  
  "tags": ["phone", "5g", "apple", "flagship"],
  "colors": ["black", "white", "blue"],
  "storage": [128, 256, 512],
  
  "imageUrl": "https://example.com/iphone.jpg",
  "thumbnailUrl": "https://example.com/iphone-thumb.jpg",
  "productUrl": "/products/iphone-15-pro",
  
  "specs": {
    "display": "6.1 inch Super Retina XDR",
    "chip": "A17 Pro",
    "ram": "8GB",
    "battery": "3274 mAh"
  },
  
  "createdAt": 1709500800,
  "updatedAt": 1710432000
}

博客文章 #

json 
{
  "objectID": "post-001",
  
  "title": "Getting Started with Algolia",
  "content": "In this tutorial, we will learn...",
  "excerpt": "Learn the basics of Algolia search...",
  
  "author": {
    "name": "John Doe",
    "id": "user-123",
    "avatar": "https://example.com/avatar.jpg"
  },
  
  "category": "Technology",
  "tags": ["algolia", "search", "tutorial"],
  
  "status": "published",
  "featured": true,
  
  "viewCount": 5420,
  "likeCount": 320,
  "commentCount": 45,
  
  "publishedAt": 1710432000,
  "updatedAt": 1710518400,
  
  "url": "/blog/getting-started-with-algolia",
  "imageUrl": "https://example.com/post-image.jpg"
}

用户档案 #

json 
{
  "objectID": "user-001",
  
  "name": "John Doe",
  "email": "john@example.com",
  "username": "johndoe",
  
  "bio": "Software developer interested in...",
  "location": "San Francisco, CA",
  
  "skills": ["JavaScript", "Python", "React"],
  "interests": ["AI", "Web Development", "Open Source"],
  
  "followers": 1250,
  "following": 320,
  "posts": 45,
  
  "joinedAt": 1709500800,
  "lastActiveAt": 1710432000,
  
  "avatarUrl": "https://example.com/avatar.jpg",
  "profileUrl": "/users/johndoe"
}

字段命名规范 #

推荐命名 #

json 
{
  "objectID": "prod-001",        // 使用前缀区分类型
  "name": "...",                  // 小驼峰命名
  "imageUrl": "...",              // URL后缀
  "createdAt": 1234567890,        // 时间戳后缀
  "inStock": true,                // 布尔前缀
  "reviewCount": 100,             // 数量后缀
  "isFeatured": true              // 布尔前缀
}

避免的命名 #

json 
{
  "_id": "...",           // 避免下划线开头
  "name-en": "...",       // 避免连字符
  "NAME": "...",          // 避免全大写
  "name1": "...",         // 避免数字后缀
  "data": {...}           // 避免泛化名称
}

字段限制 #

限制项 值
记录大小 10KB（免费）/ 20KB（付费）
属性数量 最多1000个
属性名长度 最多100字符
数组元素 最多1000个
嵌套深度 建议≤3层

数据更新策略 #

全量更新 #

javascript 
// 替换整个记录
await index.saveObject({
  objectID: '1',
  name: 'Updated Name',
  price: 899
});

部分更新 #

javascript 
// 只更新指定字段
await index.partialUpdateObject({
  objectID: '1',
  price: 899,
  stock: 45
});

原子操作 #

javascript 
// 增量更新（原子操作）
await index.partialUpdateObject({
  objectID: '1',
  viewCount: { _operation: 'Increment', value: 1 }
});

支持的原子操作：

操作 说明
Increment 增加数值
Decrement 减少数值
Add 添加数组元素
Remove 移除数组元素
AddUnique 添加唯一元素

总结 #

记录与字段设计要点：

要点 说明
结构 JSON格式，objectID必需
类型 字符串、数字、布尔、数组、对象
设计 扁平化、预计算、合理数量
分类 搜索、分面、排名、展示、隐藏
命名 小驼峰、语义化、一致性

接下来，让我们学习 搜索参数。

最后更新：2026-03-28