Settings

Index settings control search behavior: synonyms, field weights, typo tolerance, and semantic search configuration. Settings are per-index and persisted to disk.

GET /v1/indices/{uid}/settings Admin key

Get the current settings for an index.

Response 200 OK

text
{
  "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

text
const settings = await idx.getSettings();
PUT /v1/indices/{uid}/settings Admin key

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

ParameterTypeDescription
language optionalstringTokenization language code. See Language section below.
synonyms optionalobjectMap of term to synonym arrays. See Synonyms section below.
attribute_weights optionalobjectMap of field name to BM25 weight multiplier.
typo_tolerance optionalobjectTypo tolerance configuration. See below.
price_ranges optionalobject[]Custom price facet ranges. See below.
semantic optionalobjectSemantic/hybrid search configuration. See below.
enrichment optionalobjectAI catalog enrichment configuration. See below.
scoring optionalobjectDocument scoring configuration. See below.
text
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

text
await idx.updateSettings({
  synonyms: { shoes: ['sneakers', 'kicks'] },
  typo_tolerance: { min_word_length_1_typo: 3 },
});

Response 200 OK

text
{ "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.

ParameterTypeDescription
language optionalstringISO 639-1 language code.
Default: "en"

Supported languages:

ParameterTypeDescription
en optionalEnglish — stemming
es optionalSpanish — stemming + accent folding
fr optionalFrench — stemming + accent folding
de optionalGerman — stemming + accent folding
pt optionalPortuguese — stemming + accent folding
it optionalItalian — stemming + accent folding
nl optionalDutch — stemming + accent folding
ja optionalJapanese — dictionary-based segmentation (IPADIC)
zh optionalChinese — word segmentation (jieba)
ko optionalKorean — 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.

text
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

text
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.

text
{
  "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.

text
{
  "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.

ParameterTypeDescription
enabled optionalbooleanEnable or disable typo tolerance.
Default: true
min_word_length_1_typo optionalnumberMinimum word length to allow 1 typo.
Default: 4
min_word_length_2_typos optionalnumberMinimum 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.

ParameterTypeDescription
enabled optionalbooleanEnable semantic/hybrid search.
Default: false
keyword_weight optionalnumberWeight for BM25 keyword score (0.0–1.0).
Default: 0.6
semantic_weight optionalnumberWeight 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).

text
{
  "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.

ParameterTypeDescription
enabled requiredbooleanEnable enrichment for this index.
provider requiredobjectLLM provider: base_url, api_key, model, max_tokens (default 2048).
mode optionalstring"suggest" (default) or "auto_apply".
Default: "suggest"
confidence_threshold optionalnumberMinimum confidence for auto-apply (0.0–1.0).
Default: 0.8
batch_size optionalnumberDefault documents per enrichment run.
Default: 100
categories optionalstring[]Valid categories for category inference. If set, the LLM only suggests from this list.
text
{
  "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.

ParameterTypeDescription
enabled optionalbooleanEnable document scoring for this index.
Default: false
ranking_weight optionalnumberHow much popularity influences search ranking (0.0–0.5).
Default: 0.10
weights optionalobjectPer-signal weights: sales_count, revenue, ctr, conversion_rate, view_count, recency. Should sum to ~1.0.
text
{
  "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
    }
  }
}