> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/algolia/docsearch/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Parameters

> Configure Algolia search parameters to control filtering, faceting, and result display

DocSearch uses Algolia's powerful search API. You can configure search parameters to control filtering, ranking, attributes, and more.

## Configuring Search Parameters

Search parameters can be set at two levels:

1. **Per-index** (recommended) - using the `indices` prop
2. **Global** (deprecated) - using the top-level `searchParameters` prop

### Per-Index Configuration

```jsx theme={null}
import { DocSearch } from '@docsearch/react';

<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        hitsPerPage: 20,
        facetFilters: ['version:v2', 'language:en'],
        attributesToRetrieve: ['hierarchy', 'content', 'url'],
      }
    }
  ]}
/>
```

<Note>
  Using per-index `searchParameters` allows different configuration for each index when searching multiple indices.
</Note>

## Common Search Parameters

### Filtering

#### facetFilters

Filter results by facet values. Supports AND/OR logic:

```jsx theme={null}
searchParameters: {
  // AND: must match all
  facetFilters: ['version:v2', 'language:en'],
  
  // OR: match any within nested array
  facetFilters: [
    'version:v2',
    ['language:en', 'language:es']
  ],
}
```

**Common use cases:**

* Version filtering: `facetFilters: ['version:latest']`
* Language filtering: `facetFilters: ['language:en']`
* Category filtering: `facetFilters: ['category:tutorial']`

#### filters

Use filter expressions for more complex logic:

```jsx theme={null}
searchParameters: {
  filters: 'published = true AND (category:guide OR category:tutorial)',
}
```

**Operators:**

* Comparison: `=`, `!=`, `<`, `<=`, `>`, `>=`
* Logic: `AND`, `OR`, `NOT`
* Grouping: `()`

### Attributes

#### attributesToRetrieve

Specify which attributes to retrieve (improves performance):

```jsx theme={null}
searchParameters: {
  attributesToRetrieve: [
    'hierarchy.lvl0',
    'hierarchy.lvl1',
    'hierarchy.lvl2',
    'hierarchy.lvl3',
    'content',
    'type',
    'url'
  ],
}
```

<Note>
  By default, DocSearch retrieves `hierarchy.lvl0` through `hierarchy.lvl6`, `content`, `type`, and `url`. Only override if you need to optimize performance or exclude certain attributes.
</Note>

#### attributesToSnippet

Control snippet length for each attribute:

```jsx theme={null}
searchParameters: {
  attributesToSnippet: [
    'hierarchy.lvl1:10',  // 10 words
    'hierarchy.lvl2:10',
    'content:15',         // 15 words
  ],
}
```

#### restrictSearchableAttributes

Limit which attributes are searched:

```jsx theme={null}
searchParameters: {
  // Only search in content, not titles
  restrictSearchableAttributes: ['content'],
  
  // Or search specific hierarchy levels
  restrictSearchableAttributes: ['hierarchy.lvl1', 'hierarchy.lvl2', 'content'],
}
```

### Pagination and Limits

#### hitsPerPage

Number of results per query:

```jsx theme={null}
searchParameters: {
  hitsPerPage: 20, // Default is 20
}
```

<Note>
  For DocSearch, combine `hitsPerPage` with the `maxResultsPerGroup` prop to control result display.
</Note>

### Highlighting and Snippeting

#### highlightPreTag / highlightPostTag

Customize highlight markup:

```jsx theme={null}
searchParameters: {
  highlightPreTag: '<em class="highlight">',
  highlightPostTag: '</em>',
}
```

Default values:

* `highlightPreTag`: `'<mark>'`
* `highlightPostTag`: `'</mark>'`

#### snippetEllipsisText

Customize ellipsis text:

```jsx theme={null}
searchParameters: {
  snippetEllipsisText: '…', // Default
}
```

### Advanced Parameters

#### distinct

Remove duplicate or similar results:

```jsx theme={null}
searchParameters: {
  distinct: true,
  // or specify the number of distinct hits per group
  distinct: 2,
}
```

#### clickAnalytics

Enable click analytics:

```jsx theme={null}
searchParameters: {
  clickAnalytics: true,
}
```

<Note>
  When the top-level `insights` prop is `true`, `clickAnalytics` is automatically enabled unless explicitly set to `false` in `searchParameters`.
</Note>

#### optionalWords

Make certain query words optional:

```jsx theme={null}
searchParameters: {
  optionalWords: ['react', 'javascript'],
}
```

#### removeWordsIfNoResults

Automatically remove words if no results found:

```jsx theme={null}
searchParameters: {
  removeWordsIfNoResults: 'allOptional', // or 'firstWords' or 'lastWords'
}
```

## Complete SearchParamsObject Type

Here's the TypeScript interface from algoliasearch:

```typescript theme={null}
import type { SearchParamsObject } from 'algoliasearch/lite';

interface DocSearchIndex {
  name: string;
  searchParameters?: SearchParamsObject;
}
```

`SearchParamsObject` includes:

* `query?: string`
* `facetFilters?: string[] | string[][]`
* `filters?: string`
* `attributesToRetrieve?: string[]`
* `attributesToSnippet?: string[]`
* `restrictSearchableAttributes?: string[]`
* `hitsPerPage?: number`
* `highlightPreTag?: string`
* `highlightPostTag?: string`
* `snippetEllipsisText?: string`
* `distinct?: boolean | number`
* `clickAnalytics?: boolean`
* And many more...

