# Gaining insights with search analytics
**Note**
Feature support varies by index type and search API being used. To see if this feature is supported for the index type and search API you’re using, see [Index types](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html).
You can use Amazon Kendra search *Analytics* to gain insights on how your search application is successfully or unsuccessfully helping your users find information.
Amazon Kendra Analytics provide a snapshot of how your users interact with your search application and how effective your search application configuration is. You can view the metrics data using the [GetSnapshots](https://docs.aws.amazon.com/kendra/latest/APIReference/API_GetSnapshots.html) API or by selecting **Analytics** on the navigation panel in the console.
You can render the data generated by `GetSnapshots` on your own custom-built dashboard. Or you can use the metrics dashboard provided in the console, which includes visual graphs. With a visual dashboard, you can look for trends or patterns in user behavior over time or surface problems with your search application configuration. For example, a line graph that shows a consistent number of queries per day and a steady increase might indicate increased adoption and usage. On the other hand, an abrupt drop might indicate there's an issue that must be investigated.
You can use the metrics to make connections between different points of data to solve problems with how your users query for information or discover business opportunities. For example, the document 'How does AI work?' is the most clicked on document in the search results, and the top searched query is 'How does machine learning work?'. This informs you on the preferred terms and language your users use. You can integrate these terms in your documents or use custom synonyms for these terms to make your documents more searchable for your users.
## Metrics for search
There are 10 metrics for analyzing your search application's performance or what information your users are searching for. To retrieve the metrics data, you specify the string name of the metric data you want to retrieve when you call `GetSnapshots`.
You also must provide a time interval or time window to view the metrics data. The time interval uses the time zone of your index. You can view data in the following time windows:
+ `THIS_WEEK`: The current week, starting on the Sunday and ending on the day before the current date.
+ `ONE_WEEK_AGO`: The previous week, starting on the Sunday and ending on the following Saturday.
+ `TWO_WEEKS_AGO`: The week before the previous week, starting on the Sunday and ending on the following Saturday.
+ `THIS_MONTH`: The current month, starting on the first day of the month and ending on the day before the current date.
+ `ONE_MONTH_AGO`: The previous month, starting on the first day of the month and ending on the last day of the month.
+ `TWO_MONTHS_AGO`: The month before the previous month, starting on the first day of the month and ending on last day of the month.
In the console, the supported time windows are **This week**, **Previous week**, **This month**, **Previous month**.
### Click-through rate
The proportion of queries that lead to click-through to a document in the search results. This helps you understand if your search application configuration helps your users find information relevant to their queries. For queries that return instant answers, users might not need to click through to a document for more information. For more information, see [Instant answer rate](#search-instant-answer-rate). You must call [SubmitFeedback](https://docs.aws.amazon.com/kendra/latest/APIReference/API_SubmitFeedback.html) to ensure that click-through feedback is collected.
To retrieve data on click-through rate using the `GetSnapshots` API, specify the `metricType` as `AGG_QUERY_DOC_METRICS`. You can also view this metric in the console by selecting **Analytics** on the navigation panel.
### Zero click rate
The proportion of queries that lead to zero clicks in the search results. This helps you understand gaps in your content providing irrelevant search results. For queries that return instant answers, users might not need to click through to a document for more information. For more information, see [Instant answer rate](#search-instant-answer-rate). Also, your search settings, such as tuning configurations, could have an impact on how documents are returned in the search results.
To retrieve data on zero click rate using the `GetSnapshots` API, specify the `metricType` as `AGG_QUERY_DOC_METRICS`. You can also view this metric in the console by selecting **Analytics** on the navigation panel.
### Zero search results rate
The proportion of queries that lead to zero search results. This helps you understand gaps in your content providing no relevant search results.
To retrieve data on zero search results rate using the `GetSnapshots` API, specify the `metricType` as `AGG_QUERY_DOC_METRICS`. You can also view this metric in the console by selecting **Analytics** on the navigation panel.
### Instant answer rate
The proportion of queries with an instant answer or FAQ returned. This helps you understand the role of instant answers in providing information.
To retrieve data on instant answer rate using the `GetSnapshots` API, specify the `metricType` as `AGG_QUERY_DOC_METRICS`. You can also view this metric in the console by selecting **Analytics** on the navigation panel.
### Top queries
The top 100 queries searched by your users. This helps you understand which queries are popular and the kind of information your users are most interested in.
Metrics include the number of times the query is searched, the proportion of click-throughs to a document, the proportion of no click-throughs to a document, the average click depth in the search results for the query, the proportion of instant answers for the query, and the average confidence for the first 10 search results for a query.
To retrieve data on top queries using the `GetSnapshots` API, specify the `metricType` as `QUERIES_BY_COUNT`. You can also view this metric in the console by selecting **Analytics** on the navigation panel in the console, then selecting **Top queries** under **Query lists**.
### Top queries with zero clicks
The top 100 queries that lead to zero clicks in the search results. This helps you understand any gaps in your content, where there’s a lack of documents relevant to some queries or your search application configuration is returning irrelevant search results. For queries that return instant answers, users might not need to click through to a document for more information. For more information, see [Instant answer rate](#search-instant-answer-rate).
Metrics include the number of times the query leads to zero clicks, the proportion of zero clicks for the query, the proportion of instant answers for the query, and the average confidence for the first 10 search results for a query.
To retrieve data on top queries with zero clicks using the `GetSnapshots` API, specify the `metricType` as `QUERIES_BY_ZERO_CLICK_RATE`. You can also view this metric in the console by selecting **Analytics** on the navigation panel in the console, then selecting **Top zero click queries** under **Query lists**.
### Top queries with zero search results
The top 100 queries that lead to zero search results. This helps you understand any gaps in your content, where there are no documents relevant to some queries. Or, your users might query with specialized terms that possibly lead to no search results, prompting you to create [custom synonyms](https://docs.aws.amazon.com/kendra/latest/dg/index-synonyms.html) to handle this.
Metrics include the number of times the query leads to zero search results, the proportion of zero search results for the query, and the proportion of times the query is searched compared to all queries.
To retrieve data on top queries with zero search results using the `GetSnapshots` API, specify the `metricType` as `QUERIES_BY_ZERO_RESULT_RATE`. You can also view this metric in the console by selecting **Analytics** on the navigation panel in the console, then selecting **Top zero result queries** under **Query lists**.
### Top clicked on documents
The top 100 most clicked on documents in the search results. This helps you understand which documents or search results are most relevant to your users when they query for information.
Metrics include the number of times the document is clicked on, the number of likes a document receives from your users (thumbs up), the number of dislikes a document receives from your users (thumbs down).
To retrieve data on top clicked on documents using the `GetSnapshots` API, specify the `metricType` as `DOCS_BY_CLICK_COUNT`. You can also view this metric in the console by selecting **Analytics** on the navigation panel in the console, then selecting **Top clicked documents** under **Query lists**.
### Total queries
The total number of queries searched by your users. This helps you understand how engaged your users are with your search application.
To retrieve data on total queries using the `GetSnapshots` API, specify the `metricType` as `AGG_QUERY_DOC_METRICS`. You can also view this metric in the console by selecting **Analytics** on the navigation panel.
### Total documents
The total number of documents in your index. This helps you compare the size of your index to the total number of queries to check if there is an appropriate number of documents for the volume of queries.
To retrieve data on total documents using the `GetSnapshots` API, specify the `metricType` as `AGG_QUERY_DOC_METRICS`. You can also view this metric in the console by selecting **Analytics** on the navigation panel.
### Example of retrieving metric data
The following code is an example of retrieving data on the top queries for the previous month.
------
#### [ Console ]
**To retrieve top queries for the previous month**
1. In the left navigation pane, under **Indexes**, select your index, and then select **Analytics**.
1. On the **Analytics** page, select the button **This week**, to change the time window for retrieving the data to **Previous month**.
1. On the **Analytics** page, under **Query lists**, select **Top queries**.
------
#### [ CLI ]
**To retrieve top queries for the previous month**
```
aws kendra get-snapshots \
--index-id index-id \
--interval "ONE_MONTH_AGO" \
--metric-type "QUERIES_BY_COUNT"
```
------
#### [ Python ]
**To retrieve top queries for the previous month**
```
import boto3
kendra = boto3.client("kendra")
index_id = "index-id"
interval = "ONE_MONTH_AGO"
metric_type = "QUERIES_BY_COUNT"
snapshots_response = kendra.get_snapshots(
IndexId = index_id,
Interval = interval,
MetricType = metric_type
)
print("Top queries data: " + snapshots_response["snapshotsData"])
```
------
#### [ Java ]
**To retrieve top queries for the previous month**
```
package com.amazonaws.kendra;
import software.amazon.awssdk.services.kendra.KendraClient;
import software.amazon.awssdk.services.kendra.model.GetSnapshotsRequest;
import software.amazon.awssdk.services.kendra.model.GetSnapshotsResponse;
public class TopQueriesExample {
public static void main(String[] args) {
KendraClient kendra = KendraClient.builder().build();
String indexId = "indexID";
String interval = "ONE_MONTH_AGO";
String metricType = "QUERIES_BY_COUNT";
GetSnapshotsRequest getSnapshotsRequest = GetSnapshotsRequest
.builder()
.indexId(indexId)
.interval(interval)
.metricType(metricType)
.build();
GetSnapshotsResponse getSnapshotsResponse = kendra.getSnapshots(GetSnapshotsRequest);
System.out.println(String.format("Top queries data: ", getSnapshotsResponse.snapshotsData()))
```
------
## From metrics to actionable insights
Actionable insights are meaningful pieces of information extracted from raw data and are used to guide your actions or decisions. To extract meaning from the metrics and use them to drive actionable insights, it is important to not only look at the metrics in isolation but also make connections among the metrics.
For example, the top query with zero clicks is 'Which regions are currently available?'. However, it also has a 100 percent instant answer rate. This suggests your users receive the answer to this question without needing to click on a search result or document that provides information on available regions. If you looked at zero clicks alone, you would not get the full story and possibly make the wrong conclusions about the success of your search application configuration in handling this query.
Another example of an actionable insight is discovering a business opportunity. Businesses often look for opportunities to grow their customers by analyzing search metrics. The most clicked on document is 'Available regions'. In addition to this, most of the top searched queries are related to questions on product availability in the Oceanic region, with 100 percent instant answer rates and a high click-through rate to more information on available regions as part of the answer. This suggests there's interest and demand for your product or service in this region.
## Visualizing and reporting search analytics
There are five metrics that include trends data for you to visualize and look for trends or patterns over time. If you use the console, graphs of the trends data are provided. If you use the APIs, you can retrieve the trends data to create your own graphs or visualizations. Most graphs in the console plot the daily data points over your chosen time window.
The console provides a dashboard of the metrics where you can select a graph and top list you are interested in viewing. You can export the metrics shown on your dashboard in CSV format by selecting **Export** on the **Analytics** home page. You can include these reports in your business documents or presentations.
You can visualize the following metrics:
### Total queries graph
A line graph of the number of queries issued per day. The graph helps you visualize patterns in daily user engagement. Some examples include a steady increase or decrease in user engagement, or a drastic drop to 0 queries due to a crash of your search application or issues with your website.
If you use the API, you can retrieve these data by specifying `TREND_QUERY_DOC_METRICS`. You can use the data to create your own graphs, or use the graphs provided in the console.
### Click-through rate graph
A line graph of the proportions of click-throughs per day. The graph helps you visualize patterns in daily click-through rate. Some examples include a steady increase or decrease in click-through rate, or a decrease in instant answers possibly influencing an increase in click-through.
If you use the API, you can retrieve these data by specifying `TREND_QUERY_DOC_METRICS`. You can use the data to create your own graphs, or use the graphs provided in the console.
### Zero click rate graph
A line graph of the proportion of zero clicks per day. The graph helps you visualize patterns in daily zero click rate. Some examples include a steady increase or decrease in zero click rate, or an increase in instant answers possibly influencing an increase in zero clicks.
If you use the API, you can retrieve these data by specifying `TREND_QUERY_DOC_METRICS`. You can use the data to create your own graphs, or use the graphs provided in the console.
### Zero search results rate graph
A line graph of the proportion of zero search results per day. The graph helps you visualize patterns in daily zero search results rate. Some examples include a steady increase or decrease in zero search results rate, or a sharp decrease in the number of documents in your index possibly influencing an increase in zero search results.
If you use the API, you can retrieve these data by specifying `TREND_QUERY_DOC_METRICS`. You can use the data to create your own graphs, or use the graphs provided in the console.
### Instant answer rate graph
A line graph of the proportion of queries with an instant answer or FAQ returned. The graph helps you visualize patterns in daily instant answer rate. Some examples include steady increase or decrease in question-answer type queries, or a decrease in click-throughs possibly influencing an increase in instant answers.
If you use the API, you can retrieve these data by specifying `TREND_QUERY_DOC_METRICS`. You can use the data to create your own graphs, or use the graphs provided in the console.