search

The search command retrieves documents from the index. The search command can only be used as the first command in a PPL query.

Syntax

The search command has the following syntax:

search source=[<remote-cluster>:]<index> [<search-expression>]

Parameters

The search command supports the following parameters.

Search expression

The search expression syntax supports:

• Full-text search: error or "error message" – Searches the default field configured in the index.query.default_field setting (default is *, which specifies all fields). For more information, see Default field configuration.
• Field-value comparisons: field=value, field!=value, field>value, field>=value, field<value, or field<=value.
• Time modifiers: earliest=timeModifier, latest=timeModifier – Filter results by time range using the implicit @timestamp field. For more information, see Time modifiers.
• Boolean operators: AND, OR, or NOT. Default is AND.
• Grouping using parentheses: (expression).
• The IN operator for multiple values: field IN (value1, value2, value3).
• Wildcards: * (zero or more characters), ? (exactly one character).

Full-text search

Unlike other PPL commands, the search command supports both quoted and unquoted strings. Unquoted terms are limited to alphanumeric characters, hyphens, underscores, and wildcards. Any other characters require double quotation marks.

The following queries show both syntax types:

• Unquoted: search error, search user-123, search log_*
• Quoted: search "error message", search "user@example.com"

Field values

Field values follow the same quoting rules as search text.

Examples of field value syntax:

• Unquoted: status=active, code=ERR-401
• Quoted: email="user@example.com", message="server error"

Time modifiers

Time modifiers filter search results by a time range using the implicit @timestamp field. Time modifiers support the following formats.

Relative time components

Relative time modifiers use multiple components that can be combined. The following table describes each component.

The following are examples of common time modifier patterns:

• earliest=now – Start from the current time.
• latest='2024-12-31 23:59:59' – End at a specific date and time.
• earliest=-7d – Start from 7 days ago.
• latest='+1d@d' – End at the start of tomorrow.
• earliest='-1month@month' – Start from the beginning of the previous month.
• latest=1754020061 – End at the Unix timestamp 1754020061 (August 1, 2025, 03:47:41 UTC).

The following considerations apply when using time modifiers in the search command:

• Column name conflicts: If your data contains columns named earliest or latest, use backticks to access them as regular fields (for example, `earliest`="value") to avoid conflicts with time modifier syntax.
• Time round syntax: Time modifiers with chained time offsets must be wrapped in quotation marks (for example, latest='+1d@month-10h') for proper query parsing.

Default field configuration

When a search is performed without specifying a field, it uses the default field configured by the index.query.default_field index setting. By default, this is set to *, which searches all fields.

To retrieve the default field setting, use the following request:

GET /accounts/_settings/index.query.default_field

To modify the default field setting, use the following request:

PUT /accounts/_settings
{
  "index.query.default_field": "firstname,lastname,email"
}

Search behavior by field type

Different field types have specific search capabilities and limitations. The following table summarizes how search expressions work with each field type.

Consider the following performance optimizations when working with different field types:

• Each field type has specific search capabilities and limitations. Choosing an inappropriate field type during ingestion can negatively affect performance and query accuracy.
• For wildcard searches on non-keyword fields, create a keyword subfield to improve performance. For example, for wildcard searches on a message field of type text, add a message.keyword field.

Example 1: Fetching all data

Retrieve all documents from an index by specifying only the source without any search conditions. This is useful for exploring small datasets or verifying data ingestion:

source=accounts

The query returns the following results:

Example 2: Text search

For basic text search, use an unquoted single term:

search ERROR source=otellogs
| sort @timestamp
| fields severityText, body
| head 1

The query returns the following results:

Phrase search requires quotation marks for multi-word exact matching:

search "Payment failed" source=otellogs
| fields body

The query returns the following results:

Multiple search terms (unquoted string literals) are automatically combined using the AND operator:

search user email source=otellogs
| sort @timestamp
| fields body
| head 1

The query returns the following results:

search user email is equivalent to search user AND email.

Enclose terms containing special characters in double quotation marks:

search "john.doe+newsletter@company.com" source=otellogs
| fields body

The query returns the following results:

Combined phrase and Boolean search

Combine quoted phrases with Boolean operators for more precise searches:

search "User authentication" OR OAuth2 source=otellogs
| sort @timestamp
| fields body
| head 1

The query returns the following results:

Example 3: Boolean logic and operator precedence

The following queries demonstrate Boolean operators and precedence.

Boolean operators

Use OR to match documents containing any of the specified conditions:

search severityText="ERROR" OR severityText="FATAL" source=otellogs
| sort @timestamp
| fields severityText
| head 3

The query returns the following results:

Combine conditions with AND to require all criteria to match:

search severityText="INFO" AND `resource.attributes.service.name`="cart-service" source=otellogs
| fields body
| head 1

The query returns the following results:

Operator precedence

The operators are evaluated using the following precedence:

Parentheses > NOT > OR > AND

The following query demonstrates operator precedence:

search severityText="ERROR" OR severityText="WARN" AND severityNumber>15 source=otellogs
| sort @timestamp
| fields severityText, severityNumber
| head 2

The preceding expression is evaluated as (severityText="ERROR" OR severityText="WARN") AND severityNumber>15. The query returns the following results:

Example 4: NOT compared to != semantics

Both != and NOT operators find documents in which the field value is not equal to the specified value. However, the != operator excludes documents containing null or missing fields, while the NOT operator includes them. The following query shows this difference.

!= operator

Find all accounts for which the employer field exists and is not Quility:

search employer!="Quility" source=accounts

The query returns the following results:

NOT operator

Find all accounts that do not specify Quility as the employer (including those with null employer values):

