搜索参数 #

参数概述 #

Algolia搜索API提供了丰富的参数来控制搜索行为和结果。

基本搜索 #

javascript 
const results = await index.search('query', {
  // 各种搜索参数
});

基础参数 #

query #

搜索关键词：

javascript 
index.search({
  query: 'iphone'
});

// 简写形式
index.search('iphone');

hitsPerPage #

每页返回的结果数：

javascript 
index.search('iphone', {
  hitsPerPage: 20  // 默认20
});

page #

页码（从0开始）：

javascript 
index.search('iphone', {
  page: 0,         // 第一页
  hitsPerPage: 20
});

offset / length #

替代分页的偏移量方式：

javascript 
index.search('iphone', {
  offset: 40,  // 跳过前40条
  length: 20   // 获取20条
});

过滤参数 #

filters #

过滤条件：

javascript 
// 单条件
filters: 'brand:Apple'

// 多条件AND
filters: 'brand:Apple AND price < 1000'

// 多条件OR
filters: 'brand:Apple OR brand:Samsung'

// 组合条件
filters: '(brand:Apple OR brand:Samsung) AND price < 1000'

// 布尔条件
filters: 'inStock:true'

// 数组条件
filters: 'tags:phone'

过滤语法 #

操作符 说明 示例
: 等于 brand:Apple
!= 不等于 brand != Apple
< 小于 price < 1000
<= 小于等于 price <= 1000
> 大于 rating > 4
>= 大于等于 rating >= 4
AND 与 a AND b
OR 或 a OR b
NOT 非 NOT a

facetFilters #

分面过滤：

javascript 
// 单个分面
facetFilters: ['brand:Apple']

// 多个分面（AND关系）
facetFilters: ['brand:Apple', 'category:Phones']

// 同一分面多选（OR关系）
facetFilters: [['brand:Apple', 'brand:Samsung']]

// 组合使用
facetFilters: [
  ['brand:Apple', 'brand:Samsung'],
  'category:Phones',
  'inStock:true'
]

numericFilters #

数值过滤：

javascript 
numericFilters: [
  'price >= 500',
  'price <= 1000',
  'rating > 4'
];

tagFilters #

标签过滤：

javascript 
tagFilters: ['phone', '5g'];  // AND关系

tagFilters: [['phone', 'tablet']];  // OR关系

分面参数 #

facets #

返回分面统计：

javascript 
index.search('iphone', {
  facets: ['brand', 'category', 'price']
});

// 返回结果包含
{
  "facets": {
    "brand": {
      "Apple": 150,
      "Samsung": 80
    },
    "category": {
      "Phones": 200,
      "Tablets": 30
    }
  }
}

maxValuesPerFacet #

每个分面返回的最大值数量：

javascript 
index.search('iphone', {
  facets: ['brand'],
  maxValuesPerFacet: 10  // 默认100
});

facetQuery #

分面搜索：

javascript 
// 搜索品牌分面中包含"Ap"的值
index.searchForFacetValues('brand', 'Ap');
// 返回: ["Apple", "Apex"]

高亮参数 #

attributesToHighlight #

设置高亮属性：

javascript 
index.search('iphone', {
  attributesToHighlight: ['name', 'description']
});

// 返回结果
{
  "hits": [{
    "name": "iPhone 15 Pro",
    "_highlightResult": {
      "name": {
        "value": "<em>iPhone</em> 15 Pro",
        "matchLevel": "full"
      }
    }
  }]
}

highlightPreTag / highlightPostTag #

自定义高亮标签：

javascript 
index.search('iphone', {
  attributesToHighlight: ['name'],
  highlightPreTag: '<mark>',
  highlightPostTag: '</mark>'
});

// 返回
{
  "_highlightResult": {
    "name": {
      "value": "<mark>iPhone</mark> 15 Pro"
    }
  }
}

代码片段参数 #

attributesToSnippet #

设置代码片段：

javascript 
index.search('chip', {
  attributesToSnippet: ['description:50']  // 最多50字符
});

// 返回结果
{
  "_snippetResult": {
    "description": {
      "value": "...latest iPhone with A17 <em>chip</em> that delivers..."
    }
  }
}

snippetEllipsisText #

自定义省略号：

javascript 
index.search('chip', {
  attributesToSnippet: ['description:50'],
  snippetEllipsisText: '…'
});

排序参数 #

sort #

按属性排序：

javascript 
// 需要先创建排序副本索引
index.search('iphone', {
  sort: ['price:asc']
});

aroundLatLng #

按地理位置排序：

javascript 
index.search('store', {
  aroundLatLng: '37.7749,-122.4194',  // 纬度,经度
  aroundRadius: 10000  // 10公里范围
});

aroundLatLngViaIP #

使用IP定位：

javascript 
index.search('store', {
  aroundLatLngViaIP: true,
  aroundRadius: 'all'  // 所有结果
});

搜索行为参数 #

typoTolerance #

拼写容错：

javascript 
// 启用（默认）
typoTolerance: true

// 禁用
typoTolerance: false

// 最小字符数
typoTolerance: 'min'

minWordSizefor1Typo / minWordSizefor2Typos #

