Consume Data Using the REST API
The REST API supports querying data stored in a data hub. In addition, the named query feature provides customized REST endpoints to consume data with predefined structures and query parameters.
Query Records
Query Multiple Records
Method |
GET |
---|---|
Base URL |
|
URL |
|
URL Structure |
The URL is configured using the following values:
|
Supported Parameters |
|
Response Format |
The response contains the list of records with the query expressions. Example 1. Multiple records query: sample response.
|
Query a Single Record
Method |
GET |
---|---|
Base URL |
|
URL |
|
URL Structure |
The URL is configured using the following values:
Record ID Structure The
For example, to query a source data record ( |
Supported Parameters |
|
Response Format |
The response contains the list of query expressions. Example 2. Single record query: sample response.
|
Count Records
Method |
GET |
---|---|
Base URL |
|
URL |
|
URL Structure |
The URL is configured using the following values:
|
Supported Parameters |
|
Response Format |
The response contains the count of records. Example 3. Record count query: sample response.
|
Use Named Queries
Named queries provide customized REST endpoints to consume data with a predefined structure and query parameters.
See Configure Named Queries for more information about Named Queries design. |
Query Multiple Records with a Named Query
Method |
GET |
||
---|---|---|---|
Base URL |
|
||
URL |
|
||
URL Structure |
The URL is configured using the following values:
|
||
Supported Parameters |
In addition, query parameters are passed to the query using their name. For example:
|
||
Response Format |
The response contains a hierarchy of objects corresponding to the named query definition. |
Count Records in a Named Query
Method |
GET |
---|---|
Base URL |
|
URL |
|
URL Structure |
The URL is configured using the following values:
|
Supported Parameters |
In addition, query parameters are passed to the query using their name. For example: |
Response Format |
The response contains the count of records returned by the named query. |
REST API Query Parameters
View Types
Certain REST endpoints use a view type as part of their URL. This view type, identified by an alias (GD
, MD
, etc) defines the type of data (golden, master, errors, etc) queried for the entity, using the endpoint.
GD
view./api/rest/query/HR/Employee/GD
MD
view./api/rest/query/HR/Employee/MD
Some of these view types must be contextualized to list records for a given Load ID or for a given point in history (identified by a Batch ID or an As of Date).
GH
view, as of the batch 22565/api/rest/query/HR/Employee/GH(22565)
Note that the other view types ignore this contextualization syntax. You must use Filtering to query a subset of the records.
/api/rest/query/HR/Employee/GD?$f=BatchID=22565
The following table lists the most common view types.
View Type | URL Contextualization | Description |
---|---|---|
|
Golden consolidated and certified records. |
|
|
Errors detected after master data consolidation (post-consolidation), for matching entities. |
|
|
Golden consolidated and certified records, filtered to only show those with errors (matching entities only) |
|
|
Golden History. |
|
|
|
Golden data history as of batch or golden data if not historized. This view type requires a |
|
Deleted golden records logs (and data for soft delete). |
|
|
Enriched, validated and cleansed master records. |
|
|
Master records history. |
|
|
|
Master data history as of batch or master data if not historized. This view type requires a |
|
Deleted master records logs (and data for soft delete). |
|
|
Source records from finished loads, |
|
|
Errors on source records, returned with the data from the erroneous record, |
|
|
Source records from finished loads, filtered to only show those with errors, |
|
|
|
Source data loaded by the publishers for a given load. This view type requires a |
|
Source data authored by users. |
|
|
Errors detected on source authoring data. |
|
|
Source data authored by users with errors. |
|
|
|
Source data authored by users for a given load. This view type requires a |
See also Built-in Views, Attributes and Lineage for more information about the views and their aliases. |
Pagination
When calls return a large number of records, it is recommended to page the record set. By requesting smaller subsets of data, you will get a response much faster than when requesting the entire, potentially large, record set.
Parameter | Default Value | Description |
---|---|---|
|
0 |
Defines the record offset for pagination. |
|
100 |
Defines the maximum number of returned records. |
/query/CustomerAndFinancialMDM/Customer/GD?$offset=20&$limit=10
Query Expressions
Query expressions define which values are returned by the query for each record.
Parameter | Default Value | Description |
---|---|---|
|
USER_ATTRS |
Defines the set of base attributes to include in the records, in addition to those specified using the
|
|
N/A |
Expression to include to the record in addition to, or to remove from, the base attributes (
|
/query/CustomerAndFinancialMDM/Customer/GD?$baseExprs=USER_ATTRS&$expr=Creator&$expr=CreationDate
/query/CustomerAndFinancialMDM/Customer/GD?$baseExprs=NONE&$expr=Name:Upper(CustomerName)&$expr=Revenue:TotalRevenue
/query/CustomerAndFinancialMDM/Customer/GD?$baseExprs=USER_ATTRS&$expr=$exclude:TotalRevenue
Sorting
Sort expressions define the order of the records in the response.
Parameter | Default Value | Description |
---|---|---|
|
None |
SemQL Order By Clause defining the order of the records in the response. |
/query/CustomerAndFinancialMDM/Customer/GD?$orderBy=TotalRevenue%20DESC,CustomerName%20ASC
Filtering
Use filters to request only specific records, that match the criteria you choose.
Parameter | Default Value | Description |
---|---|---|
|
SemQL filter. It is a SemQL condition applied to filter records. Only records matching this condition are returned. You can combine multiple SemQL filters in the same query. |
/query/CustomerAndFinancialMDM/Contact/GD?$f=FirstName%20LIKE%20%27Joe%25%27