OData Reference

The Anzo Data on Demand service follows the OData Version 4.0 specification, which defines the standard URL conventions and query options. This topic provides a quick reference for learning OData basics and viewing the supported string operators and output formats. It also provides some example queries.

The Anzo Data on Demand service does not impose limitations on the data that can be retrieved. However, some third-party applications do not support multi-value properties.

OData URL Conventions

An OData service URL has three main parts:

  1. The Service Root URL that Anzo provides. The service root URL is the metadata that describes all of the available feeds (tables).
  2. The optional Resource Path that narrows the scope of the available data to the individual table (class) level, property level, or the schema.
  3. The Query Options for analyzing the data.

For example, the following OData URL shows the service root from the Data on Demand screen in Anzo, a resource path that narrows the scope of the data to the Employees table (class), and query options that filter the result set to show data for the NA region only:

OData requests need to be URL-encoded. Typically you can configure programs to encode requests automatically. And browsers encode URLs that are pasted into the address bar.

Supported Query Operators

OData query options are used to dynamically query data via the endpoint and control the amount and order of the data returned. The Data on Demand service supports the following OData query operators. See Example OData Requests below for example queries that employ the operators.

Operator Description
$count Used to count the number of matching resources in the result set.
$expand Used to retrieve related data and include it in the results. When you query data via OData, the default response does not include related entities. The $expand option provides flexibility for exploring data across the data model. It allows the related information to be embedded in the response.
$filter Used to filter a result set. The expression specified with $filter is evaluated for each resource identified by the resource path, and only items where the expression evaluates to true are included in the response.
$format Used to specify the output format for the results. The supported formats are text/CSV, JSON, and XML. For example: $format=json
$metadata Used to return the schema, entity set, and property metadata.
$orderby Used to return results in ascending (asc) or descending (desc) order. If asc or desc is not specified, solutions are returned in ascending order.
$select Used to specify the subset of properties to include in the result set.
$skip Used to specify the number of solutions to exclude in the results. The $top and $skip OData query options are similar to the LIMIT and OFFSET clauses in SPARQL queries.
$top Used to limit the number of solutions that are returned.

Example OData Requests

This section demonstrates the use of OData query operators by providing examples of common types of OData requests.

The examples below are run against a sample graphmart, called LeagueGM, that contains data about the teams and players in a small local baseball league. The Data on Demand endpoint is named LeagueData. The following service root URL was created by Anzo: 

https://10.100.0.10/dataondemand/LeagueGM/LeagueData

For readability, the examples below abbreviate "https://10.100.0.10/dataondemand" to dataondemand. In addition, the examples are not URL-encoded.

The data has Leagues, Teams, Players, and Positions classes (or entities in OData). And the image below shows a graph view of the data model. To view the TriG version of the model, click here.

To view the instance data for each class, you can click a link below to view the data for that class. The data is in JSON format.

Leagues

Teams

Players

Positions

Retrieving Metadata

The request below retrieves the schema, entity set, and property metadata for the endpoint.

dataondemand/LeagueGM/LeagueData/$metadata

The results are in XML format. A snippet of the results is shown below. To view the complete response, click here.

<?xml version="1.0" encoding="UTF-8"?>
<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
  <edmx:DataServices>
    <Schema xmlns="http://docs.oasis-open.org/odata/ns/edm" Namespace="Feeds">
      <EntityContainer Name="Default">
        <EntitySet Name="Leagues" EntityType="com.cambridgesemantics.ont.autogen.LeagueDict.LeagueData.Leagues">
          <NavigationPropertyBinding Path="LeagueToTeam" Target="Teams"/>
        </EntitySet>
        <EntitySet Name="Teams" EntityType="com.cambridgesemantics.ont.autogen.LeagueDict.LeagueData.Teams">
          <NavigationPropertyBinding Path="TeamToLeague" Target="Leagues"/>
          <NavigationPropertyBinding Path="TeamToPlayer" Target="Players"/>
        </EntitySet>
        <EntitySet Name="Positions" EntityType="com.cambridgesemantics.ont.autogen.LeagueDict.LeagueData.Positions">
          <NavigationPropertyBinding Path="PositionToPlayer" Target="Players"/>
        </EntitySet>
        <EntitySet Name="Players" EntityType="com.cambridgesemantics.ont.autogen.LeagueDict.LeagueData.Players">
          <NavigationPropertyBinding Path="PlayerToPosition" Target="Positions"/>
          <NavigationPropertyBinding Path="PlayerToTeam" Target="Teams"/>
        </EntitySet>
      </EntityContainer>
    </Schema>
...

Counting an Entity

The request below returns the number of teams in the graphmart. Adding the resource path Teams to the request narrows the scope to the Teams entity (or class in Anzo).

dataondemand/LeagueGM/LeagueData/Teams/$count

Result

4

This request returns the number of players:

dataondemand/LeagueGM/LeagueData/Players/$count

Result

12

Counting a Property of an Entity

The request below counts the number of players on the Al Thomas team. The request uses the team_key to identify the team and the TeamToPlayer to identify each player.

dataondemand/LeagueGM/LeagueData/Teams('aHR0cDovL2NzaS5jb20vVGVhbXMvMQ')/TeamToPlayer/$count

Result

3

This request counts the number of positions played by James Smith:

dataondemand/LeagueGM/LeagueData/Players('aHR0cDovL2NzaS5jb20vUGxheWVycy8y')/PlayerToPosition/$count

Result

2

Filtering Data via Text Search

