---
title: "Query for Suggestions"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions"
version: "6.2"
language: "php"
---

# Query for Suggestions

> Client language: PHP. Also available for [Java](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.java.md), [C#](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.md), [Python](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.python.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - Given a string term, the Suggestion feature will offer **similar terms** from your data.
>
> - Word similarities are found using string distance algorithms.
>
> - Examples in this article demonstrate getting suggestions with a **dynamic-query**.  
>   For getting suggestions with an **index-query** see [query for suggestions with index](https://docs.ravendb.net/6.2/indexes/querying/suggestions.php.md).
>
> - In this page:
>
>   - Overview:
>     - [What are terms](#what-are-terms)
>     - [When to use suggestions](#when-to-use-suggestions)
>
>   - Examples:
>     - [Suggest terms - for a single term](#suggest-terms---for-a-single-term)
>     - [Suggest terms - for multiple terms](#suggest-terms---for-multiple-terms)
>
>   - [The auto-index terms in Studio](#the-auto-index-terms-in-studio)
>
>   - [Syntax](#syntax)

## What are terms

- All queries in RavenDB use an index - learn more about that [here](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.php.md#queries-always-provide-results-using-an-index).  
  Whether making a dynamic query which generates an auto-index or using a static index,  
  the data from your documents is 'broken' into **terms** that are kept in the index.

- This tokenization process (what terms will be generated) depends on the analyzer used,  
  various analyzers differ in the way they split the text stream. Learn more in [Analyzers](https://docs.ravendb.net/6.2/indexes/using-analyzers.php.md).

- The terms can then be queried to retrieve matching documents that contain them.

## When to use suggestions

Querying for suggestions is useful in the following scenarios:

- **When query has no results**:

  - When searching for documents that match some condition on a given string term,  
    if the term is misspelled then you will Not get any results.  
    You can then ask RavenDB to suggest similar terms that do exist in the index.

  - The suggested terms can then be used in a new query to retrieve matching documents,  
    or simply presented to the user asking what they meant to query.

- **When looking for alternative terms**:

  - When simply searching for additional alternative terms for a term that does exist.

> **Warning**
>
> The resulting suggested terms will Not include the term for which you search,  
> they will only contain the similar terms.

## Suggest terms - for a single term

Consider this example:  
Based on the Northwind sample data, the following query has no resulting documents,  
as no document in the Products collection contains the term `chaig` in its `Name` field.

```php
/**
* Usage:
*   - suggestUsing(SuggestionBase $suggestion);
*   - suggestUsing(Closure $suggestionBuilder);
*
* @param SuggestionBase|Closure|null $suggestionOrBuilder
* @return SuggestionDocumentQueryInterface
*/
public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface;
```

- Executing the above query will generate the auto-index `Auto/Products/ByName`.  
  This auto-index will contain a list of all available terms from the document field `Name`.  
  The generated terms are visible in the Studio - see image [below](#the-auto-index-terms-in-studio).

- If you suspect that the term `chaig` in the query criteria is written incorrectly,  
  you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:.

### Query

```php
/**
* Usage:
*   - byField("fieldName", "term");
*   - byField("fieldName", ["term1", "term2"]);
*/
function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface;

function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface;
```

### DocumentQuery

```php
$options = new SuggestionOptions();
$options->setAccuracy(0.4);
$options->setPageSize(5);
$options->setDistance(StringDistanceTypes::jaroWinkler());
$options->setSortMode(SuggestionSortMode::popularity());

/** @var array<SuggestionResult> $suggestions */
$suggestions = $session
  ->query(Employee::class, Employees_ByFullName::class)
  ->suggestUsing(function($builder) use ($options) {
      $builder->byField("FullName", "johne")
          ->withOptions($options);
  })
  ->execute();
```

### RQL

```sql
// Query for terms from field 'Name' that are similar to 'chaig'
from "Products"
select suggest(Name, "chaig")
```

## Suggest terms - for multiple terms

### Query

```php
private int $pageSize = 15;
private ?StringDistanceTypes $distance = null;
private float $accuracy = 0.5;
private ?SuggestionSortMode $sortMode = null;

public function __construct()
{
  $distance = StringDistanceTypes::levenshtein();
  $sortMode = SuggestionSortMode::popularity();
  ...
}

// getters and setters for fields listed above
```

### Query\_async

```php
$suggestionWithTerm = new SuggestionWithTerm("FullName");
$suggestionWithTerm->setTerm("johne");

/** @var array<SuggestionResult> $suggestions */
$suggestions = $session
  ->query(Employee::class, Employees_ByFullName::class)
  ->suggestUsing($suggestionWithTerm)
  ->execute();
```

### RQL

```sql
// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof'
from "Products" select suggest(Name, $p0)
{ "p0" : ["chaig", "tof"] }
```

## The auto-index terms in Studio

Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`:

![Figure 1. Auto-index terms](https://docs.ravendb.net/assets/images/auto-index-terms-22a0dd88b792b1192dc5f78cb5a63cd4.png)

1. **The field name** - derived from the document field that was used in the dynamic-query.  
   In this example the field name is `Name`.

2. **The terms** generated from the data that the Products collection documents have in their `Name` field.

## Syntax

**Suggest using**:

```php
/**
* Usage:
*   - suggestUsing(SuggestionBase $suggestion);
*   - suggestUsing(Closure $suggestionBuilder);
*
* @param SuggestionBase|Closure|null $suggestionOrBuilder
* @return SuggestionDocumentQueryInterface
*/
public function suggestUsing(null|SuggestionBase|Closure $suggestionOrBuilder): SuggestionDocumentQueryInterface;
```

| Parameter | Type | Description |
| - | - | - |
| **$suggestionOrBuilder** | `SuggestionBase` | An instance of `SuggestionBase`.<br />Defines the type of suggestion requested. |
| **$suggestionOrBuilder** | `Closure` | Builder with a fluent API that constructs a `SuggestionBase` instance. |

**Builder operations**:

```php
/**
* Usage:
*   - byField("fieldName", "term");
*   - byField("fieldName", ["term1", "term2"]);
*/
function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface;

function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface;
```

| Parameter | Type | Description |
| - | - | - |
| **$fieldName** | `?string` | The index field in which to search for similar terms |
| **$terms** | `null`<br />`string`<br />`StringArray`<br />`array` | List of terms to get suggested similar terms for |
| **$options** | `?SuggestionOptions` | Non-default options to use in the operation (optional) |

**Suggestions options**:

```php
/**
* Usage:
*   - byField("fieldName", "term");
*   - byField("fieldName", ["term1", "term2"]);
*/
function byField(?string $fieldName, null|string|StringArray|array $terms): SuggestionOperationsInterface;

function withOptions(?SuggestionOptions $options): SuggestionOperationsInterface;
```

| Option | Type | Description |
| - | - | - |
| **$pageSize** | `int` | Maximum number of suggested terms to return |
| **$distance** | `?StringDistanceTypes` | String distance algorithm to use |
| **$accuracy** | `float` | Suggestion accuracy |
| **$sortMode** | `?SuggestionSortMode` | Order to return results by |

## See also

- [Querying: Basics](https://docs.ravendb.net/6.2/indexes/querying/query-index.php.md)
- [How to Query](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.php.md)
- [Query for suggestions with index](https://docs.ravendb.net/6.2/indexes/querying/suggestions.php.md)
