What Are OpenSearch Queries?
OpenSearch queries are requests sent to an OpenSearch cluster to search, filter, and analyze data. OpenSearch supports multiple query interfaces, but the primary and most flexible native option is Query DSL (Domain-Specific Language), which uses a JSON format inside the HTTP request body.
The structure and capabilities of OpenSearch queries are designed to accommodate diverse requirements. Users can write queries using different syntaxes and paradigms, such as a JSON-based Query DSL, SQL-like syntax, or a pipe-based query language. Each approach offers unique benefits and caters to different technical backgrounds and use cases
Main Ways to Query OpenSearch
1. Query DSL
Query DSL is the native JSON-based language for querying OpenSearch. It provides the most complete access to search features, including full-text search, exact matching, filtering, scoring, aggregations, nested queries, and geospatial searches. Query DSL is typically used through the OpenSearch REST API and is the preferred option when applications need precise control over search behavior.
A simple match query searches an analyzed text field for relevant documents:
|
1 2 3 4 5 6 7 8 |
GET /catalog/_search { "query": { "match": { "product_summary": "noise cancelling earbuds" } } } |
For exact filtering, a term query matches a specific value without text analysis:
|
1 2 3 4 5 6 7 8 |
GET /catalog/_search { "query": { "term": { "department.keyword": "audio" } } } |
2. OpenSearch SQL
OpenSearch SQL lets users query indexed data using SQL syntax. This approach is useful for people who already work with relational databases and want to analyze OpenSearch data without learning Query DSL. SQL supports operations such as filtering, sorting, grouping, joins on supported data sources, and aggregations, making it well suited for reporting and ad hoc analysis.
The following example retrieves products in the electronics category and sorts them by price:
|
1 2 3 4 |
SELECT product_name, stock_quantity FROM inventory WHERE brand = 'Acme' ORDER BY stock_quantity DESC; |
SQL queries can be submitted through the SQL plugin endpoint or compatible clients, and OpenSearch translates them into the appropriate search operations internally.
3. OpenSearch PPL
PPL (Piped Processing Language) is a pipeline-oriented query language designed for exploratory analysis. It uses a sequence of commands connected by pipes, making it easy to build queries step by step. PPL is commonly used for log analysis, security investigations, and operational troubleshooting because it supports filtering, field selection, aggregations, sorting, and statistical operations in a readable format.
The following example filters error logs, counts occurrences by service, and sorts the results:
|
1 2 3 4 |
source=application_events | where status = 'FAILED' | stats count() by component | sort -count |
PPL emphasizes data processing pipelines rather than nested query structures, making complex analysis easier to read and modify as additional processing steps are added.
Query DSL vs. SQL vs. PPL: How to Choose
The best query language depends on the task you need to perform:
- Query DSL provides the most complete access to OpenSearch features and is the standard choice for application development. It supports advanced search capabilities such as relevance tuning, nested queries, vector search, highlighting, and complex aggregations that may not be fully exposed through other query languages.
- OpenSearch SQL is a good fit for users with SQL experience who need to query indexed data for reporting, dashboards, or ad hoc analysis. It offers familiar syntax and can simplify data exploration, but some OpenSearch-specific features are easier or only possible to express with Query DSL.
- OpenSearch PPL is intended for interactive data exploration and operational analysis. Its pipe-based syntax makes it easy to build processing pipelines that filter, transform, aggregate, and sort data in a logical sequence. This makes PPL especially useful for investigating logs, monitoring systems, and security events.
Many teams use more than one query language. Developers often use Query DSL in applications, while analysts use SQL for reporting and PPL for troubleshooting and exploratory analysis. Since all three operate on the same underlying data, you can choose the interface that best matches your workflow without changing how the data is stored.
Tips from the expert
Kassian Wren
Open Source Technology Evangelist
Kassian Wren is an Open Source Technology Evangelist specializing in OpenSearch. They are known for their expertise in developing and promoting open-source technologies, and have contributed significantly to the OpenSearch community through talks, events, and educational content.
In my experience, here are tips that can help you better adapt to OpenSearch queries:
- Profile slow queries before optimizing them: Use the Profile API to see where execution time is spent: query execution, scoring, aggregation, or fetching documents. Many “slow query” problems turn out to be mapping or shard issues rather than inefficient query syntax.
- Prefer filter context whenever relevance isn’t needed: Authentication checks, tenant isolation, status filters, and time windows should almost always run in the
filterclause. This enables caching and avoids unnecessary scoring, significantly improving query performance under load. - Push expensive filtering into index design: If users repeatedly filter by a calculated value (such as severity, region, or customer tier), compute and index that field during ingestion instead of using runtime scripts or complex query logic on every search.
- Control shard fan-out for time-series searches: Even efficient queries become slow when they touch hundreds of shards. Organize logs and metrics into time-based indexes so most searches only access a small subset of the cluster.
- Choose analyzers based on search behavior, not language alone: Many search quality issues originate from analyzer selection. Product catalogs, log messages, usernames, and free-form text often require different analyzers, and using a single default analyzer rarely produces the best relevance.
Common OpenSearch Query Examples
Search Documents by Keyword
A match query performs a full-text search against analyzed fields. It is the most common way to search for documents containing specific words or phrases.
|
1 2 3 4 5 6 7 8 |
GET /knowledge-base/_search { "query": { "match": { "body": "distributed search setup" } } } |
This query analyzes the search terms using the field’s analyzer and returns documents ranked by relevance.
Filter Logs by Time Range and Service
A bool query can combine multiple filters. Using the filter clause avoids relevance scoring and is efficient for structured conditions such as timestamps and service names.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
GET /system-events/_search { "query": { "bool": { "filter": [ { "term": { "application.keyword": "order-service" } }, { "range": { "event_time": { "gte": "now-6h", "lt": "now" } } } ] } } } |
This query returns log entries from the order-service service generated during the last 6 hours.
Search Exact IDs or Status Values
Use a term query when matching exact values such as document IDs, status codes, tags, or keyword fields. Unlike match, the value is not analyzed.
|
1 2 3 4 5 6 7 8 |
GET /shipments/_search { "query": { "term": { "delivery_status.keyword": "in_transit" } } } |
To retrieve a document by its ID, use the ids query:
|
1 2 3 4 5 6 7 8 |
GET /shipments/_search { "query": { "ids": { "values": ["SHP-7845", "SHP-9210"] } } } |
Combine Text Search with Filters
A bool query lets you combine a full-text search with one or more filters. This is a common pattern because it limits results without affecting relevance scores.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
GET /store-items/_search { "query": { "bool": { "must": { "match": { "product_details": "ergonomic office chair" } }, "filter": [ { "term": { "manufacturer.keyword": "Herman Miller" } }, { "range": { "unit_price": { "lt": 1500 } } } ] } } } |
This query searches for products whose details match “ergonomic office chair” while only returning Herman Miller priced at $1,500 or less.
OpenSearch Query Performance Best Practices
Here are some useful practices to keep in mind when using OpenSearch queries.
1. Use Filters for Exact Constraints
Use filter clauses for conditions that do not need relevance scoring, such as status, service name, tenant ID, date range, or numeric limits. Filters are faster for exact constraints because OpenSearch can cache them and skip score calculation.
This pattern is common in log search, multi-tenant applications, and dashboards. The query below limits results to production environment created in the last 12 hours, without changing relevance scores.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
{ "query": { "bool": { "filter": [ { "term": { "environment.keyword": "production" } }, { "range": { "event_time": { "gte": "now-12h" } } } ] } } } |
2. Query Keyword Fields for Exact Matches
Use keyword fields when matching exact values. Text fields are analyzed, so values may be split, lowercased, or transformed before indexing. This is useful for full-text search but can produce unexpected results for IDs, tags, usernames, statuses, and service names.
The example below searches for the exact deployment region of eu-central-1. This avoids matching partial tokens or analyzed variants.
|
1 2 3 4 5 6 7 |
{ "query": { "term": { "deployment_region.keyword": "eu-central-1" } } } |
3. Avoid Leading Wildcards and Limit Expensive Regex Queries
Leading wildcards force OpenSearch to scan many terms, which can make queries slow on large indexes. Prefer prefix queries, n-grams, edge n-grams, or dedicated search fields when users need partial matching.
The following query is more efficient than a leading wildcard search because OpenSearch can look for terms that start with a known prefix.
|
1 2 3 4 5 6 7 |
{ "query": { "prefix": { "product_code.keyword": "SKU-24" } } } |
Avoid patterns such as *error or broad regular expressions unless the field has low cardinality and the query is tightly scoped.
4. Use Aggregations Efficiently
Aggregations can be expensive because they process many matching documents. Narrow the query first with filters, aggregate on keyword or numeric fields, and keep bucket counts small when possible.
The example below filters results to the last seven days before grouping documents by region. It also sets size to 0 because the response only needs aggregation results, not individual documents.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "size": 0, "query": { "range": { "event_time": { "gte": "now-7d", "lt": "now" } } }, "aggs": { "events_by_region": { "terms": { "field": "region.keyword", "size": 5 } } } } |
5. Align Query Patterns with Index Design
Design indexes around the queries they need to support. Fields used for filtering, sorting, and aggregations should have suitable mappings, such as keyword, numeric, date, or boolean types. Full-text fields should use analyzers that match how users search. A well-designed index often has a greater impact on query performance than small query optimizations.
For example, storing identifiers as keyword fields instead of analyzed text allows exact lookups to execute more efficiently. Similarly, choosing the correct analyzer for text fields improves search relevance while reducing the need for complex query logic. For time-series data, use time-based indexes so queries can target only the relevant date range. This reduces the number of shards searched and improves performance for logs, metrics, and events.
As query patterns evolve, periodically review index mappings and shard layouts to ensure they still match the application’s workload.
6. Return Only the Fields You Need
Large response payloads increase latency and network cost. Use _source filtering to return only the fields required by the application or dashboard. This is useful when documents contain large text fields, nested objects, or raw event payloads. The query below returns only the ticket ID, priority, and assigned_team for completed orders.
|
1 2 3 4 5 6 7 8 |
{ "_source": ["ticket_id", "priority", "assigned_team"], "query": { "term": { "priority.keyword": "high" } } } |
7. Paginate Large Result Sets Carefully
Avoid deep pagination with large from values because OpenSearch must still collect and sort skipped results. This becomes expensive as users move deeper into the result set.
For large exports or scrolling through many results, use search_after with a stable sort order. The example below returns the next page after the last sort values from the previous response.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "size": 50, "sort": [ { "event_time": "desc" }, { "record_id.keyword": "asc" } ], "search_after": [ "2026-07-12T18:30:00Z", "evt-90871" ] } |
8. Use a Managed OpenSearch Solution for Production Workloads
Production OpenSearch clusters need ongoing tuning, scaling, backups, security configuration, monitoring, and version management. A managed OpenSearch service can reduce this operational work by handling infrastructure tasks such as node provisioning, patching, failure recovery, and storage scaling.
Managed platforms also provide features such as automated snapshots, built-in monitoring, access control, and high-availability deployments. These capabilities improve reliability while reducing the operational effort required to maintain a production cluster This is particularly valuable as data volumes and query traffic increase. Instead of spending time managing infrastructure, teams can focus on improving index design, optimizing queries, and building features that deliver value to users.
Run and Scale OpenSearch Queries with Instaclustr Managed OpenSearch
Writing efficient queries is only part of the challenge; running them reliably in production means managing clusters, scaling, security, and monitoring at the same time. NetApp Instaclustr delivers fully managed, production-ready OpenSearch clusters that power everything from log analytics and application monitoring to advanced semantic search, so teams can focus on query design and building features instead of operating infrastructure. The service runs 100% open source OpenSearch with no vendor lock-in, on your cloud provider account, ours, or on-prem.
Key capabilities of Instaclustr Managed OpenSearch:
- Fast, production-ready deployment: Spin up production-ready OpenSearch clusters in minutes without advanced technical skills, using the console, API, or Terraform provider.
- Flexible scaling: Adapt to fluctuating workloads with dynamic scaling options across on-prem, cloud, and hybrid environments, so query traffic and data growth are handled without disruption.
- Optimized configuration and performance: Clusters are tuned for reliability, performance, and security based on years of experience operating tens of millions of node hours, with proactive monitoring to keep queries running at peak efficiency.
- High-availability SLAs: Up to 99.999% availability SLA and up to 99% latency SLAs for read/write transactions to a maintained index within a specified latency threshold.
- Enterprise-grade security: Built-in security features including PCI-DSS compliance, Private Network Clusters, and compliance with SOC2, ISO27001, and ISO27018 standards.
- AI-powered search: An integrated pipeline to ingest, vectorize, and search data, with vector search and AI capabilities directly within OpenSearch to power semantic search, RAG, and chatbots.
- Searchable snapshots and hourly backups: Query snapshot data stored in remote storage without a full restore, backed by scheduled hourly backups of all OpenSearch data.
- Plugin framework and special purpose nodes: A range of OpenSearch plugins that can be enabled through the console, API, or Terraform, plus dedicated special purpose node types to optimize cluster configuration and query performance.
- Integrated OpenSearch Dashboards: Easily add an OpenSearch Dashboards node to visualize and navigate query results across formats such as histograms, pie charts, line graphs, geospatial views, and time series.
Ready to run your OpenSearch queries on a fully managed, optimized cluster? Explore Instaclustr Managed OpenSearch to deploy, secure, and scale your search workloads with 24/7 expert support.
