Configure field weights to control relevance and boost important fields in search results.

What Are Field Weights?

Field weights let you boost the importance of specific fields when ranking results. A field with weight 3 is three times more important than a field with weight 1.

Basic Configuration

import { LumoSearch } from '@lumosearch/search'

const docs = [
  {
    title: 'JavaScript Patterns',
    description: 'Design patterns for JavaScript applications',
    body: 'Full article content here...'
  }
]

const search = new LumoSearch(docs, {
  keys: [
    { name: 'title', weight: 3 },       // Most important
    { name: 'description', weight: 2 }, // Medium importance
    { name: 'body', weight: 1 }         // Least important
  ]
})

Best Practice: Title fields should typically have the highest weight, followed by metadata fields, with body content having the lowest weight.

String Syntax

For simple cases, you can use strings (default weight is 1.0):

const search = new LumoSearch(docs, {
  keys: ['title', 'body']  // Both have weight 1.0
})

Nested Fields

Use dot notation for nested object fields:

const docs = [
  {
    title: 'Article Title',
    author: {
      name: 'Jane Doe',
      bio: 'Software engineer and writer'
    },
    metadata: {
      tags: ['javascript', 'programming'],
      category: 'tutorials'
    }
  }
]

const search = new LumoSearch(docs, {
  keys: [
    { name: 'title', weight: 5 },
    { name: 'author.name', weight: 3 },
    { name: 'metadata.tags', weight: 2 },
    { name: 'author.bio', weight: 1 }
  ]
})

Choosing Weights

E-commerce Products

const search = new LumoSearch(products, {
  keys: [
    { name: 'name', weight: 5 },        // Product name is critical
    { name: 'brand', weight: 3 },       // Brand matters
    { name: 'category', weight: 2 },    // Category helps
    { name: 'description', weight: 1 }  // Description less critical
  ]
})

Documentation Search

const search = new LumoSearch(docs, {
  keys: [
    { name: 'title', weight: 10 },      // Page title most important
    { name: 'headings', weight: 5 },    // Section headings very important
    { name: 'keywords', weight: 3 },    // Keywords help discovery
    { name: 'content', weight: 1 }      // Full content less weighted
  ]
})

Blog Posts

const search = new LumoSearch(posts, {
  keys: [
    { name: 'title', weight: 4 },
    { name: 'tags', weight: 3 },
    { name: 'excerpt', weight: 2 },
    { name: 'author.name', weight: 2 },
    { name: 'content', weight: 1 }
  ]
})

User Directory

const search = new LumoSearch(users, {
  keys: [
    { name: 'name', weight: 5 },
    { name: 'email', weight: 4 },
    { name: 'username', weight: 3 },
    { name: 'department', weight: 2 },
    { name: 'bio', weight: 1 }
  ]
})

Weight Guidelines

Weight Range	Use Case
5-10	Critical identifying fields (title, name)
3-4	Important metadata (tags, category, author)
2	Supporting fields (excerpt, description)
1	Body content, full text

Impact on Results

Here's how weights affect ranking:

const docs = [
  { title: 'JavaScript Guide', body: 'Learn TypeScript here' },
  { title: 'TypeScript Guide', body: 'JavaScript is mentioned' }
]

// Query: "typescript"

// With equal weights (1, 1):
// Doc 2 ranks higher (title match)

// With weights (3, 1):
// Doc 2 ranks MUCH higher (title is 3x more important)

// With weights (1, 3):
// Doc 1 might rank higher (body is 3x more important)

Testing Different Weights

Experiment with weights to find what works best for your data:

// Test different weight configurations
const configs = [
  { title: 3, body: 1 },
  { title: 5, body: 1 },
  { title: 10, body: 1 }
]

configs.forEach(({ title, body }) => {
  const search = new LumoSearch(docs, {
    keys: [
      { name: 'title', weight: title },
      { name: 'body', weight: body }
    ]
  })

  const results = search.search('test query')
  console.log(`Weights (${title}, ${body}):`, results[0].item.title)
})

Common Mistakes

❌ Weights too extreme

{ name: 'title', weight: 100 },
{ name: 'body', weight: 1 }

Body matches become almost irrelevant. Use 5-10x max difference.

❌ All weights equal

{ name: 'title', weight: 1 },
{ name: 'body', weight: 1 }

Doesn't leverage the power of field weighting. At least 2-3x difference is good.

❌ Ignoring data characteristics

If titles are always 2-3 words and body is 1000 words, you need strong title boost to compensate for length differences.

Best Practices

Start with title:3, metadata:2, body:1 as a baseline
Test with real queries and adjust based on results
Consider field length — short fields may need higher weights
Use 2-10x differences, avoid extreme ratios like 100:1
Document your weight choices for future reference

Search Concepts →

Understand BM25F scoring and how weights affect ranking

Search API →

Use weighted fields with filters and predicates

Weighted Fields