Settings
Index settings control search behavior: synonyms, field weights, typo tolerance, and semantic search configuration. Settings are per-index and persisted to disk.
Get the current settings for an index.
Response 200 OK
{
"language": "en",
"synonyms": {
"shoes": ["sneakers", "kicks"],
"fast": ["quick", "rapid"]
},
"attribute_weights": {
"title": 3.0,
"description": 1.0
},
"typo_tolerance": {
"enabled": true,
"min_word_length_1_typo": 4,
"min_word_length_2_typos": 8
},
"price_ranges": [],
"semantic": {
"enabled": false,
"keyword_weight": 0.6,
"semantic_weight": 0.4
},
"enrichment": {
"enabled": false,
"provider": null,
"mode": "suggest",
"confidence_threshold": 0.8,
"batch_size": 100,
"categories": []
},
"scoring": {
"enabled": false,
"ranking_weight": 0.10,
"weights": {
"sales_count": 0.30,
"revenue": 0.20,
"ctr": 0.20,
"conversion_rate": 0.15,
"view_count": 0.10,
"recency": 0.05
}
}
}SDK
const settings = await idx.getSettings();
Update index settings. Provided fields are merged with existing settings.
All fields are optional. Only the fields you include will be updated. Omitted fields retain their current values.
Request body
| Parameter | Type | Description |
|---|---|---|
| language optional | string | Tokenization language code. See Language section below. |
| synonyms optional | object | Map of term to synonym arrays. See Synonyms section below. |
| attribute_weights optional | object | Map of field name to BM25 weight multiplier. |
| typo_tolerance optional | object | Typo tolerance configuration. See below. |
| price_ranges optional | object[] | Custom price facet ranges. See below. |
| semantic optional | object | Semantic/hybrid search configuration. See below. |
| enrichment optional | object | AI catalog enrichment configuration. See below. |
| scoring optional | object | Document scoring configuration. See below. |
curl -X PUT https://search.example.com/v1/indices/products/settings \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "synonyms": { "shoes": ["sneakers", "kicks"] }, "typo_tolerance": { "min_word_length_1_typo": 3 } }'
SDK
await idx.updateSettings({ synonyms: { shoes: ['sneakers', 'kicks'] }, typo_tolerance: { min_word_length_1_typo: 3 }, });
Response 200 OK
{ "status": "ok" }Language
Controls stemming, accent folding, and word segmentation for the index. The tokenizer is baked into the index schema at creation time — changing the language after indexing requires a full reindex to apply the new tokenizer to existing documents.
| Parameter | Type | Description |
|---|---|---|
| language optional | string | ISO 639-1 language code. Default: "en" |
Supported languages:
| Parameter | Type | Description |
|---|---|---|
| en optional | English — stemming | |
| es optional | Spanish — stemming + accent folding | |
| fr optional | French — stemming + accent folding | |
| de optional | German — stemming + accent folding | |
| pt optional | Portuguese — stemming + accent folding | |
| it optional | Italian — stemming + accent folding | |
| nl optional | Dutch — stemming + accent folding | |
| ja optional | Japanese — dictionary-based segmentation (IPADIC) | |
| zh optional | Chinese — word segmentation (jieba) | |
| ko optional | Korean — dictionary-based segmentation (ko-dic) |
European languages include accent folding, so cafe matches café and chateau matches château. CJK languages use dictionary-based tokenizers
that properly segment text without spaces.
curl -X PUT https://search.example.com/v1/indices/products/settings \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "language": "fr" }'
SDK
await idx.updateSettings({ language: 'fr' });
Synonyms
Map a term to an array of equivalent terms. When a user searches for any term in a synonym group, Skirre expands the query to include all synonyms.
{
"synonyms": {
"shoes": ["sneakers", "kicks", "footwear"],
"tv": ["television", "monitor"]
}
}See the Synonyms guide for best practices and advanced patterns.
Attribute Weights
Control how much each field contributes to the BM25 relevance score. Higher weight means matches in that field rank higher.
{
"attribute_weights": {
"title": 3.0,
"brand": 2.0,
"description": 1.0
}
}Typo Tolerance
Fuzzy matching lets Skirre find results even when the query contains typos. Configure the minimum word length required before typos are tolerated.
| Parameter | Type | Description |
|---|---|---|
| enabled optional | boolean | Enable or disable typo tolerance. Default: true |
| min_word_length_1_typo optional | number | Minimum word length to allow 1 typo. Default: 4 |
| min_word_length_2_typos optional | number | Minimum word length to allow 2 typos. Default: 8 |
See the Typo Tolerance guide for tuning recommendations.
Semantic Search
Enable hybrid search to combine BM25 keyword scores with embedding-based semantic similarity. When enabled, Skirre computes vector embeddings for documents and queries, then blends the scores using configurable weights.
| Parameter | Type | Description |
|---|---|---|
| enabled optional | boolean | Enable semantic/hybrid search. Default: false |
| keyword_weight optional | number | Weight for BM25 keyword score (0.0–1.0). Default: 0.6 |
| semantic_weight optional | number | Weight for embedding cosine similarity (0.0–1.0). Default: 0.4 |
See the Semantic Search guide for details on how hybrid scoring works.
Price Ranges
Define custom ranges for price faceting. Values are in the smallest currency unit (e.g. cents).
{
"price_ranges": [
{ "label": "Under $25", "min": 0, "max": 2500 },
{ "label": "$25–$50", "min": 2500, "max": 5000 },
{ "label": "$50–$100", "min": 5000, "max": 10000 },
{ "label": "$100+", "min": 10000, "max": 999999 }
]
}Enrichment
Configure AI-powered catalog enrichment using your own LLM. See the Enrichment API reference for the full endpoint documentation.
| Parameter | Type | Description |
|---|---|---|
| enabled required | boolean | Enable enrichment for this index. |
| provider required | object | LLM provider: base_url, api_key, model, max_tokens (default 2048). |
| mode optional | string | "suggest" (default) or "auto_apply". Default: "suggest" |
| confidence_threshold optional | number | Minimum confidence for auto-apply (0.0–1.0). Default: 0.8 |
| batch_size optional | number | Default documents per enrichment run. Default: 100 |
| categories optional | string[] | Valid categories for category inference. If set, the LLM only suggests from this list. |
{
"enrichment": {
"enabled": true,
"provider": {
"base_url": "https://api.openai.com/v1",
"api_key": "sk-...",
"model": "gpt-4o-mini",
"max_tokens": 2048
},
"mode": "suggest",
"confidence_threshold": 0.8,
"batch_size": 100,
"categories": ["Earrings", "Necklaces", "Rings"]
}
}Scoring
Configure document scoring to boost popular items in search results. Scores are computed from behavioral events (clicks, purchases, views) every 6 hours. See the Scoring guide for details on the algorithm and tuning.
| Parameter | Type | Description |
|---|---|---|
| enabled optional | boolean | Enable document scoring for this index. Default: false |
| ranking_weight optional | number | How much popularity influences search ranking (0.0–0.5). Default: 0.10 |
| weights optional | object | Per-signal weights: sales_count, revenue, ctr, conversion_rate, view_count, recency. Should sum to ~1.0. |
{
"scoring": {
"enabled": true,
"ranking_weight": 0.10,
"weights": {
"sales_count": 0.30,
"revenue": 0.20,
"ctr": 0.20,
"conversion_rate": 0.15,
"view_count": 0.10,
"recency": 0.05
}
}
}