+++
title = "Query Logs"
updated = 2026-08-17
weight = 10
[extra]
weight = 14
+++

Query Logs show you the actual search terms your end users are typing into your application ranked by volume, with performance data for each query. It's the first place to look when you want to understand how your search is performing and where to improve it.

While you may store this data, it may not be easy for you to access otherwise. The Bonsai Query Logs feature surfaces this data directly in your Bonsai dashboard, without any additional instrumentation required.

{% admonition(title="BETA FEATURE") %}
_Query Logs is currently a beta feature that we are rolling out gradually. If you don't see query logs in your cluster dashboard, contact support to request access._
{% end %}

---

## Where to find it

Your query log results exist in two places: 

**On your cluster dashboard** — a preview of your top queries from the last 7 days appears as a widget on the cluster overview page.

{{ image(src="query-logs-dashboard.jpg", ratio="2096:1332", full=1, border=true) }}

_Click the "Queries" tab menu item, or the "View All" link in the panel to open the full report._

**In a weekly summary e-mail** — each week, Bonsai sends a summary across all of your clusters. For each cluster, you'll see top queries by volume, zero-hit queries, and total request volume compared to the prior week. Clusters with no query data in the period will show "No data.”

---

## Reading the Queries table

The Queries page shows one row per unique query, sorted by volume (descending) by default. In the full report view on the _Queries_ tab, you can filter by **1 day**, **7 days**, **14 days**, or **30 days** at the top of the page.

| Column | What it means |
| --- | --- |
| **Query** | The search term your user typed, extracted and normalized* from the raw request |
| **Volume** | How many times this query was run in the selected time window |
| **Duration** | Average response time for this query, in milliseconds |
| **Hits** | Average number of results returned per search for this query |

*Bonsai normalizes queries before grouping them. **Normalization** means that `Shoes`, `shoes`, and `SHOES` are counted as the same query. Whitespace differences are also merged. You cannot edit normalization rules. Bonsai applies a single consistent extractor across all clusters.

---

## **How to use your query data**

- **High volume + low hits** is the clearest signal of a relevancy problem. Users are searching for something frequently and not finding it. Start here.
- **Zero-hit queries** are your highest-priority fix target. Users searched and came up completely empty — common causes are missing synonyms, content gaps, or language mismatches. For multilingual gaps, consider [vector search.](https://bonsai.io/docs/ai-search/vector-search/)
- **High volume + high hits** doesn't guarantee search is working — it means results are being returned, not that they're useful. Click-through data is not available in this release.
- **Short duration (under ~50ms)** generally indicates a fast, well-structured query. Consistently above 500ms is worth investigating: look at your Request Duration Profiles in your [Cluster Metrics Dashboard](https://bonsai.io/docs/features/dashboard-metrics#request-duration-percentiles) to see how the query is performing compared to your p50, p95, and p99 profiles. Note that we aggregate all traffic (searches, which comprise your queries, and writes) in these profiles.
- **Queries you don't recognize** are normal. Your cluster may be receiving programmatic queries alongside user-typed searches. Queries with no extractable user text don't appear in the table, for example: any query with `size: 0`, filters without text values, or reports that aggregate.

For a deeper walkthrough on improving relevance with query data, see [Announcing Query Logs](https://bonsai.io/blog/announcing-query-logs) on the Bonsai blog.

---

## Export your data

In the full view, the **Export** button downloads a CSV of all queries in the selected time window, sorted by volume. Large exports are delivered as a download link.

{{ image(src="query-logs-full-view.jpg", ratio="1900:1007", full=1, border=true) }}

---

## Explicitly declaring the user query

While we've done our best to detect the user query from an OpenSearch or Elasticsearch QueryDSL, it may not be exactly what you want. For example if you're using vector search, the user query might have been replaced by a vector!

So, we've added a special feature that allows you to specify exactly what gets aggregated in query logs.  Just set the value to `ext.bonsai.user_query` in your QueryDSL:

```json
{
   "ext":{
     "bonsai":{
       "user_query":"YOUR VALUE HERE"
     }
   },
   "query":{...}
}
```

When the above is used, the `user_query` value will be taken instead of looking in the query body.

---

## FAQ

**Why don't I see Query Logs in my dashboard?**
A few possible causes: your cluster may be on an unsupported version, the feature may have been explicitly disabled via a cluster attribute,  or your application may not be sending queries with an extractable user query term. The most common fix is to instrument your application to send the `ext.bonsai` user query field — see [link to doc] for how to do that.

**Why does my cluster show "No data"?**
Either no queries with extractable user text ran in the selected time window, or your application isn't sending the `ext.bonsai` user query field. Adding that field is the fastest way to get meaningful data into Query Logs. If you've done that and still see nothing, **contact support.**

**Can I see who ran a specific query?**
No. Query Logs shows aggregate data only — no user-agent breakdowns, IP addresses, or per-user detail. Individual query drill-down is not available in this release.

**Can I edit how my queries are normalized?**
No. Normalization rules are applied consistently by Bonsai and are not configurable per cluster in this release.

**Is there a cost to use Query Logs?**
No. Query Logs is included at no additional charge.

**What's coming next?**
Query Logs is the first step in Bonsai's search relevancy tools. Future releases will build on this data to help you identify patterns, understand what your users are trying to accomplish, and improve your search results — automatically.