Audience features

An audience feature is a pre-created OTQL query fragment. Your users can leverage the audience features you create to run complex queries without OTQL knowledge. Each audience feature will turn into a user-friendly selector in the UI.

Audience features you create are available in the navigator, in Audience > Builders > Standard.

Let's take the following query as an example:

SELECT @count{} FROM UserPoint WHERE
events { 
    nature = "$transaction_confirmed" and 
    date >= $date 
    and products {brand in $brand and name in $name}
    }

It is technically an OTQL query based on your schema in which you registered parameters. In this case, it represents a business feature that may be used regularly by your users: selecting user points that perform a transaction in a particular date range and for specific products.

Users will see this selector in the builder instead of an OTQL query.

This audience feature will automatically be combined with other audience features, which the user can select to create segments.

The process

Users will have access to the standard segment builder if at least one audience feature is set up. But you need multiple ones to create value for users.

Good knowledge of the schema and the queries that are usually created in your datamart is important for the success of this feature.

Here is a sample process to follow to enable audience features and create value for your users:

1. Know your schema. What is it optimized for? Which queries are regularly created? What are your actual segments and what are their queries? You should be able to create a list of useful audience features with these pieces of information.

2. Set up audience features, in the UI and/or by script.

3. Monitor usage and update audience features regularly!

Folders

You can store audience features in folders. Any audience feature without a folder will be assigned to the root folder. Here are some examples.

List folders

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders

Path Parameters

Name	Type	Description
datamart_id	integer	The ID of the datamart

200

{
  "first_result": 0,
  "count": 0,
  "max_results": 0,
  "status": "ok",
  "data": [
    {
      "id": "string",
      "children_ids": [
        "string"
      ],
      "audience_features_ids": [
        "string"
      ],
      "parent_id": "string",
      "datamart_id": "string",
      "name": "string"
    }
  ],
  "total": 0
}

List one folder

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders/{audience_feature_folders_id}

Path Parameters

Name	Type	Description
audience_feature_folders_id	integer	The ID of the folder
datamart_id	integer	The ID of the datamart

200

{
  "status": "ok",
  "data": {
    "id": "string",
    "children_ids": [
      "string"
    ],
    "audience_features_ids": [
      "string"
    ],
    "parent_id": "string",
    "datamart_id": "string",
    "name": "string"
  }
}

Create a folder

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders

Path Parameters

Name	Type	Description
datamart_id*	integer	The ID of the datamart

Request Body

Name	Type	Description
children_ids	array	IDs of folder's children
audience_features_ids	array	IDs of audience features attached to the folder
parent_id	string	The ID of the folder's parent
datamart_id	string	The ID of the datamart
name*	string	The name of the folder

200

// Create a folder payload
{
  "children_ids": [
    "string"
  ],
  "audience_features_ids": [
    "string"
  ],
  "parent_id": "string",
  "datamart_id": "string",
  "name": "string"
}

Edit a folder

PUT https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_feature_folders/{audience_feature_folders}

Path Parameters

Name	Type	Description
datamart_id*	integer	The ID of the datamart
audience_feature_folders_id*	integer	The ID of the audience feature folder

Request Body

Name	Type	Description
children_ids	array	IDs of folders's children
audience_features_ids	array	IDs of audience features attached to the folder
parent_id	string	The ID of the folder's parent
datamart_id	string	The ID of the datamart
name*	string	The name of the folder

200

{
  "status": "ok",
  "data": {
    "id": "string",
    "children_ids": [
      "string"
    ],
    "audience_features_ids": [
      "string"
    ],
    "parent_id": "string",
    "datamart_id": "string",
    "name": "string"
  }
}

// Editing a folder payload
{
  "children_ids": [
    "string"
  ],
  "audience_features_ids": [
    "string"
  ],
  "parent_id": "string",
  "datamart_id": "string",
  "name": "string"
}

Audience features

List audience features

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features

Path Parameters

Name	Type	Description
datamart_id	integer	The ID of the datamart

200

{
  "first_result": 0,
  "total": 0,
  "count": 0,
  "data": [
    {
      "object_tree_expression": "string",
      "description": "string",
      "id": "string",
      "variables": [
        {
          "field_name": "string",
          "data_type": "string",
          "reference_model_type": "string",
          "type": "string",
          "parameter_name": "string",
          "path": [
            "string"
          ],
          "reference_type": "string",
          "directive": "string",
          "container_type": "string"
        }
      ],
      "token": "string",
      "datamart_id": "string",
      "addressable_object": "string",
      "name": "string",
      "folder_id": "string",
      "creation_date": 0
    }
  ],
  "max_results": 0,
  "status": "ok"
}

