---
title: "Full-Text Search"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/text-search/full-text-search"
version: "6.2"
language: "python"
---

# Full-Text Search

> Client language: Python. Also available for [C#](https://docs.ravendb.net/6.2/client-api/session/querying/text-search/full-text-search.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/querying/text-search/full-text-search.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/text-search/full-text-search.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**
>
> - This article is about running a full-text search with a **dynamic query**.  
>   To learn how to run a full-text search using a static-index, see [full-text search with index](https://docs.ravendb.net/6.2/indexes/querying/searching.python.md).
>
> - Use the `search()` method to query for documents that contain specified term/s
>   within the text of the specified document field/s.
>
> - When running a full-text search with a dynamic query, the **auto-index** created by the server
>   breaks down the text of the searched document field using the [default search analyzer](https://docs.ravendb.net/6.2/indexes/using-analyzers.python.md#using-the-default-search-analyzer).  
>   All generated terms are lower-cased, so the search is **case-insensitive**.
>
> - Gain additional control over term tokenization by running a full-text search
>   using a [static-index](https://docs.ravendb.net/6.2/indexes/querying/searching.python.md), where the used
>   analyzer is configurable.
>
> > **Info**
> >
> > - A **boost** value can be set for each search to prioritize results.
> >   Learn more in [boost search results](https://docs.ravendb.net/6.2/client-api/session/querying/text-search/boost-search-results.python.md).
> >
> > - User experience can be enhanced by requesting text fragments that **highlight**
> >   the searched terms in the results. Learn more in [highlight search results](https://docs.ravendb.net/6.2/client-api/session/querying/text-search/highlight-query-results.python.md).
>
> - In this page:
>   - [Search for single term](#search-for-single-term)
>   - [Search for multiple terms](#search-for-multiple-terms)
>   - [Search with analyzer-generated phrases](#search-with-analyzer-generated-phrases)
>   - [Search in multiple fields](#search-in-multiple-fields)
>   - [Search in complex object](#search-in-complex-object)
>   - [Search operators](#search-operators)
>   - [Search options](#search-options)
>   - [Using wildcards](#using-wildcards)
>   - [Syntax](#syntax)

## Search for single term

> **Note**
>
> ### Query
>
> ```python
> employees = list(
>   session
>   # Make a dynamic query on Employees collection
>   .query(object_type=Employee)
>   # * Call 'search' to make a Full-Text search
>   # * Search is case-insensitive
>   # * Look for documents containing the term 'University' within their 'Notes' field
>   .search("Notes", "University")
> )
>
> # Results will contain Employee documents that have
> # any case variation of the term 'university' in their 'Notes' field.
> ```
>
> ### RQL
>
> ```sql
> from "Employees"
> where search(Notes, "University")
> ```

- Executing the above query will generate the auto-index `Auto/Employees/BySearch(Notes)`.

- This auto-index will contain the following two index-fields:

  - `Notes`  
    Contains terms with the original text from the indexed document field 'Notes'.  
    Text is lower-cased and Not tokenized.

  - `search(Notes)`  
    Contains **lower-cased terms** that were tokenized from the 'Notes' field by the [default search analyzer](https://docs.ravendb.net/6.2/indexes/using-analyzers.python.md#using-the-default-search-analyzer) (RavenStandardAnalyzer).
    Calling the `search()` method targets these terms to find matching documents.

## Search for multiple terms

- You can search for multiple terms in the **same field** in a single search method.

- By default, the logical operator between these terms is 'OR'.

- This behavior can be modified. See section [Search operators](#search-operators).

> **Note**
>
> **Pass terms in a string**:
>
> ### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # * Pass multiple terms in a single string, separated by spaces.
>   # * Look for documents containing either 'University' OR 'Sales' OR 'Japanese'
>   #   within their 'Notes' field
>   .search("Notes", "University Sales Japanese")
> )
>
> # * Results will contain Employee documents that have at least one of the specified terms.
> # * Search is case-insensitive.
> ```
>
> ### RQL
>
> ```sql
> from "Employees"
> where search(Notes, "University Sales Japanese")
> ```

## Search with analyzer-generated phrases

A value passed to `search()` is processed in two stages:

1. **Search terms**:  
   `search()` parses the value into **search terms**.  
   Unquoted spaces or tabs separate terms, while double quotes keep the enclosed text together as one term.

2. **Tokens**:  
   The [query-time analyzer](https://docs.ravendb.net/6.2/indexes/using-analyzers.python.md#analyzers-at-query-time)
   processes each search term and produces zero, one, or multiple **tokens**.

**When the analyzer produces multiple tokens from one search term**, RavenDB searches those tokens as a **phrase**.  
This means that a document matches only when the corresponding tokens in the searched field are adjacent  
and occur in the same order as the analyzer-generated query tokens.

---

### How the input form affects matching

With RavenDB's default analyzer configuration, compare the following three cases:

> **Note**
>
> **Separate search terms: matched independently**
>
> #### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # Pass two separate search terms
>   .search("Title", "sales representative")
> )
> ```
>
> #### RQL
>
> ```sql
> from "Employees"
> // Pass two separate search terms        
> where search(Title, "sales representative")
> ```
>
> In both the Python and RQL tabs above, the outer quotation marks delimit the string literal.  
> These quotation marks are not part of the value processed by `search()`.  
> RavenDB therefore parses `sales representative` as the two terms `sales` and `representative`.
>
> The search operator combines these terms (`OR` by default), so they do not need to be adjacent or appear in the same order.

> **Note**
>
> **One search term, multiple analyzer tokens: matched as a phrase**
>
> #### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # Pass one term that the analyzer splits
>   .search("Title", "sales%representative")
> )
> ```
>
> #### RQL
>
> ```sql
> from "Employees"
> // Pass one term that the analyzer splits    
> where search(Title, "sales%representative")
> ```
>
> Because `%` is not whitespace, `search()` initially parses `sales%representative` as one term.
> `RavenStandardAnalyzer` then splits that term into the tokens `sales` and `representative`.  
> RavenDB searches those analyzer-generated tokens as a **phrase**.
>
> - The `%` character is [not a wildcard](#using-wildcards)
>   and has no special meaning to `search()`.  
>   It is simply an example of punctuation that `RavenStandardAnalyzer` treats as a token boundary.  
>   Other analyzers can produce different tokens from the same input.
>
> - If the `search()` value contains other search terms, the search operator combines those terms with the generated phrase.
>   It does not change the required order or adjacency of the tokens within the phrase.

> **Note**
>
> **Explicitly quoted text: matched as a phrase**
>
> #### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # Pass an explicitly quoted phrase
>   .search("Title", '"sales representative"')
> )
> ```
>
> #### RQL
>
> ```sql
> from "Employees"
> // Pass an explicitly quoted phrase    
> where search(Title, '"sales representative"')
> ```
>
> The quotation marks around `sales representative` are part of the value sent to RavenDB.  
> They instruct `search()` to keep it together as one search term.  
> The analyzer produces the tokens `sales` and `representative`, which RavenDB searches as a **phrase**.

The analyzer-generated phrase and the explicitly quoted phrase use the same phrase-matching rules.  
Both match `Sales Representative`.
Neither matches `Representative Sales`, where the order is reversed, or `Sales Area Representative`, where the tokens are not adjacent.

> **Info:** Analyzer used by a dynamic query
>
> - A dynamic full-text query uses the default search analyzer configured for the auto-index.  
>   This is `RavenStandardAnalyzer` unless [Indexing.Analyzers.Search.Default](https://docs.ravendb.net/6.2/server/configuration/indexing-configuration.md#indexinganalyzerssearchdefault)
>   is configured with a different analyzer.
>
> - To choose an analyzer for a specific index-field, use a [static index](https://docs.ravendb.net/6.2/indexes/querying/searching.python.md).

---

### Wildcard terms

Search terms that use the supported `*` wildcard forms are handled as prefix, suffix, or contains queries;  
they are not converted into phrase queries.
See [Using wildcards](#using-wildcards).

---

### When analysis produces no tokens

If the analyzer produces no tokens from a search term - for example, because it removes all of them as
[stop words](https://docs.ravendb.net/6.2/indexes/using-analyzers.python.md#analyzers-that-remove-common-stop-words) -  
RavenDB drops that term from the query. If no term in the `search()` call produces a token, the call matches no documents.

---

### Search-engine compatibility

Phrase matching for analyzer-generated tokens is supported by both **Corax** and **Lucene**.

> **Note**
>
> #### Existing Corax indexes:
>
> - Corax indexes store the term-position data required for phrase matching only if they were created or reset in RavenDB 6.0 or later.
> - A Corax index - including an auto-index - created before this support was available retains the legacy behavior, where analyzer-generated tokens are matched independently.  
>   Reset or recreate the index to enable phrase matching.

## Search in multiple fields

- You can search for terms in **different fields** by making multiple search calls.

- By default, the logical operator between consecutive search methods is 'OR'.

- This behavior can be modified. See section [Search options](#search-options).

> **Note**
>
> ### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # * Look for documents containing:
>   #   'French' in their 'Notes' field OR 'President' in their 'Title' field
>   .search("Notes", "French")
>   .search("Title", "President")
> )
>
> # * Results will contain Employee documents that have
> #   at least one of the specified fields with the specified terms.
> # * Search is case-insensitive.
> ```
>
> ### RQL
>
> ```sql
> from "Employees"
> where (search(Notes, "French") or search(Title, "President"))
> ```

## Search in complex object

- You can search for terms within a complex object.

- Any nested text field within the object is searchable.

> **Note**
>
> ### Query
>
> ```python
> companies = list(
>   session.query(object_type=Company)
>   # * Look for documents that contain:
>   #   the term 'USA' OR 'London' in any field within the complex 'Address' object
>   .search("Address", "USA London")
> )
>
> # * Results will contain Company documents that are located either in 'USA' OR in 'London'.
> # * Search is case-insensitive.
> ```
>
> ### RQL
>
> ```sql
> from "Companies"
> where search(Address, "USA London")
> ```

## Search operators

- By default, the logical operator between multiple terms within the **same field** in a search call is **OR**.

- This can be modified using the `operator` parameter as follows:

> **Note**
>
> **AND**:
>
> ### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # * Pass 'operator' with 'SearchOperator.AND'
>   .search("Notes", "College German", operator=SearchOperator.AND)
> )
>
> # * Results will contain Employee documents that have BOTH 'College' AND 'German'
> #   in their 'Notes' field.
> # * Search is case-insensitive.
> ```
>
> ### RQL
>
> ```sql
> from "Employees"
> where search(Notes, "College German", and)
> ```

> **Note**
>
> **OR**:
>
> ### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # * Pass 'operator' with 'SearchOperator.OR' (or don't pass this param at all)
>   .search("Notes", "College German", operator=SearchOperator.OR)
> )
>
> # * Results will contain Employee documents that have EITHER 'College' OR 'German'
> #   in their 'Notes' field.
> # * Search is case-insensitive.
> ```
>
> ### RQL
>
> ```sql
> from "Employees"
> where search(Notes, "College German")
> ```

## Search options

- Search options allow to:
  - Negate a search criteria.
  - Specify the logical operator used between **consecutive search calls**.

> **Note**
>
> **Negate search**:
>
> ### Query
>
> ```python
> companies = list(
>   session.query(object_type=Company)
>   .open_subclause()
>   # Call 'not_' to negate the next search call
>   .not_()
>   .search("Address", "USA")
>   .close_subclause()
> )
>
> # * Results will contain Company documents are NOT located in 'USA'
> # * Search is case-insensitive
> ```
>
> ### RQL
>
> ```sql
> from "Companies"
> where (exists(Address) and not search(Address, "USA"))
> ```

> **Note**
>
> **Default behavior between search calls**:
>
> - By default, the logical operator between consecutive search methods is **OR**.
>
> ### Query
>
> ```python
> companies = list(
>   session.query(object_type=Company)
>   .where_equals("Contact.Title", "Owner")
>   # Operator AND will be used with previous 'where_equals' predicate
>   .search("Address.Country", "France")
>   # Operator OR will be used between the two 'search' calls by default
>   .search("Name", "Markets")
> )
>
> # * Results will contain Company documents that have:
> #   ('Owner' as the 'Contact.Title')
> #   AND
> #   (are located in 'France' OR have 'Markets' in their 'Name' field)
> #
> # * Search is case-insensitive
> ```
>
> ### RQL
>
> ```sql
> from "Companies" 
> where Contact.Title == "Owner" and
> (search(Address.Country, "France") or search(Name, "Markets"))
> ```

> **Note**
>
> **AND search calls**:
>
> ### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   .search("Notes", "French")
>   # Call 'and_also' so that operator AND will be used with previous 'search' call
>   .and_also()
>   .search("Title", "Manager")
> )
>
> # * Results will contain Employee documents that have:
> #   ('French' in their 'Notes' field)
> #   AND
> #   ('Manager' in their 'Title' field)
> #
> # * Search is case-insensitive
> ```
>
> ### RQL
>
> ```sql
> from "Employees" 
> where search(Notes, "French") and search(Title, "Manager")
> ```

> **Note**
>
> **Combine AND with negation**:
>
> ### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   .search("Notes", "French")
>   # Call 'and_also' so that operator AND will be used with previous 'search' call
>   .and_also()
>   .open_subclause()
>   # Call 'not_' to negate the next search call
>   .not_()
>   .search("Title", "Manager")
>   .close_subclause()
> )
>
> # * Results will contain Employee documents that have:
> #   ('French' in their 'Notes' field)
> #   AND
> #   (do NOT have 'Manager' in their 'Title' field)
> #
> # * Search is case-insensitive
> ```
>
> ### RQL
>
> ```sql
> from "Employees"
> where search(Notes, "French") and
> (exists(Title) and not search(Title, "Manager"))
> ```

## Using wildcards

- Wildcards can be used to replace:
  - Prefix of a searched term
  - Postfix of a searched term
  - Both prefix & postfix

- Note:

  - Searching with a wildcard as the prefix of the term (e.g. `*text`) is less recommended,  
    as it will cause the server to perform a full index scan.

  - Instead, consider using a static-index that indexes the field in reverse order  
    and then query with a wildcard as the postfix, which is much faster.

> **Note**
>
> ### Query
>
> ```python
> employees = list(
>   session.query(object_type=Employee)
>   # Use '*' to replace one or more characters
>   .search("Notes", "art*")
>   .search("Notes", "*logy")
>   .search("Notes", "*mark*")
> )
>
> # Results will contain Employee documents that have in their 'Notes' field:
> # (terms that start with 'art')  OR
> # (terms that end with 'logy') OR
> # (terms that have the text 'mark' in the middle)
> #
> # * Search is case-insensitive
> ```
>
> ### RQL
>
> ```sql
> from "Employees" where
> search(Notes, "art*") or
> search(Notes, "*logy") or
> search(Notes, "*mark*")
> ```

## Syntax

```python
def search(self, field_name: str, search_terms: str, operator: SearchOperator = None) -> DocumentQuery[_T]: ...
```

| Parameter | Type | Description |
| - | - | - |
| **field\_name** | `str` | Name of the searched field. |
| **search\_terms** | `str` | A string containing the term or terms (separated by spaces) to search for. |
| **operator** | `SearchOperator` | Logical operator to use between multiple terms in the same Search method. <br /> Can be `SearchOperator.OR` or `SearchOperator.AND`. <br /> **Default** is `SearchOperator.OR` |

| Return Type | Description |
| - | - |
| `DocumentQuery[_T]` | The same object used for the query |

## See also

- [Query overview](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.python.md)
- [How to Use Regex](https://docs.ravendb.net/6.2/client-api/session/querying/text-search/using-regex.python.md)
- [How to Query With Exact Match](https://docs.ravendb.net/6.2/client-api/session/querying/text-search/exact-match-query.python.md)
- [Analyzers](https://docs.ravendb.net/6.2/indexes/using-analyzers.python.md)
- [Full-text search with index](https://docs.ravendb.net/6.2/indexes/querying/searching.python.md)
