Feedback Edit

Explore the Analytics OData metadata

  • Article
  • 5 minutes to read

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020 | Azure DevOps Server 2019

Understanding the metadata associated with the entity model for Analytics is a prerequisite for programmatically querying the Data model for Analytics. OData metadata is a machine-readable description of the entity model designed to enable client consumption.

Note

"The Open Data Protocol (OData) is a data access protocol built on core protocols like HTTP and commonly accepted methodologies like REST for the web. There are various kinds of libraries and tools can be used to consume OData services." - OData Organization Basic Tutorial.

Note

The Analytics service is automatically enabled for all Azure DevOps Services. It is supported for use in production. Power BI integration and access to the OData feed of the Analytics Service are generally available. We encourage you to use it and provide us feedback.

Note

The Analytics service is automatically installed on all new project collections for Azure DevOps Server 2020 and later versions. It is supported for use in production. Power BI integration and access to the OData feed of the Analytics Service are generally available. We encourage you to use it and provide us feedback. If you upgraded from Azure DevOps Server 2019, then you're provided with the option to install the Analytics service during upgrade.

Note

The Analytics service is in preview for Azure DevOps Server 2019. You access Analytics by enabling or installing it for a project collection. Power BI integration and access to the OData feed of the Analytics Service are in Preview. We encourage you to use it and provide us feedback.

In this article you'll learn how to:

  • Query the metadata on a specific project
  • Query the metadata on an organization
  • Identify the keys, properties, and navigational properties associated with an Entity
  • Identify the capabilities of the Analytics OData endpoint

For detailed descriptions for all OData elements, see OData model.

Query the Analytics service for metadata

Analytics exposes the entity model at the metadata URL, formed by appending $metadata to the service root URL. Analytics provides service roots for a project or an entire organization in Azure DevOps.

Query for metadata on a specific project

You construct the service root URL for a project as shown:

https://analytics.dev.azure.com/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata

Note

The {version} value is formatted as v1.0. The latest supported version is v2.0, and the latest preview version is v4.0-preview. For more information, see OData API versioning.

https://{servername}:{port}/tfs/{OrganizationName}/{ProjectName}/_odata/{version}/$metadata

Note

The examples shown in this document are based on a Azure DevOps Services URL, you will need to substitute in your Azure DevOps Server URL

Interpret the metadata response

The core components of the metadata response are EntityType and EntityContainer.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
    <edmx:DataServices>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Microsoft.VisualStudio.Services.Analytics.Model">
           <EntityType Name="Entity Name"/>
        </Schema>
        <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Default">
           <EntityContainer Name="Container"/>
        </Schema>
    </edmx:DataServices>
</edmx:Edmx>

EntityTypes

Entity types are named structured types with a key. They define the named properties and relationships of an entity. Entity types may derive by single inheritance from other entity types. The key of an entity type is formed from a subset of its primitive properties.

EntityTypes define each of the entities in the Analytics model including properties and relationships. The following example

<EntityType Name="Project">
  <Key>
    <PropertyRef Name="ProjectSK"/>
  </Key>
  <Property Name="ProjectSK" Type="Edm.Guid" Nullable="false"/>
  <Property Name="ProjectId" Type="Edm.Guid" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Id"/>
  </Property>
  <Property Name="ProjectName" Type="Edm.String" Nullable="false">
    <Annotation Term="Display.DisplayName" String="Project Name"/>
  </Property>
  <Property Name="AnalyticsUpdatedDate" Type="Edm.DateTimeOffset"/>
  <Property Name="ProjectVisibility" Type="Microsoft.VisualStudio.Services.Analytics.Model.ProjectVisibility">
    <Annotation Term="Display.DisplayName" String="Project Visibility"/>
  </Property>
  <NavigationProperty Name="Areas" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Area)"/>
  <NavigationProperty Name="Iterations" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Iteration)"/>
  <NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>
</EntityType>

Keys

Keys define the Entity properties available for use as a Navigational Property.

<Key>
   <PropertyRef Name="ProjectSK"/>
</Key>

Properties

