# Optimal Resolution Value Formula for FlexSearch: Balancing Document Length and Search Relevance

> Discover the optimal resolution value formula for FlexSearch v7: 2 × √maxDocLength. Balance document length and search relevance for faster results.

- Repository: [Nextapps GmbH/flexsearch](https://github.com/nextapps-de/flexsearch)
- Tags: deep-dive
- Published: 2026-02-23

---

**The optimal resolution value for FlexSearch is calculated as `2 × ⌊√maxDocLength⌋`, where `maxDocLength` represents the term count of your largest document.**

FlexSearch, the high-performance full-text search library by nextapps-de/flexsearch, uses a **resolution** parameter to divide document scores into discrete scoring slots. Choosing the right value requires balancing search relevance against memory consumption, with document length serving as the primary determining factor. The resolution formula ensures you allocate enough buckets to distinguish term positions meaningfully without wasting memory on empty slots.

## Why Document Length Determines the Resolution Value

FlexSearch maps each term's position to a scoring slot during indexing. The **resolution** defines how many slots exist (ranging from `0` to `resolution-1`).

- **Low resolution** collapses many term positions into the same bucket, reducing relevance precision.
- **High resolution** creates excessive empty buckets, increasing memory overhead without improving search quality.

The optimal value scales with your **largest document length** because longer documents contain more distinct term positions that need separation.

## The Optimal Resolution Value Formula

### The Square Root Formula

According to the [FlexSearch README](https://github.com/nextapps-de/flexsearch/blob/master/README.md), the well-balanced formula for the default (non-context) resolution is:

> **Formula:** `resolution = 2 × ⌊√content.length⌋`

Where `content.length` represents the term count of the largest document passed to `index.add()`.

In JavaScript implementation:

```javascript
function optimalResolution(maxDocLength) {
  return 2 * Math.floor(Math.sqrt(maxDocLength));
}

```

This square-root scaling provides sufficient granularity to distinguish term positions while keeping the total slot count modest.

### Implementation Example

For a document containing 1,200 terms:

```javascript
const maxLength = 1200;
const resolution = 2 * Math.floor(Math.sqrt(maxLength)); // Returns 68

const index = new FlexSearch.Index({
  resolution,  // 68 scoring slots
  context: { resolution: 3 }  // Separate context resolution
});

```

## Context Resolution vs Standard Resolution

When enabling the **context** option (`index.context`), FlexSearch uses a separate `resolution_ctx` parameter for proximity-based scoring rather than absolute position scoring.

**Key differences:**

- **Standard resolution**: Uses the square-root formula above (typically values of 9-100+ depending on document size).
- **Context resolution**: Requires much lower values, typically **1-3**, because context scoring only needs to distinguish "near" versus "far" term occurrences.

According to the source code in [`src/index.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index.js) (lines 95-124), the default context resolution is `3`, and values higher than approximately 50% of the main resolution are usually excessive.

## How FlexSearch Implements Resolution Internally

The resolution parameter directly impacts the scoring mechanism in three key source locations:

1. **Default Configuration** (`src/index.js:95-124`): Sets the default `resolution` to `9` and `resolution_ctx` to `3`.

2. **Score Calculation** (`src/index/add.js:301-321`): The `get_score()` function maps term positions into resolution slots by stretching the raw position across the `[0, resolution-1]` range, ensuring the first slot is reserved for the best match.

3. **Custom Scoring** ([`doc/customization.md`](https://github.com/nextapps-de/flexsearch/blob/main/doc/customization.md)): When providing a custom `score` function, the return value must be an integer in the range `[0, resolution-1]` to properly align with the allocated scoring slots.

## Practical Code Examples

### Optimizing for Large Documents (1,200 Terms)

```javascript
// Calculate resolution for documents up to 1,200 terms
const maxDocLength = 1200;
const optimalResolution = 2 * Math.floor(Math.sqrt(maxDocLength));

const index = new FlexSearch.Index({
  resolution: optimalResolution,  // 68 slots
  context: {
    resolution: 3  // Low value for proximity scoring
  }
});

// Add your documents
index.add(1, "Your document content here...");

```

### Custom Score Function with Resolution Constraints

```javascript
const resolution = 12;

const index = new FlexSearch.Index({
  resolution,
  score: (content, term, termIndex, partialIndex) => {
    // Custom logic must return value in [0, resolution-1]
    // Example: Prioritize terms appearing in first half of document
    const normalizedPos = termIndex / content.length;
    return Math.min(
      Math.floor(normalizedPos * resolution), 
      resolution - 1
    );
  }
});

```

### Context-Only Configuration for Phrase Matching

```javascript
const index = new FlexSearch.Index({
  resolution: 2 * Math.floor(Math.sqrt(500)), // For standard scoring
  context: {
    resolution: 1  // Minimal buckets for proximity-only scoring
  },
  tokenize: "strict"
});

```

## Summary

- **Use the formula** `resolution = 2 × ⌊√maxDocLength⌋` to calculate the optimal resolution value for standard indexing, where `maxDocLength` is the term count of your largest document.
- **Context resolution** requires separate treatment—use values of `1-3` rather than the square-root formula, as proximity scoring needs fewer buckets.
- **Default values** in [`src/index.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index.js) set `resolution` to `9` and `resolution_ctx` to `3`, suitable for small-to-medium documents.
- **Memory vs. relevance** trade-off drives the formula: too low collapses positions, too high wastes memory on empty slots in [`src/index/add.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index/add.js).

## Frequently Asked Questions

### What happens if I set the resolution too high for my document length?

Setting a resolution significantly higher than `2 × √maxDocLength` creates excessive empty scoring buckets in the index structure implemented in [`src/index/add.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index/add.js). This wastes memory without improving search relevance, as the scoring algorithm in `get_score()` cannot utilize granularity finer than the actual term positions in your documents.

### Can I use the same resolution formula for the context option?

No, the square-root formula applies only to the standard resolution. According to the FlexSearch README and source code in [`src/index.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index.js), context resolution (`resolution_ctx`) should use much lower values—typically between `1` and `3`—because proximity scoring only needs to distinguish between "near" and "far" term occurrences rather than precise positional mapping.

### How do I determine the maxDocLength value for the formula?

Calculate `maxDocLength` by counting the number of terms (tokens) in the longest document you plan to index using your chosen tokenizer. If using the default tokenizer, split your longest document by whitespace and punctuation to get the term count. If documents vary significantly in length, consider using the 90th percentile length rather than the absolute maximum to prevent over-allocation for outliers.

### Does the resolution affect query performance or just indexing memory?

The resolution primarily impacts **indexing memory consumption** and **relevance precision** rather than query execution speed. As documented in [`src/index.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index.js) and [`src/index/add.js`](https://github.com/nextapps-de/flexsearch/blob/main/src/index/add.js), the resolution determines how many scoring slots exist in the index structure, which affects how finely term positions can be distinguished during scoring calculation. Query performance remains largely unaffected because the scoring lookup operates in O(1) time regardless of resolution size.