When a document field holds multiple values of the same type — such as a book's genre tags or a product's category labels — map that field to an ARRAY type. OpenSearch indexes each element independently, so a query matching any one element returns the document.
Example: A novel tagged "Mystery", "Time-travel", and "Classical" appears in results when a user searches for "Mystery" alone.
Push ARRAY data
Call API operations
Submit the array field as a JSON array in the fields object. Set cmd to ADD.
[
{
"fields": {
"id": "0",
"int_array": [14, 85],
"float_array": [14.0, 85.0],
"literal_array": ["abc", "xyz"]
},
"cmd": "ADD"
}
]For the full API reference, see Process data.
Use SDKs
The push process follows the same pattern across SDK languages. For a Java example, see Demo code for pushing data.
In Java, map each ARRAY field to its corresponding Java array type:
| OpenSearch field | Java type |
|---|---|
literal_array | String[] |
int_array | int[] |
Configure data sources
When using a data source connector, associate the MultiValueSpliter plug-in with the ARRAY-type field and set a delimiter. The plug-in splits the delimited string from your database and converts it to an ARRAY value that the search engine can index.
For example, if the source database stores tags as "Time-travel,Mystery,Romantic", set the delimiter to a comma (,):
For setup instructions, see Use data processing plug-ins.
Query ARRAY fields
Use a query clause or a filter clause to match individual elements. The following examples use a document with a tags field containing "Time-travel", "Mystery", and "Romantic", and a title field containing "Treading On Thin Ice".
Query clause only — match on a single tag:
query=tags:'Time-travel'Combined query and filter — match on title and filter by tag:
query=title:'Treading On Thin Ice'&&filter=tags="Time-travel"
Return value format: Search results return ARRAY field values as tab-separated strings (\t), not as JSON arrays. Split on \t in your application code to retrieve individual elements.
To count the elements in an ARRAY field, use the fieldlen function in a filter clause. See filter clause for the full syntax.
FAQ
Why is TEXT_ARRAY unavailable, and how does TEXT differ from STRING_ARRAY?
TEXT types (TEXT, SHORT_TEXT, NWS_TEXT, MWS_TEXT) run through an analysis pipeline that supports fuzzy matching. Because analysis operates on the whole field value, multi-value semantics do not apply — there is no TEXT_ARRAY. STRING_ARRAY, by contrast, performs exact matching on each element individually. An element can contain multiple terms, and not all elements need to match for the document to be returned.