拼写容错阈值：

javascript 
index.search('iphone', {
  minWordSizefor1Typo: 4,   // 4字符以上允许1个拼写错误
  minWordSizefor2Typos: 8   // 8字符以上允许2个拼写错误
});

ignorePlurals #

忽略复数形式：

javascript 
// 所有语言
ignorePlurals: true

// 特定语言
ignorePlurals: ['en', 'fr']

removeStopWords #

移除停用词：

javascript 
// 所有语言
removeStopWords: true

// 特定语言
removeStopWords: ['en', 'zh']

queryType #

查询类型：

javascript 
// prefixLast（默认）：最后一个词前缀匹配
queryType: 'prefixLast'
// "iphone pro" 匹配 "iphone pro..." 和 "iphone processor"

// prefixAll：所有词前缀匹配
queryType: 'prefixAll'
// "iphone pro" 匹配 "iphone pro..." 和 "professional iphone"

// prefixNone：精确匹配
queryType: 'prefixNone'
// "iphone pro" 只匹配包含 "iphone pro" 的记录

removeWordsIfNoResults #

无结果时移除词：

javascript 
// none（默认）：不移除
removeWordsIfNoResults: 'none'

// lastWords：移除最后的词
removeWordsIfNoResults: 'lastWords'

// firstWords：移除最前的词
removeWordsIfNoResults: 'firstWords'

// allOptional：所有词变为可选
removeWordsIfNoResults: 'allOptional'

optionalWords #

可选词：

javascript 
// 这些词不匹配也返回结果
index.search('iphone pro max', {
  optionalWords: ['pro', 'max']
});

高级参数 #

restrictSearchableAttributes #

限制搜索属性：

javascript 
// 只在name和brand中搜索
index.search('apple', {
  restrictSearchableAttributes: ['name', 'brand']
});

advancedSyntax #

高级语法：

javascript 
index.search('iphone', {
  advancedSyntax: true
});

// 支持的语法：
// "exact phrase" - 精确短语
// -exclude - 排除词
// +must - 必须包含

distinct #

去重：

javascript 
// 按brand去重，每个brand只返回1条
index.search('phone', {
  distinct: 1
});

// 需要在attributesForFaceting中设置
// attributesForFaceting: ['brand']

getRankingInfo #

获取排名信息：

javascript 
index.search('iphone', {
  getRankingInfo: true
});

// 返回
{
  "hits": [{
    "_rankingInfo": {
      "nbTypos": 0,
      "firstMatchedWord": 0,
      "proximityDistance": 1,
      "userScore": 100
    }
  }]
}

analytics #

搜索分析：

javascript 
index.search('iphone', {
  analytics: true,           // 启用分析（默认true）
  analyticsTags: ['mobile'], // 分析标签
  clickAnalytics: true       // 点击分析
});

personalizationImpact #

个性化影响程度：

javascript 
index.search('iphone', {
  enablePersonalization: true,
  personalizationImpact: 50  // 0-100，默认100
});

响应参数 #

attributesToRetrieve #

返回属性：

javascript 
// 只返回指定属性
index.search('iphone', {
  attributesToRetrieve: ['name', 'price', 'imageUrl']
});

responseFields #

响应字段：

javascript 
// 只返回指定字段
index.search('iphone', {
  responseFields: ['hits', 'nbHits', 'processingTimeMS']
});

参数组合示例 #

电商搜索 #

javascript 
index.search(query, {
  hitsPerPage: 20,
  page: page,
  
  filters: `inStock:true AND category:${category}`,
  
  facets: ['brand', 'category', 'price_range'],
  facetFilters: [
    `brand:${selectedBrand}`,
    `price_range:${selectedPriceRange}`
  ],
  
  attributesToHighlight: ['name', 'description'],
  attributesToSnippet: ['description:100'],
  
  attributesToRetrieve: [
    'name', 'price', 'imageUrl', 'brand', 'rating'
  ],
  
  typoTolerance: true,
  ignorePlurals: true,
  
  analytics: true,
  analyticsTags: ['ecommerce', 'mobile']
});

内容搜索 #

javascript 
index.search(query, {
  hitsPerPage: 10,
  
  filters: 'status:published',
  
  attributesToHighlight: ['title', 'content'],
  attributesToSnippet: ['content:200'],
  
  restrictSearchableAttributes: ['title', 'content', 'tags'],
  
  removeStopWords: ['en'],
  ignorePlurals: true,
  
  advancedSyntax: true,
  
  attributesToRetrieve: [
    'title', 'excerpt', 'author', 'publishedAt', 'url'
  ]
});

参数优先级 #

text 
搜索参数 > 索引设置 > 默认值

总结 #

搜索参数分类：

类别 参数
基础 query, hitsPerPage, page
过滤 filters, facetFilters, numericFilters
分面 facets, maxValuesPerFacet
高亮 attributesToHighlight, highlightPreTag
代码片段 attributesToSnippet, snippetEllipsisText
排序 sort, aroundLatLng
行为 typoTolerance, queryType, removeStopWords
高级 distinct, advancedSyntax, getRankingInfo

接下来，让我们学习 排名与相关性。

最后更新：2026-03-28