The request below filters the results to show data for the TeamName that equals "Black Sox." The request also returns results in JSON format: 

dataondemand/LeagueGM/LeagueData/Teams?$filter=TeamName eq 'Black Sox'&$format=json

Result

{
  "@odata.context": "https://10.100.0.10/dataondemand/LeagueGM/LeagueData/$metadata#Teams",
  "value": [
    {
      "teams_key": "aHR0cDovL2NzaS5jb20vVGVhbXMvMg",
      "TeamId": 2,
      "teamtoleague_key": [
          "aHR0cDovL2NzaS5jb20vTGVhZ3Vlcy8x"
      ],
      "TeamName": "Black Sox",
      "teamtoplayer_key": [
          "aHR0cDovL2NzaS5jb20vUGxheWVycy80",
          "aHR0cDovL2NzaS5jb20vUGxheWVycy81",
          "aHR0cDovL2NzaS5jb20vUGxheWVycy82"
      ]
    }
  ]
}

This request filters the data to find the players whose name contains "Ted."

dataondemand/LeagueGM/LeagueData/Players?$filter=contains(PlayerName,'Ted')

The request can also use "startswith" in place of contains to filter specifically for player names that start with "Ted."

dataondemand/LeagueGM/LeagueData/Players?$filter=startswith(PlayerName,'Ted')

Result

{
  "@odata.context": "https://10.100.0.10/dataondemand/LeagueGM/LeagueData/$metadata#Players",
  "value": [
    {
      "players_key": "aHR0cDovL2NzaS5jb20vUGxheWVycy8xMA",
      "playertoposition_key": [
          "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzM",
          "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzI"
      ],
      "PlayerId": 10,
      "playertoteam_key": [
          "aHR0cDovL2NzaS5jb20vVGVhbXMvNA"
      ],
      "PlayerName": "Ted James",
      "DefensiveRating": 92.55
    },
    {
      "players_key": "aHR0cDovL2NzaS5jb20vUGxheWVycy84",
      "playertoposition_key": [
          "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzI",
          "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzEw"
      ],
      "PlayerId": 8,
      "playertoteam_key": [
          "aHR0cDovL2NzaS5jb20vVGVhbXMvMw"
      ],
      "PlayerName": "Ted Sale",
      "DefensiveRating": 77.33
    }
  ]
}

Selecting Properties and Ordering Results

The request below selects player names and their defensive ratings. The results are ordered by defensive rating in descending order so that the player with the highest defensive rating is listed first. The request also formats the results in text/csv.

dataondemand/LeagueGM/LeagueData/Players?$select=PlayerName,DefensiveRating&$orderby=DefensiveRating desc&$format=text/csv

Result

PlayerName,DefensiveRating
James Smith,98.33
Alex Granderson,98.22
Matt Butler,95.66
Tim Hooper,93.43
Steve Jones,93.28
Ted James,92.55
Fred Wynn,88.68
Jared Bonds,86.34
Billy Roper,83.44
Mike Magazine,78.33
Ted Sale,77.33
Chris Underwood,66.22

Expanding the Results to Include Related Entities

The request below uses the $expand operator to retrieve data from the Players entity and include the related Positions data for each player. For this example, the request limits the number of results returned to 2 players by adding $top=2:

dataondemand/LeagueGM/LeagueData/Players?$expand=PlayerToPosition&$top=2

Result

{
  "@odata.context": "https://10.100.0.10/dataondemand/LeagueGM/LeagueData/$metadata#Players",
  "value": [
    {
      "players_key": "aHR0cDovL2NzaS5jb20vUGxheWVycy8x",
      "playertoposition_key": [
          "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzg"
      ],
      "PlayerId": 1,
      "playertoteam_key": [
          "aHR0cDovL2NzaS5jb20vVGVhbXMvMQ"
      ],
      "PlayerName": "Steve Jones",
      "DefensiveRating": 93.28,
      "PlayerToPosition": [
          {
            "positions_key": "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzg",
            "PositionId": 8,
            "ShortName": "CF",
            "positiontoplayer_key": [
                "aHR0cDovL2NzaS5jb20vUGxheWVycy8xMg",
                "aHR0cDovL2NzaS5jb20vUGxheWVycy8x"
            ],
            "Description": "Centerfield"
          }
      ]
    },
    {
      "players_key": "aHR0cDovL2NzaS5jb20vUGxheWVycy8xMA",
      "playertoposition_key": [
          "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzI",
          "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzM"
      ],
      "PlayerId": 10,
      "playertoteam_key": [
          "aHR0cDovL2NzaS5jb20vVGVhbXMvNA"
      ],
      "PlayerName": "Ted James",
      "DefensiveRating": 92.55,
      "PlayerToPosition": [
          {
            "positions_key": "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzI",
            "PositionId": 2,
            "ShortName": "C",
            "positiontoplayer_key": [
                "aHR0cDovL2NzaS5jb20vUGxheWVycy84",
                "aHR0cDovL2NzaS5jb20vUGxheWVycy8xMA"
            ],
            "Description": "Catcher"
          },
          {
            "positions_key": "aHR0cDovL2NzaS5jb20vUG9zaXRpb25zLzM",
            "PositionId": 3,
            "ShortName": "1B",
            "positiontoplayer_key": [
                "aHR0cDovL2NzaS5jb20vUGxheWVycy83",
                "aHR0cDovL2NzaS5jb20vUGxheWVycy8xMA"
            ],
            "Description": "First Base"
          }
       ]
     }
   ]
}
Related Topics