search NOT employer="Quility" source=accounts

The query returns the following results. Dale Adams appears in the search results because his employer field is null:

Example 5: Range queries

Use comparison operators (>, <, >= and <=) to filter numeric and date fields within specific ranges. Range queries are particularly useful for filtering by age, price, timestamps, or any numeric metrics:

search severityNumber>15 AND severityNumber<=20 source=otellogs
| sort @timestamp
| fields severityNumber
| head 3

The query returns the following results:

The following query filters by decimal values within a specific range:

search `attributes.payment.amount`>=1000.0 AND `attributes.payment.amount`<=2000.0 source=otellogs
| fields body

The query returns the following results:

Example 6: Wildcards

The following queries demonstrate wildcard pattern matching. In wildcard patterns, * matches zero or more characters, while ? matches exactly one character.

Use * to match any number of characters at the end of a term:

search severityText=ERR* source=otellogs
| sort @timestamp
| fields severityText
| head 3

The query returns the following results:

Wildcard searches also work within text fields to find partial matches:

search body=user* source=otellogs
| sort @timestamp
| fields body
| head 2

The query returns the following results:

Use ? to match exactly one character in specific positions:

search severityText="INFO?" source=otellogs
| sort @timestamp
| fields severityText
| head 3

The query returns the following results:

Example 7: Wildcard patterns in field searches

When searching in text or keyword fields, wildcards enable partial matching, which is useful when you only know part of a value. Wildcards work best on keyword fields, for which they match the exact value using patterns. Using wildcards on text fields may produce unexpected results because they apply to individual tokens after analysis, not the entire field value. Wildcards in keyword fields are case sensitive unless normalized at indexing.

Leading wildcards (for example, *@example.com) can decrease query speed compared to trailing wildcards.

Find records for which you only know the beginning of a field value:

search employer=Py* source=accounts
| fields firstname, employer

The query returns the following results:

Combine wildcard patterns with other conditions for more precise filtering:

search firstname=A* AND age>30 source=accounts
| fields firstname, age, city

The query returns the following results:

Example 8: Field value matching

The IN operator efficiently checks whether a field matches any value in a list, providing a more concise and more performant alternative to chaining multiple OR conditions on the same field.

Check whether a field matches any value from a predefined list:

search severityText IN ("ERROR", "WARN", "FATAL") source=otellogs
| sort @timestamp
| fields severityText
| head 3

The query returns the following results:

Filter logs by severityNumber to find errors with a specific numeric severity level:

search severityNumber=17 source=otellogs
| sort @timestamp
| fields body
| head 1

The query returns the following results:

Search for logs containing a specific user email address in the attributes:

search `attributes.user.email`="user@example.com" source=otellogs
| fields body

The query returns the following results:

Example 9: Complex expressions

To create sophisticated search queries, combine multiple conditions using Boolean operators and parentheses:

search (severityText="ERROR" OR severityText="WARN") AND severityNumber>10 source=otellogs
| sort @timestamp
| fields severityText
| head 3

The query returns the following results:

Combine multiple conditions with OR and AND operators to search for logs matching either a specific user or high-severity fund errors:

search `attributes.user.email`="user@example.com" OR (`attributes.error.code`="INSUFFICIENT_FUNDS" AND severityNumber>15) source=otellogs
| fields body

The query returns the following results:

Example 10: Time modifiers

Time modifiers filter search results by time range using the implicit @timestamp field. They support various time formats for precise temporal filtering.

Absolute time filtering

Filter logs within a specific time window using absolute timestamps:

search earliest='2024-01-15 10:30:05' latest='2024-01-15 10:30:10' source=otellogs
| fields @timestamp, severityText

The query returns the following results:

Relative time filtering

Filter logs using relative time expressions, such as those that occurred before 30 seconds ago:

search latest=-30s source=otellogs
| sort @timestamp
| fields @timestamp, severityText
| head 3

The query returns the following results:

Time rounding

Use time rounding expressions to filter events relative to time boundaries, such as those before the start of the current minute:

search latest='@m' source=otellogs
| fields @timestamp, severityText
| head 2

The query returns the following results:

Unix timestamp filtering

Filter logs using Unix epoch timestamps for precise time ranges:

search earliest=1705314600 latest=1705314605 source=otellogs
| fields @timestamp, severityText

The query returns the following results:

Example 11: Escaping special characters

Special characters fall into two categories, depending on whether they must always be escaped or only when you want to search for their literal value:

• The following characters must always be escaped to be interpreted literally:
  • Backslash (\): Escape as \\.
  • Quotation mark ("): Escape as \" when used inside a quoted string.
• These characters act as wildcards by default and should be escaped only when you want to match them literally:
  • Asterisk (*): Use as * for wildcard matching; escape as \\* for a literal asterisk.
  • Question mark (?): Use as ? for wildcard matching; escape as \\? for a literal question mark.

The following table compares wildcard and literal character matching.

Escaping backslash characters

Each backslash in the search value must be escaped with another backslash. For example, the following query searches for Windows file paths by properly escaping backslashes:

search `attributes.error.type`="C:\\\\Users\\\\admin" source=otellogs
| fields `attributes.error.type`

The query returns the following results:

When using the REST API with JSON, additional JSON escaping is required.

Quotation marks within strings

Search for text containing quotation marks by escaping them with backslashes:

search body="\"exact phrase\"" source=otellogs
| sort @timestamp
| fields body
| head 1

The query returns the following results:

Text containing special characters

Search for literal text containing wildcard characters by escaping them:

search "wildcard\\* fuzzy~2" source=otellogs
| fields body
| head 1

The query returns the following results: