Create a metric

Important

The GraphQL Insights API is currently in Early Availability status for customers on the AWS-US cluster. For more information, see GraphQL API policy.

A metric definition mainly consists of an SQL query, with the option to apply filters.

Each metric is associated with a specific dataset. There can be multiple metrics defined for a given dataset, but there must be at least one so you can retrieve the data.

Since metrics use SQL queries, you should be familiar with writing SQL queries in order to create them, and understand how the various clauses of a query are constructed.

SELECT clause

The SELECT clause specifies the attributes for which data is to be retrieved.

When constructing the SELECT part of the SQL query, it's important to know that Insights appends a prefix and suffix to the name of each attribute within the dataset. The prefix is data_ and the suffix indicates the datatype. For example:

• region becomes data_region_string

• contracts becomes data_contracts_integer

When you create a metric, you must use the full attribute name in the query. Using the examples above, the SELECT part of the query might look like this:

    SELECT \
      data_region_string, \
      data_contracts_integer \

FROM clause

The FROM part of the query pulls data from a single base table, whose name always corresponds to the product UUID. For example:

    FROM \"{12345a6b-c7d8-90e1-2f3g-45678h90i123}\"

Note that the double-quotes here are required, as single quotes do not work. The double-quotes must be escaped in order for the JSON to parse correctly.

WHERE clause

The WHERE part of the query specifies the dataset, along with any filters that users will be able to use to determine which results are returned. It must begin by specifying the dataset UUID as the value for the identity_dataset_id parameter, and specifying a date range for the query:

WHERE identity_dataset_id = '{996e42eb-97b4-4d80-8201-6f377c31e745}' \
  AND __time > {date_created_from} \
  AND __time < {date_created_to} \

The date_created_from and date_created_to values are supplied when data is retrieved using the visualizationMetricData query (see Retrieve data for a metric).

If a filter is defined for the metric, a value for it may be included in an AND clause within the WHERE clause. For example:

WHERE identity_dataset_id = '{996e42eb-97b4-4d80-8201-6f377c31e745}' \
  AND __time > {date_created_from} \
  AND __time < {date_created_to} \
  AND data_region_string = '{MY_FILTER_1}'

End users may then use a mechanism in the front end to supply the filter value (for example, by selecting it from a drop-down list).

Mutation

mutation createVisualizationMetric($in: CreateVisualizationMetricInput!) {
  createVisualizationMetric(input: $in) {
    metric {
      id
    }
  }
}

Variables

{
  "in": {
    "name": "METRIC_NAME",
    "datasetId": "{996e42eb-97b4-4d80-8201-6f377c31e745}",
    "revisionId": 1,
    "productId": "12345a6b-c7d8-90e1-2f3g-45678h90i123",
    "query": "\
SELECT \
  __time, \
  data_my_product_dimension_a_string, \
  data_my_product_measure_b_integer, \
  identity_dataset_id \
FROM \"{12345a6b-c7d8-90e1-2f3g-45678h90i123}\" \
WHERE identity_dataset_id = '{996e42eb-97b4-4d80-8201-6f377c31e745}'\
  AND __time > {date_created_from} \
  AND __time < {date_created_to} \
  AND data_my_product_dimension_a_string = '{MY_FILTER_1}' \
    "
  }
}

Response

The id returned in this response is the metric UUID, and is needed for other API calls involving this metric.

{
  "data": {
    "createVisualizationMetric": {
      "metric": {
        "id": "d4615d7a-c384-486f-beff-6fb013a342ec"
      }
    }
  }
}