Skip to main content
This feature is experimental.

​
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.

​
Installation

To use the starter, add the following dependency to your pom.xml. 
<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: 
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: 
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
H2 in-memory databases are not recommended for production. Use a persistent database such as PostgreSQL or MySQL to retain query history across restarts.

​
Field limits

Maximum character lengths for stored fields can be tuned. Values exceeding the limit are truncated.
PropertyDefaultApplies to
field-limits.query10 000Query text
field-limits.standard-field1 000Node name, trace ID, username, metadata attribute names
field-limits.metadata-value10 000Metadata 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 with the following rules:
OperationRequired authority
OPTIONSPermitted (CORS preflight)
DELETEAdmin roles (configured via atoti.server.security.roles-admin)
PATCHAdmin roles (configured via atoti.server.security.roles-admin)
GETAdmin or user roles (combined roles-admin and roles-user)
The security filter chain can be disabled via: 
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 for the full endpoint reference.