You're viewing version 3.6 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
mvexpand
The mvexpand command expands each value in a multivalue (array) field into a separate row. For each document, every element in the specified array field is returned as its own row.
Syntax
The mvexpand command has the following syntax:
mvexpand <field> [limit=<int>]
Parameters
The mvexpand command supports the following parameters.
| Parameter | Required/Optional | Description |
|---|---|---|
<field> | Required | The multivalue (array) field to expand. |
limit | Optional | The maximum number of values per document to expand. If not specified, all array elements are expanded. |
Example 1: Using basic expansion
The following query creates an array and expands it into separate rows:
source=people
| eval tags = array('error', 'warning', 'info')
| fields tags
| head 1
| mvexpand tags
| fields tags
The query returns the following results:
| tags |
|---|
| error |
| warning |
| info |
Example 2: Limiting the number of expanded rows
The following query expands an array while limiting the number of expanded rows:
source=people
| eval ids = array(1, 2, 3, 4, 5)
| fields ids
| head 1
| mvexpand ids limit=3
| fields ids
The query returns the following results:
| ids |
|---|
| 1 |
| 2 |
| 3 |
Example 3: Expanding nested fields
The following query expands a multivalue projects field into one row per project:
source=people
| head 1
| fields projects
| mvexpand projects
| fields projects.name
The query returns the following results:
| projects.name |
|---|
| AWS Redshift Spectrum querying |
| AWS Redshift security |
| AWS Aurora security |
Example 4: Single-value array
A single-element array expands to one row:
source=people
| eval tags = array('error')
| fields tags
| head 1
| mvexpand tags
| fields tags
The query returns the following results:
| tags |
|---|
| error |
Example 5: Missing fields
The following query attempts to expand a field that does not exist in the input schema:
source=people
| eval some_field = 'x'
| fields some_field
| head 1
| mvexpand tags
| fields tags
The query throws the following semantic check exception:
{'reason': 'Invalid Query', 'details': "Field 'tags' not found in the schema", 'type': 'SemanticCheckException'}
Related commands
nomv– Converts a multivalue field into a single-value stringmvcombine– Combines multiple rows into a single row with multivalue fields