---
schema_version: "1"
id: bde9f3c3c459b0ab55708b10848eacada87eeefca9a5485cbe819a30954fae11
title: Overview
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/data-cloud/semantic-layer/guides/metric-query-api-in-depth-overview.md
canonical_url: https://developer.salesforce.com/docs/data/semantic-layer/guide/metric-query-api-in-depth-overview.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 15ff8b7ce975447fa83a2b24664255b7d3543740aee2cadc18d09698c67d70ac
products:
  - Tableau Semantics Layer APIs
  - Data 360 Developer Documentation
---
# Overview

Use the Semantic Metric Query API to send metric-based queries against your Semantic Model. The Semantic Metric Query API allows you to leverage your data in Data 360 through Tableau Semantics to answer business questions using predefined metrics.

First, start with an existing Semantic Model that contains semantic metrics, or build a new Semantic Model through the Tableau Semantics Authoring Experience or Authoring Connect API. Then, you can use the Semantic Metric Query API to send metric queries that leverage your Tableau Semantics data (including any Semantic Definitions, and Metrics) to obtain exact results for each business case by selecting the measure, time dimension and using various metric parameters, such as additional dimensions, time range and sorting.

## What is the Semantic Metric Query?

A semantic metric query is a logical request that defines what metric data to retrieve from the Semantic Model. It's processed by the Semantic Metric Query Generator, which translates the request into optimized SQL over Data 360 objects, runs it in the context of your tenant, and returns the results.

The Semantic Metric Query is composed of the following properties:

- A metric definition that specifies the metric measure and time dimension.
- Additional dimensions to group the metric results by
- Sorting and filtering options for the results
- Semantic context including timezone and locale settings

## Semantic Metric Query Execution and Flow

A Semantic Metric Query is first sent to a gateway service and then the metadata associated with the objects being queried (Semantic Model Objects, Semantic Definitions, and Metrics) is fetched from Salesforce Core and Data 360. The SQL query is then generated and executed.

## Semantic Metric Query model

The following is an example of a Semantic Metric Query with a Model ID:

```json
{
  "structuredMetricQuery": {
    "semantic_context": {
      "timezone": {
        "id": "America/Los_Angeles"
      },
      "locale": {
        "code": "en_US"
      }
    },
    "model_api_name": "AccountSDM",
    "submetric_definition": {
      "metric_api_name": "AnnualRevenueAmountPerName_md"
    },
    "additional_dimensions": [
      {
        "tableFieldReference": {
          "fieldApiName": "MailingCountry__c",
          "tableApiName": "ContactSemanticLayer__dll"
        }
      }
    ]
  },
  "semanticModelId": "2SMxx0000004CAeGAM"
}
```

The following example shows a complete Semantic Metric Query with a Semantic Model:

```json
{
  "structuredMetricQuery": {
    "semantic_context": {
      "timezone": {
        "id": "America/Los_Angeles"
      },
      "locale": {
        "code": "en_US"
      }
    },
    "model_api_name": "AccountSDM",
    "submetric_definition": {
      "metric_api_name": "AnnualRevenueAmountPerName_md"
    },
    "additional_dimensions": [
      {
        "tableFieldReference": {
          "fieldApiName": "City",
          "tableApiName": "SemanticAccount_SDO"
        }
      }
    ]
  },
  "semanticModel": {
    "apiName": "TestSDM",
    "label": "TestSDM",
    "semanticDataObjects": [
      {
        "apiName": "SemanticAccount_SDO",
        "label": "SemanticAccount",
        "dataObjectName": "SemanticAccount_SDO__dll",
        "dataObjectType": "Dlo",
        "semanticDimensions": [
          {
            "apiName": "Name",
            "label": "Name",
            "dataType": "Text",
            "dataObjectFieldName": "Name__c"
          },
          {
            "apiName": "CreatedDate",
            "label": "CreatedDate",
            "dataType": "DateTime",
            "dataObjectFieldName": "CreatedDate__c"
          },
          {
            "apiName": "City",
            "label": "City",
            "dataType": "Text",
            "dataObjectFieldName": "City__c"
          }
        ],
        "semanticMeasurements": [
          {
            "apiName": "AnnualRevenueAmount",
            "label": "AnnualRevenueAmount",
            "dataType": "Number",
            "dataObjectFieldName": "AnnualRevenueAmount__c"
          }
        ]
      }
    ],
    "semanticMetrics": [
      {
        "apiName": "AnnualRevenueAmountPerName_md",
        "label": "Annual Revenue Amount Per Name Metric",
        "tableFieldReference": {
          "fieldApiName": "AnnualRevenueAmount",
          "tableApiName": "SemanticAccount_SDO"
        },
        "timeDimensionReference": {
          "tableFieldReference": {
            "fieldApiName": "CreatedDate",
            "tableApiName": "SemanticAccount_SDO"
          }
        },
        "aggregationType": "Sum",
        "timeGrains": ["Day", "Month", "Week", "Quarter"],
        "additionalDimensions": [
          {
            "tableFieldReference": {
              "fieldApiName": "Name",
              "tableApiName": "SemanticAccount_SDO"
            }
          }
        ]
      }
    ]
  }
}
```