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.
OData URL Conventions
An OData service URL has three main parts:
- The Service Root URL that Anzo provides. The service root URL is the metadata that describes all of the available feeds (tables).
- The optional Resource Path that narrows the scope of the available data to the individual table (class) level, property level, or the schema.
- 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.
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"
}
]
}
]
}