Analytics Query Settings
Essential knowledge
Intended Audience:
Technical User
Author:
Holger Lierse
Changed on:
16 Jan 2026
Overview
Analytics Queries are configured through settings that map query names to analytics resources in the Fluent Analytics backend services. Each setting follows the pattern`fc.analytics.queries.{domain}` and defines available queries, their resource locations, access permissions, and optional default parameters. Use this document to:- Understand query setting structure and naming conventions
- Configure new analytics queries
- Set default parameters for queries
- Control query access through role-based permissions
Key points
- Analytics queries are defined within settings (under
`fc.analytics.queries.{domain}`) - Target names: Queries are referenced as
`{domain}_{query_name}`in GraphQL (e.g.,`orders_total_revenue`) - Resource path: Each query points to a metric calculation in the analytics backend
- Role-based access: Optional roles field restricts query access to specific user roles
- Default parameters: Optional parameters field sets default filters (can be overridden at query time)
- Parameter precedence: GraphQL query parameters override setting defaults
Setting Naming Pattern
Query settings follow a standardized naming convention:`fc.analytics.queries.{domain}`Examples:
`fc.analytics.queries.orders``fc.analytics.queries.fulfilments``fc.analytics.queries.inventory``fc.analytics.queries.returns`
Query Definition Structure
Each setting contains an array of query definitions. A query definition is a configuration object that defines one metric, including its name, resource path in the Fluent Analytics backend services, required and optional roles and default parameters.1{
2 "queries": [
3 {
4 "name": "total_revenue",
5 "resource": {
6 "type": "PATH",
7 "value": "Standard Template/Dashboards/Orders/Total Revenue"
8 },
9 "roles": ["ORDER_MANAGER", "FINANCE_DIRECTOR"],
10 "parameters": [
11 {
12 "name": "order.status",
13 "value": ["COMPLETED"]
14 }
15 ]
16 }
17 ]
18}Query Definition Fields
Each query in the`queries` array requires two mandatory fields (`name` and `resource`) and supports two optional fields (`roles` and `parameters`). Together, these fields define what the query is called, where it gets its data, who can access it, and what default filters apply.Refer to the sample query alias definition above, which includes a single query, and consider the following key elements:| Field | Required | Purpose |
`name` | Yes | Unique identifier for the query |
`resource` | Yes | Resource location of the metric within the Fluent Analytics backend services |
`roles` | Optional (Recommended) | Restricts access to specific user roles |
`parameters` | Optional | Sets default filter values |
name
The`name`, prefixed with the domain, uniquely identifies a query within the Analytics platform (target name). While the name must be unique within the query settings definition, it can be shared across different settings.In combination with the `domain` (separated by an underscore (`_`)), it forms the target name of a metric. For example, if the above example, the name is `total_revenue` and the domain is `orders`, the query would be fully qualified as `orders_total_revenue`.resource
The`resource` specifies the query within the analytics backend services. It consists of a JSON object containing two fields: `type` and `value`.typeDefines the type of analytics query:
- PATH (default): The default type, commonly used.
- PATH: resources, this represents the location of the resource in the Fluent Analytics backend services.
roles
The`roles` field optionally defines a list roles that restrict access to the query. Users must be assigned a role that has the `ANALYTICS_VIEW` permission AND is listed in this array (see Analytics: Roles & Permissions).parameters
`parameters` allow customisation by specifying customer-specific labels, statuses, or constraints. A parameter specifies to a fully qualified field on the Fluent Analytics backend services, and a list of values to either limit the query (inclusion), or to exclude (exclusion) (see Analytics: Filtering Analytics Queries by Status).Parameters let you filter what data gets included in a query. Each parameter consists of: - A field name that identifies what to filter (e.g.,
`order.status`,`fulfilment.type`) - A list of values that define the filter criteria
- Inclusion:
`["COMPLETED"]`includes only entities with these values - Exclusion:
`["-CANCELLED"]`excludes entities with these values (note the`-`prefix)