<Card title="Full API Reference" icon="book">
  See the [Algolia API documentation](https://www.algolia.com/doc/api-reference/search-api-parameters/) for all available search parameters.
</Card>

## Common Patterns

### Version-Specific Documentation

```jsx theme={null}
function VersionedDocSearch({ version }) {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={[
        {
          name: 'documentation',
          searchParameters: {
            facetFilters: [`version:${version}`, 'language:en'],
            hitsPerPage: 15,
          }
        }
      ]}
    />
  );
}
```

### Multi-Language Search

```jsx theme={null}
function MultiLanguageDocSearch({ language }) {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={[
        {
          name: 'documentation',
          searchParameters: {
            facetFilters: [`language:${language}`],
            // Fallback to English if no results
            removeWordsIfNoResults: 'allOptional',
          }
        }
      ]}
    />
  );
}
```

### Filtered Category Search

```jsx theme={null}
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        facetFilters: [[
          'category:getting-started',
          'category:guides',
          'category:tutorials'
        ]],
      }
    }
  ]}
/>
```

### Performance-Optimized Search

```jsx theme={null}
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        // Retrieve only essential fields
        attributesToRetrieve: [
          'hierarchy.lvl0',
          'hierarchy.lvl1',
          'hierarchy.lvl2',
          'content',
          'url'
        ],
        // Shorter snippets
        attributesToSnippet: [
          'content:10',
        ],
        // Fewer results
        hitsPerPage: 10,
      }
    }
  ]}
  maxResultsPerGroup={5}
/>
```

### Search with Ask AI Parameters

When using Ask AI, you can also configure search parameters for the AI context:

```jsx theme={null}
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        // Regular search parameters
        facetFilters: ['version:v2'],
        hitsPerPage: 20,
      }
    }
  ]}
  askAi={{
    assistantId: 'your-assistant-id',
    searchParameters: {
      // Ask AI specific parameters
      facetFilters: ['version:v2', 'language:en'],
      attributesToRetrieve: ['content', 'hierarchy', 'url'],
      distinct: true,
    }
  }}
/>
```

<Note>
  Ask AI `searchParameters` are separate from index `searchParameters`. They control what content the AI uses to generate answers.
</Note>

## Debugging Search Parameters

### Viewing Search Requests

Use `transformSearchClient` to log search requests:

```jsx theme={null}
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        facetFilters: ['version:v2'],
      }
    }
  ]}
  transformSearchClient={(searchClient) => {
    return {
      ...searchClient,
      search(requests) {
        console.log('Search requests:', requests);
        return searchClient.search(requests);
      },
    };
  }}
/>
```

### Testing Parameters

Test parameters in Algolia dashboard before adding them to your code:

1. Go to your Algolia dashboard
2. Open the "Search" page
3. Use the search parameters panel to test filters, facets, etc.
4. Once satisfied, copy the parameters to your code

## Migration from Deprecated Props

<Warning>
  The top-level `searchParameters` prop is deprecated. Use per-index parameters with the `indices` prop instead.
</Warning>

### Before (Deprecated)

```jsx theme={null}
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indexName="documentation"
  searchParameters={{
    hitsPerPage: 20,
    facetFilters: ['version:v2'],
  }}
/>
```

### After (Recommended)

```jsx theme={null}
<DocSearch
  appId="YOUR_APP_ID"
  apiKey="YOUR_SEARCH_API_KEY"
  indices={[
    {
      name: 'documentation',
      searchParameters: {
        hitsPerPage: 20,
        facetFilters: ['version:v2'],
      }
    }
  ]}
/>
```

## Complete Example

```jsx theme={null}
import { DocSearch } from '@docsearch/react';
import '@docsearch/css';

function App() {
  const currentVersion = 'v2';
  const userLanguage = 'en';
  
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      apiKey="YOUR_SEARCH_API_KEY"
      indices={[
        {
          name: 'documentation',
          searchParameters: {
            // Filtering
            facetFilters: [
              `version:${currentVersion}`,
              `language:${userLanguage}`
            ],
            filters: 'published = true',
            
            // Attributes
            attributesToRetrieve: [
              'hierarchy.lvl0',
              'hierarchy.lvl1',
              'hierarchy.lvl2',
              'hierarchy.lvl3',
              'content',
              'type',
              'url'
            ],
            attributesToSnippet: [
              'hierarchy.lvl1:10',
              'hierarchy.lvl2:10',
              'content:15'
            ],
            
            // Results
            hitsPerPage: 20,
            distinct: true,
            
            // Highlighting
            highlightPreTag: '<mark class="search-highlight">',
            highlightPostTag: '</mark>',
            snippetEllipsisText: '…',
            
            // Analytics
            clickAnalytics: true,
          }
        },
        {
          name: 'blog_posts',
          searchParameters: {
            facetFilters: [`language:${userLanguage}`],
            hitsPerPage: 5,
            filters: 'published = true',
          }
        }
      ]}
      maxResultsPerGroup={10}
      insights={true}
    />
  );
}
```