Get Data Graph Data with Lookup Keys
Queries data from a specific data graph using lookup keys. This endpoint allows you to retrieve records based on primary keys or lookup keys from any participating data model object (DMO).
A single request can return one or more data graph records. The result count depends on the lookup criteria and the number of unified records that match the provided lookup keys.
- HTTP Method: GET
- Availability: Data 360 v1.0, Salesforce v51.0
- Format: REST
- URI:
/api/v1/dataGraph/{dataGraphEntityName}?lookupKeys=[]&live=true/false&fields=[]&filters=[]
| Parameter | Type | Description |
|---|---|---|
| dataGraphEntityName | string | Required. The unique identifier of the data graph. Example: individual_eng_dg |
| Parameter | Type | Description |
|---|---|---|
| lookupKeys | string | Required. The lookup key in the format [DMO__dlm.field__c=value]. Example: [UnifiedLinkssotIndividualIr1__dlm.SourceRecordId__c=10000001] |
| live | boolean | Retrieves the latest data graph data if set to true. Retrieves the precalculated data graph data by default. |
| fields | string | Comma-separated list of fully qualified field paths to include in the response. Optional: Alias fields with originalPath=aliasName. |
| filters | string | Comma-separated list of filter expressions using comparison operators (=, >=, <=, >, <). Example: [DMO.Field >= 'value']. |
Note
You can pass multiple lookup keys in a single request. When multiple lookup keys are provided, the query only returns records that satisfy all specified lookup criteria. When using contact-based lookup, only one contact key (either an email address or a phone number) is supported per request.
You can query your data using a combination of DMO values included in the data graph. For all DMOs, search is supported by primary key and key qualifier. If a lookup key matches more than one unified record, the results will include multiple data graphs. Review these key definitions and search capabilities for data graphs:
- Value DMO: The materialized table in the data graph that contains the full data payload.
- Primary DMO: The DMO the data graph is built from.
- Link table DMO: A junction table that links a unified DMO to another DMO.
- Participating DMO: A DMO used to store many-to-many relationships and perform reverse lookups from the DMO to the data graph.
- Cross table search: A query method using a combination of the primary key and key qualifier from a value DMO with one or more fields from the primary DMO. To use cross table search, pass multiple values to the search call
[primaryKeyFieldOfValueDMO=value, columnOfPrimaryDMO=value], [primaryKeyFieldOfValueDMO=value, column1OfPrimaryDMO=value, column2OfPrimaryDMO=value]. You can also use the primary key of a participating table in cross table search. - Real-time data graphs: Search is only supported by primary key and key qualifier. Non-primary key lookups and cross-table searches are not supported.
| Search Scenario | Primary Key | Primary Key and Key Qualifier | Non-primary Key Fields |
|---|---|---|---|
| Primary DMO | [primaryDMO__dlm.PrimaryKeyField=value] | [primaryDMO__dlm.PrimaryKeyField=value, primaryDMO__dlm.keyQualifierField=value] | \[primaryDMO__dlm.anyField=value, primaryDMO__dlm.anyField2=value] |
| Value DMO | [valueDMO__dlm.PrimaryKeyField=value] | [valueDMO__dlm.PrimaryKeyField=value, valueDMO__dlm.keyQualifierField=value] | Not supported |
| Link Table DMO | [DMO__dlm.primaryKeyField=value] | [DMO__dlm.primaryKeyField=value, DMO__dlm.keyQualifierField=value] | [linkTableDMO__dlm.anyField=value, linkTableDMO__dlm.anyField2=value] |
| Participating DMO | [Participating__dlm.primaryKey=value] | Not supported | Not supported |
To help build lookup keys, use the GET /dataGraph/metadata?entityName={DataGraphName} API to explore a data graph schema and retrieve the full DMO and field definitions.
| Parameter | Type | Description |
|---|---|---|
| dataspace | string | The dataspace that the query executes in. |
By default, data graph queries return the complete graph with all fields and DMOs. Use the fields and filters parameters to retrieve only the specific fields and records you need.
Use projections when:
- Reducing LLM context size: Include only the fields relevant to your AI agent’s task.
- Optimizing API performance: Reduce data transfer by excluding unnecessary fields or DMOs.
- Targeting specific scenarios: Filter records based on business rules (order amounts, date ranges, status values).
- Downstream integration: Match alias fields to the schema expected by consuming applications.
Field Selection: Specify fully qualified field paths by using dot notation from the root DMO:
Field Aliasing: Rename fields in the output by using the = syntax:
Filtering Records: Use comparison operators to filter records within DMOs:
- Fields must exist in the data graph: Projections filter existing fields; they don’t add new ones.
- Hierarchy must be preserved: You must include the complete parent-child path; you can’t skip intermediate DMOs.
- No nested projections: You can’t apply a projection on top of another projection.
- Filters apply per DMO: You can’t filter a parent DMO based on grandchild values.
- No aggregations: Standard aggregation functions (SUM, AVG, COUNT) aren’t supported.
- No custom ordering: Results follow the data graph’s materialization-time sort order.
The response includes:
data: Array of objects containing the requested data. Multiple data graph records are returned if the lookup criteria match more than one unified record.done: Boolean indicating if all results have been returned
This example shows the data graph UnifiedIndividual_DG queried using the field SourceRecordIdc=10000001 on the related object UnifiedLinkssotIndividualIr1dlm. The request to query the data graph is made using these elements:
- DMO: UnifiedLinkssotIndividualIr1
- Primary Key name: SourceRecordId
- Primary Key value: 10000001
Request
Response
This example shows the data graph Individual_DG queried using the field SourceRecordIdc=10000001 on the related object LinkssotIndividualIr1dlm with the key qualifier kq_id__c=123. The request to query the data graph is made using these elements:
- DMO: LinkssotIndividualIr1
- Primary Key name: SourceRecordId
- Primary Key value: 10000001
- Key Qualifier ID: 123
Request
Response
This example retrieves only customer contact information and recent case data, filtering cases created after January 1, 2024:
Request
Response
Returns only the specified fields for the individual and their cases created after January 1, 2024, omitting all other DMOs and fields from the Data Graph.
This example identifies orders over $50,000 paid via COD:
Request
Response
Returns only orders matching both filter criteria with the specified fields.
This example renames fields to match a downstream system’s expected schema:
Request
Response
Returns the projected fields with aliased names instead of the original data graph field names.