Get an audience feature

GET https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features/{audience_feature_id}

Path Parameters

Name	Type	Description
audience_feature_id	integer	The ID of the audience feature
datamart_id	integer	The ID of the datamart

200

{
  "status": "ok",
  "data": {
    "object_tree_expression": "string",
    "description": "string",
    "id": "string",
    "variables": [
      {
        "field_name": "string",
        "data_type": "string",
        "reference_model_type": "string",
        "type": "string",
        "parameter_name": "string",
        "path": [
          "string"
        ],
        "reference_type": "string",
        "directive": "string",
        "container_type": "string"
      }
    ],
    "token": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string",
    "creation_date": 0
  }
}

Create an audience feature

POST https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features

Path Parameters

Name	Type	Description
datamart_id	integer	The ID of the datamart

Request Body

Name	Type	Description
object_tree_expression	string	The WHERE statement of the query associated to the audience feature
description	string	The description of your audience feature
datamart_id	string	The ID of the datamart
addressable_object	string	The SELECT statement of the query associated to the audience feature. It must always set at UserPoint.
name	string	The name of the audience feature
folder_id	string	The ID of folder where the audience feature is stored

200

{
  "status": "ok",
  "data": {
    "object_tree_expression": "string",
    "description": "string",
    "id": "string",
    "variables": [
      {
        "field_name": "string",
        "data_type": "string",
        "reference_model_type": "string",
        "type": "string",
        "parameter_name": "string",
        "path": [
          "string"
        ],
        "reference_type": "string",
        "directive": "string",
        "container_type": "string"
      }
    ],
    "token": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string",
    "creation_date": 0
  }
}

// Creating an audience feature payload
{
    "object_tree_expression": "string",
    "description": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string"
}

Edit an audience feature

PUT https://api.mediarithmics.com/v1/datamarts/{datamart_id}/audience_features/{audience_feature_id}

Path Parameters

Name	Type	Description
audience_feature_id	integer	The ID of the audience feature to edit
datamart_id	integer	The ID of the datamart

Request Body

Name	Type	Description
object_tree_expression	string	The WHERE statement of the query associated to the audience feature
description	string	The description of your audience feature
datamart_id	string	The ID of the datamart
addressable_object	string	The SELECT statement of the query associated to the audience feature. It must always set at UserPoint.
name	string	The name of the audience feature
folder_id	string	The ID of folder where the audience feature is stored

200

{
  "status": "ok",
  "data": {
    "object_tree_expression": "string",
    "description": "string",
    "id": "string",
    "variables": [
      {
        "field_name": "string",
        "data_type": "string",
        "reference_model_type": "string",
        "type": "string",
        "parameter_name": "string",
        "path": [
          "string"
        ],
        "reference_type": "string",
        "directive": "string",
        "container_type": "string"
      }
    ],
    "token": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string",
    "creation_date": 0
  }
}

// Editing an audience feature payload
{
    "object_tree_expression": "string",
    "description": "string",
    "datamart_id": "string",
    "addressable_object": "string",
    "name": "string",
    "folder_id": "string"
}

OTQL query rules

Parameters

Create query parameters using the $parameter_namesyntax. Example:

// The gender will be selectable by the user
SELECT @count{} FROM UserPoint 
where  profiles {gender in $gender}

// The date will be selectable by the user,
// but the nature will always be $transaction_confirmed
SELECT @count{} FROM UserPoint 
where events { nature = "$transaction_confirmed" and date >= $date }

The field in the audience feature will have the name you enter after the $ . Spaces in field name are not authorized. The type of selector in the audience feature is automatically chosen based on the field type

If you want to be able to select several values in a field, use keyword in instead of the classic ==.

// User will only be able to select one gender
SELECT @count{} FROM UserPoint 
where  profiles {gender == $gender}

// User will be able to select multiple gender values
SELECT @count{} FROM UserPoint 
where  profiles {gender in $gender}

You can create parameters for frequency requests with the @ScoreSum directive:

// User will be able to select the minimum number of transactions
SELECT @count{} FROM UserPoint 
WHERE events@ScoreSum(min: $frequency) { 
    purchase in $user_purchase 
}