Analytics Query Structure

Get Started
Functionality
Learning
Extension
Dev Tooling
APIs
Releases

Essential knowledge

Intended Audience:

Technical User

Author:

Holger Lierse

Changed on:

16 Jan 2026

Overview

This document defines the structure and syntax for querying the Fluent Analytics backend services. Analytics Queries reference pre-configured metrics by name (called "targets"), rather than defining individual fields like standard GraphQL queries. Targets provide controlled access to analytics metrics with built-in role-based permissions. Use this document to:

Understand and construct analytics GraphQL queries
Understand target name format and how it links to query settings
Configure filter parameters to refine query results
Integrate analytics into dashboards and web applications

Key points

Target-based queries: Reference pre-configured metrics by name (e.g., `orders_total_revenue`) instead of individual fields
Target names: Follow format `{query_group}_{query_name}` and link to query settings
Filter parameters: Optional key-value pairs that refine query results (values must be arrays)
Dynamic binding: Template syntax enables runtime parameter values from URL, context, or user data
Analytics Query settings: Configuration that defines available queries, resource paths, roles, and defaults.

GraphQL Query Syntax

Unlike standard GraphQL queries that define individual fields, the `analytics` query uses `targets` which are pre-configured metric identifiers like `orders_total_revenue`. Each target can include optional filter parameters to refine the results.Analytics Query Structure

1query AnalyticsQuery(
2  $targets: [AnalyticsTarget!]!,
3  $timezone: String
4) {
5  analytics(targets: $targets, timezone: $timezone) {
6    results
7  }
8}

Argument	Type	Required	Description
`targets`	`[AnalyticsTarget!]!`	Yes	Array of analytics queries to execute. Each `AnalyticsTarget` holds the details of the metric query identified by a target name and optional filter parameters.
`timezone`	`String`	No	IANA timezone identifier (e.g., "America/New_York")

Analytics Response Structure

1{
2  "data": {
3    "analytics": {
4      "results": {
5        "query_name_1": {
6          // Query-specific data structure
7        },
8        "query_name_2": {
9          // Query-specific data structure
10        }
11      }
12    }
13  }
14}

Target Names

A target name identifies which metric to retrieve from the Fluent Analytics backend services. It follows the format `{domain}_{query_name}`, such as `orders_total_revenue` or `inventory_total_on_hand`.The target name links to an Analytics Query Setting through its structure:

domain: Corresponds to Analytics Query Setting suffix
- Derived from setting name: `fc.analytics.queries.{domain}`
- Examples: `orders`, `fulfilments`, `inventory`, `returns`
query_name: Matches the `name` field in Analytics Query Setting definition
- Defined in the query setting configuration
- Examples: `total_revenue`, `fulfilment_by_location`, `total_on_hand`

Examples:

Full Query Name	Domain	Query Name	Setting Name
`orders_total_revenue`	`orders`	`total_revenue`	`fc.analytics.queries.orders`
`fulfilments_fulfilment_by_location`	`fulfilments`	`fulfilment_by_location`	`fc.analytics.queries.fulfilments`
`inventory_total_on_hand`	`inventory`	`total_on_hand`	`fc.analytics.queries.inventory`
`returns_return_rate`	`returns`	`return_rate`	`fc.analytics.queries.returns`

Filter Parameters

Filter parameters refine analytics queries by applying conditions to the data. Each parameter is a key-value pair where the key identifies the field to filter (e.g., `order.status`) and the value specifies the filter criteria (e.g., `["COMPLETE"]`). Values are always arrays, even for single items.Filter Parameter Structure

1{
2  "key": "parameter_name",
3  "value": ["parameter_value_1", "parameter_value_2"]
4}

Rules:

Keys must match available parameter names for the metric query (see Metrics Library)
Multiple values use OR logic (e.g., `["COMPLETE", "BOOKED"]` returns orders with either status)
All values must be arrays: `["single_value"]` not `"single_value"`

Common Parameter TypesAnalytics queries support several standard parameter types for filtering data. While available parameters vary by query, most follow consistent patterns based on the type of data being filtered.

Parameter Type	Example Key	Description
Date Range	`order.created_date`	ISO 8601 dates (e.g., `["2024-01-01", "2024-12-31"]`)
Status	`order.status`	Workflow status values (e.g., `["COMPLETE", "BOOKED"]`)
Reference	`retailer.ref`	Entity identifiers (e.g., `["RETAILER_001"]`)
Type	`order.type`	Entity type classifications (e.g., `["CC", "HD"]`)

Note

Available parameters vary by each domain. Review the Metrics Library for query-specific parameters.

Dynamic Parameter Binding

Parameter values can use template syntax to bind dynamically to URL parameters, user context, or other runtime values. This enables filter components and user-specific data restrictions to work automatically without hardcoding values. Learn more about UX Configuration Common Concepts

Analytics Query Settings

Analytics queries are defined in settings that map query names to their underlying analytics resources. These settings use a standardized naming pattern and contain all the metadata needed to execute queries, including resource paths, required roles, and optional default parameters.Setting StructureQuery settings follow the naming pattern: `fc.analytics.queries.{query_group}`Examples:

For more details see Analytics Query Settings.

Analytics Query Structure

Overview

Key points

GraphQL Query Syntax

Target Names

Filter Parameters

Analytics Query Settings

Related content

Configuring the Fluent Analytics Dashboards: A Step-by-Step Guide

Analytics: Filtering Analytics Queries by Status

Fluent Metrics Library Overview

Analytics Query Settings

Holger Lierse

Building Blocks

By Type

Helpful Resources

Quick Links