The set of `Entity properties available for query. Annotations represent other details about a given property.

Any property of Analytics that should be visible to end users is annotated with a DisplayName.

<Property Name="ProjectSK" Nullable="false" Type="Edm.Guid"/>
<Property Name="ProjectId" Nullable="false" Type="Edm.Guid">
   <Annotation String="Project Id" Term="Display.DisplayName"/>
</Property>
<Property Name="ProjectName" Nullable="false" Type="Edm.String">
   <Annotation String="Project Name" Term="Display.DisplayName"/>
</Property>

ReferenceName is another common annotation used to define the system identifier for a specific property.

<Property Name="State" Type="Edm.String">
   <Annotation String="State" Term="Display.DisplayName"/>
   <Annotation String="System.State" Term="Ref.ReferenceName"/>
</Property>

Querying an individual Entity is useful. Eventually, you'll probably want to filter or expand details of another Entity. To do so, you need to understand how to use the Navigational Properties of the Entity model.

A NavigationaProperty with a collection type represents a many-to-many relationship in the model.

<NavigationProperty Name="Teams" Type="Collection(Microsoft.VisualStudio.Services.Analytics.Model.Team)"/>

ReferentialConstraints tie navigational properties to a specific key of an entity, representing a many-to-one relationship in the model.

<NavigationProperty Name="Project" Type="Microsoft.VisualStudio.Services.Analytics.Model.Project">
   <ReferentialConstraint ReferencedProperty="ProjectSK" Property="ProjectSK"/>
</NavigationProperty>

Containers (OData capabilities)

EntitySets

Entities are the core identity types in a data model. Entity sets are named collections of entities. For example, WorkItems and WorkItemRevisions are EntitySets within the EntityContainer named Container. An entity can be a member of at most one entity set. Entity sets provide the primary entry points into the data model, and represent a collection of entities and associated Navigational property bindings and annotations.

The following XML syntax indicates the Projects entity set data model. For a description of each entity set, see Data model for Analytics.

<EntitySet Name="Projects" EntityType="Microsoft.VisualStudio.Services.Analytics.Model.Project">
  <NavigationPropertyBinding Path="Areas" Target="Areas"/>
  <NavigationPropertyBinding Path="Iterations" Target="Iterations"/>
  <NavigationPropertyBinding Path="Teams" Target="Teams"/>
  <Annotation Term="Org.OData.Display.V1.DisplayName" String="Projects"/>
</EntitySet>

Capabilities

Capabilities define the set of functions understood by the Analytics OData endpoint.

<Annotation Term="Org.OData.Capabilities.V1.FilterFunctions">
   <Collection>
      <String>contains</String>
      <String>endswith</String>
      <String>startswith</String>
      <String>length</String>
      <String>indexof</String>
      <String>substring</String>
      <String>tolower</String>
      <String>toupper</String>
      <String>trim</String>
      <String>concat</String>
      <String>year</String>
      <String>month</String>
      <String>day</String>
      <String>hour</String>
      <String>minute</String>
      <String>second</String>
      <String>fractionalseconds</String>
      <String>round</String>
      <String>floor</String>
      <String>ceiling</String>
      <String>date</String>
      <String>time</String>
      <String>isof</String>
      <String>cast</String>
   </Collection>
</Annotation>

Aggregations

Aggregation annotations define the set of transformations understood by the Analytics OData endpoint.

<Annotation Term="Org.OData.Aggregation.V1.ApplySupported">
   <Record>
      <PropertyValue Property="Transformations">
         <Collection>
            <String>aggregate</String>
            <String>filter</String>
            <String>groupby</String>
            <String>compute</String>
            <String>expand</String>
         </Collection>
      </PropertyValue>
      <PropertyValue Property="CustomAggregationMethods ">
         <Collection>
           <String>ax.ApproxCountDistinct</String>
           <String>ax.StandardDeviation</String>
           <String>ax.StandardDeviationP</String>
           <String>ax.Variance</String>
           <String>ax.VarianceP</String>
         </Collection>
      </PropertyValue>
   </Record>
</Annotation>

<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType" Bool="true"/>
<Annotation Term="Org.OData.Capabilities.V1.BatchSupportType">
   <Record>
      <PropertyValue Property="Supported" Bool="true"/>
      <PropertyValue Property="ContinueOnErrorSupported" Bool="false"/>
      <PropertyValue Property="ReferencesInRequestBodiesSupported" Bool="false"/>
      <PropertyValue Property="ReferencesAcrossChangeSetsSupported" Bool="false"/>
      <PropertyValue Property="EtagReferencesSupported" Bool="false"/>
   </Record>
</Annotation>

Next steps

Data model for Analytics