Customer Profiling

Introduction

The Customer Profiling component is designed to serve various metrics needed to show ROI and profile our customers (identifying needs, understanding consumption, etc.). It provides a flexible querying interface that allows for retrieving metrics at different aggregation levels, such as per account, contract, company, or industry.

Materials - Framing issue Discussion ⧉

Quering metrics

The public API exposes a QueryBuilder factory that facilitates the creation of queries for different aggregation levels. To get started, import the factory and the necessary enums:

from components.customer_profiling.public.enums import (
    AggregationLevel,
)
from components.customer_profiling.public.queries.factory import (
    QueryBuilder,
)

query = QueryBuilder.query(AggregationLevel.account)

The query builder supports several filters to refine your queries:

App Name: Specify the app for which you want to retrieve metrics.

from shared.helpers.app_name import AppName

query = QueryBuilder.query(AggregationLevel.account)
    .for_app(AppName.ALAN_FR)

If you don't specify the app name the query builder will default to AppName.ALAN_FR

Entity Reference: Specify the entity for which you want to retrieve metrics.

query = QueryBuilder.query(AggregationLevel.account)
    .for_entity(account_id)

Multiple Entities: Specify multiple entities for which you want to retrieve metrics.

query = QueryBuilder.query(AggregationLevel.account)
    .for_entities([account_id1, account_id2])

Metric Names: Filter metrics by their names.

query = QueryBuilder.query(AggregationLevel.account)
    .for_entity("ACCOUNT ID")
    .where_metric_name_in(["metric1", "metric2"])

Attributes-only querying: If you are not interested in metrics, you can query attributes only. This will avoid loading unnecessary metric data.

query = QueryBuilder.query(AggregationLevel.account)
    .for_entity("ACCOUNT ID")
    .attributes_only()

Effective Dates: Retrieve metrics for specific effective dates.

query = QueryBuilder.query(AggregationLevel.account)
    .for_entity("ACCOUNT ID")
    .where_effective_date_in([date1, date2])

You can use the for_last_full_month method in order to only get metrics effective for the last full month. Metrics for April are made available on May 1st and their effective date is 01/04/YYYY.

query = QueryBuilder.query(AggregationLevel.account)
    .for_entity("ACCOUNT ID")
    .for_last_full_month()

After configuring your query with the desired filters, you can finalize the query using the following methods:

Single Entity Response:

Use the first method to retrieve metrics for a single entity:

response = QueryBuilder.query(AggregationLevel.account)
    .for_entity("ACCOUNT ID")
    .where_metric_name_in(["metric1", "metric2"])
    .where_effective_date_in([date1, date2])
    .first()

Multiple Entities Response:

Use the all method to retrieve metrics for multiple entities:

response = QueryBuilder.query(AggregationLevel.account)
    .for_entities(["ACCOUNT_ID_1", "ACCOUNT_ID_2"])
    .where_metric_name_in(["metric1", "metric2"])
    .where_effective_date_in([date1, date2])
    .all()

Response Structure

The response from the first method is a QueryResponse object that contains:

• Meta: Metadata providing context about the query results.
• Metrics: A list of MetricRow objects representing the metrics.

Each MetricRow includes the metric name, raw value, unit, effective date, and a formatted value for display purposes.

Example response:

{
  "meta": {
    "account_id": "0029beef-34f2-4e28-8d13-3e019e032d69", 
    "account_name": "Bonard", 
    "customer_industry": "retail", 
    "is_key_account": false, 
    "n_employees": 7
  }, 
  "metrics": [
    {
      "effective_date": "2023-03-01", 
      "metric_name": "affiliation_minutes_saved_past_12_months", 
      "metric_unit": "minutes", 
      "metric_value": "5.0", 
      "metric_value_formatted": "5min"
    }
  ]
}

The response from the all method is a list of QueryResponse objects, each corresponding to one of the queried entities.

[
  {
    "meta": {
      "account_id": "0029beef-34f2-4e28-8d13-3e019e032d69",
      "account_name": "Bonard",
      "customer_industry": "retail",
      "is_key_account": false,
      "n_employees": 7
    },
    "metrics": [
      {
        "effective_date": "2023-03-01",
        "metric_name": "affiliation_minutes_saved_past_12_months",
        "metric_unit": "minutes",
        "metric_value": "5.0",
        "metric_value_formatted": "5min"
      }
    ]
  },
  {
    "meta": {
      "account_id": "0039beef-34f2-4e28-8d13-3e019e032d70",
      "account_name": "Metro",
      "customer_industry": "hospitality",
      "is_key_account": true,
      "n_employees": 50
    },
    "metrics": [
      {
        "effective_date": "2023-04-01",
        "metric_name": "revenue_generated_past_12_months",
        "metric_unit": "euros",
        "metric_value": "15000.0",
        "metric_value_formatted": "€15,000"
      }
    ]
  }
]

The metric_value_formatted attribute in MetricRow is calculated based on the unit, providing a human-readable representation of the metric value.