# Custom Analytics

<figure><img src="/files/fq2X53a7j2MR6zuaeNi3" alt=""><figcaption></figcaption></figure>

***

## Key Highlights

* Ask questions in plain language and the **AI Assistant** writes the SQL for you.
* Use SQL to query your BoxHero data.
* Combine conditions (e.g. item, attribute, price, date range, partner) to define the data you want to return as a custom report.
* Save queries you use often and open them again at any time.
* Export results to Excel for additional analysis or reporting.

## Use Cases

The standard <mark style="color:$primary;">`Inventory Reports`</mark> feature gives you a quick view of key metrics like average stock quantity and inventory turnover for a selected period. Because those reports use predefined formulas and fields, they may not cover every type of analysis your team needs.

<mark style="color:$primary;">`Custom Analytics`</mark> gives you more control over how you explore your data. It’s especially useful when:

* You can’t find the data you need in the standard [Inventory Reports](/docs/other-features/analytics.md)
* You want to filter or group data by item, supplier, customer, team member, or other detailed conditions
* You need time-based analysis such as monthly, quarterly, or year-over-year
* You want to save reports you rely on and use them again
* You need flexible data to support reporting or decision-making

***

## How to Use Custom Analytics

### 1. Getting Started

Go to <mark style="color:$primary;">`Reports`</mark> > <mark style="color:$primary;">`Custom Analytics`</mark>. This opens a new workspace where you can create and manage your SQL queries. Then, select <mark style="color:$primary;">`+ New`</mark> to create a new query.

<figure><img src="/files/hUMqtrACXaGmyuYTpvHk" alt=""><figcaption></figcaption></figure>

### 2. Write a Query

You have two ways to write queries:

1. **Use the AI Assistant** to generate SQL from a plain-language question (recommended for most users).
2. **Write SQL directly** using [DuckDB SQL](https://duckdb.org/docs/stable/sql/introduction).

<figure><img src="/files/3CXXxc60Cygriv8PzFxW" alt=""><figcaption></figcaption></figure>

#### Using the AI Assistant

The <mark style="color:$primary;">`AI Assistant`</mark> turns plain-language questions into working SQL queries. You don't need to know SQL to use it.&#x20;

Type your question in the assistant panel and press enter. The assistant generates the SQL, applies it to the editor, and runs it. Results appear below the query.

You can edit the generated SQL before saving if you want to adjust anything.

{% embed url="<https://customer-0jrbilsa8yt3k758.cloudflarestream.com/38e5c1fa675d1d7f16b1d9e95a6aabd4/iframe?autoplay=true&controls=false&letterboxColor=transparent&loop=true&muted=true&poster=https://customer-0jrbilsa8yt3k758.cloudflarestream.com/38e5c1fa675d1d7f16b1d9e95a6aabd4/thumbnails/thumbnail.jpg?height=1080&preload=true>" %}

**Example Questions**

* Items below safety stock level
* What hasn't sold in the last 90 days?
* Top 10 SKUs by units sold this month
* Open POs past their expected arrival date
* Stock levels by location&#x20;

#### Building Reusable Queries

You can ask the assistant to include adjustable filters in a query, such as date ranges or partner names. The assistant uses Query Variables so you can change the inputs later without rewriting the SQL.

For example, asking *"sales by item for a date range I can change"* generates a query with a date variable that prompts for input each time the query runs.

<figure><img src="/files/4TNkl60okOYWnyx6YbSu" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
The AI Assistant works best with **specific** **questions**. \
Instead of *"show me sales,"* try *"top 10 items by revenue this month."*
{% endhint %}

{% embed url="<https://customer-0jrbilsa8yt3k758.cloudflarestream.com/27509a71c500d77cd43f29409abe0d68/iframe?autoplay=true&controls=false&letterboxColor=transparent&loop=true&muted=true&poster=https://customer-0jrbilsa8yt3k758.cloudflarestream.com/27509a71c500d77cd43f29409abe0d68/thumbnails/thumbnail.jpg?height=1080&preload=true>" %}

{% hint style="success" %}
Click the <mark style="color:$primary;">`Chart`</mark> button to visualize the data — bar, line, pie, stacked bar, stacked area supported.
{% endhint %}

### 3. Save a Query

Select <mark style="color:$primary;">`Execute`</mark> to test your query. Since results depend on the conditions you write, review the output to confirm that it matches what you expect.

If you plan to reuse a query, select <mark style="color:$primary;">`Save`</mark> in the top-right corner. Saved queries appear in the left sidebar, where you can open and run them at any time.

After your query runs successfully, you can export the results with <mark style="color:$primary;">`Export to Excel`</mark>.

<figure><img src="/files/28pLcm7DoGUkKMVatYQi" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Your data syncs automatically **once a day**.\
To sync immediately, click the sync icon (🔄) at the bottom of the sidebar.
{% endhint %}

***

## Query Variables

If you include `{{variable_name}}` in your query, an input field is automatically generated when the query runs. The value entered in that field is applied to the variable in your SQL query.

When you save a query, your team members can enter their own values in the variable field and run the report whenever they need it.

#### Example

1. To search for items that contain a specific keyword, enter the following query:

```sql
select sku, name 
from items 
where name ilike '%' || {{item_name}} || '%';
```

2. When you run the query, an input field named **item\_name** appears.

<figure><img src="/files/QCHAIMDfwPuMHkdqagNo" alt=""><figcaption></figcaption></figure>

3. Enter a keyword such as *`sweater`* and the results will show all items with *“sweater”* in their name.

<figure><img src="/files/GVH3w1PcQplnnHMw0mTW" alt=""><figcaption></figcaption></figure>

4. Save the query if you plan to use it again. You can select and load saved queries anytime from the left-hand menu.

<figure><img src="/files/PZFM4RRFiIOtD1u2bnIW" alt=""><figcaption></figcaption></figure>

***

## Examples

Custom Analytics includes built-in templates you can run right away. Review a template to understand how it works, then adjust it or create a new query based on your needs.

#### Templates

* Weekly Stock In/Out Report
* Monthly Purchase and Sales Trend
* Last Outbound Date by Item

<figure><img src="/files/nQnYbuUTJowvomY7g8vf" alt=""><figcaption></figcaption></figure>

***

**Have more questions?** Check out our Custom Analytics FAQ:

{% content-ref url="/spaces/mkYNU2xLl20GSI6NQQ6q/pages/JZKqCEfW9v3ZHGye2PVO" %}
[Custom analytics](/docs/faq/reporting/custom-analytics.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.boxhero.io/docs/other-features/custom-analytics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.