> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Query History Starter

<Info>
  This feature is experimental.
</Info>

## Introduction

The Query History Starter automatically sets up query history persistence, a REST API, and security rules for tracking MDX query executions in an Atoti Server application.

When enabled, it records MDX queries executed against the server, including their status, duration, user, and metadata. It also exposes REST endpoints to browse, filter, cancel, and delete recorded queries, as well as retrieve query execution plans.

The following metadata attributes are automatically attached to queries:

* `apiType` — set to `rest` for queries executed via the REST API.
* `failureCause` — added automatically when a query fails, containing the error message.

The Query History Starter is typically used alongside the [Atoti Server Starter](atoti_starter).

## Installation

To use the starter, add the following dependency to your `pom.xml`.

```xml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}} theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
<dependency>
  <groupId>com.activeviam.springboot</groupId>
  <artifactId>query-history-starter</artifactId>
  <version>${activepivot.version}</version>
</dependency>
```

## Configuration

All properties live under the `atoti.server.query-history` namespace.

### Enabling and disabling

The starter is **enabled by default**. To disable it:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
atoti:
  server:
    query-history:
      enabled: false
```

### Database

Query history is persisted using Hibernate. The `database` property accepts standard Hibernate and HikariCP connection pool settings.

The following example configures an H2 in-memory database:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
atoti:
  server:
    query-history:
      database:
        hibernate:
          dialect: org.hibernate.dialect.H2Dialect
          hbm2ddl.auto: update
          show_sql: false
          format_sql: false
          connection:
            driver_class: org.h2.Driver
            autocommit: false
            provider_class: org.hibernate.hikaricp.internal.HikariCPConnectionProvider
          hikari:
            maximumPoolSize: 10
            maxLifetime: 300000
            idleTimeout: 0
            dataSourceClassName: org.h2.jdbcx.JdbcDataSource
            dataSource:
              url: "jdbc:h2:mem:query_history;DB_CLOSE_DELAY=-1;IGNORECASE=TRUE"
            poolName: QueryHistory-ConnectionPool
```

<Warning>
  H2 in-memory databases are not recommended for production. Use a persistent database such as PostgreSQL or MySQL to retain query history across restarts.
</Warning>

### Field limits

Maximum character lengths for stored fields can be tuned. Values exceeding the limit are truncated.

| Property                      | Default | Applies to                                              |
| ----------------------------- | ------- | ------------------------------------------------------- |
| `field-limits.query`          | 10 000  | Query text                                              |
| `field-limits.standard-field` | 1 000   | Node name, trace ID, username, metadata attribute names |
| `field-limits.metadata-value` | 10 000  | Metadata attribute values, error messages               |

## Security

The Atoti Server Starter registers a `SecurityFilterChain` (order 330) that protects all endpoints under `/activeviam/query-history/rest/v1/**`.
It uses the project's [`MachineToMachineSecurityDsl`](atoti_starter#machine-to-machine-dsl) with the following rules:

| Operation | Required authority                                               |
| --------- | ---------------------------------------------------------------- |
| `OPTIONS` | Permitted (CORS preflight)                                       |
| `DELETE`  | Admin roles (configured via `atoti.server.security.roles-admin`) |
| `PATCH`   | Admin roles (configured via `atoti.server.security.roles-admin`) |
| `GET`     | Admin or user roles (combined `roles-admin` and `roles-user`)    |

The security filter chain can be disabled via:

```yaml theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
atoti:
  server:
    endpoint:
      query-history:
        security:
          enabled: false
```

## Distributed setup

In a distributed environment, the Query History Starter should be activated on the **query node** — the node that receives and executes client MDX queries. Activating it on a data node will have no effect since data nodes do not execute client MDX queries.

Query cancellation is not supported in distributed environments. The cancel endpoints only operate on queries known to the local node.

## REST API

All endpoints are served under the base path `/atoti/query-history/rest/v1`.
See the [Query History REST API](/engine/rest/6.1.20/query-history-rest-api-experimental) for the full endpoint reference.