# 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.

## Syntax

- **HTTP Method**: GET
- **Availability**: Data 360 v1.0, Salesforce v51.0
- **Format**: REST
- **URI**: `/api/v1/dataGraph/{dataGraphEntityName}?lookupKeys=[]&live=true/false&fields=[]&filters=[]`

## Path Parameters

| Parameter           | Type   | Description                                                                     |
| ------------------- | ------ | ------------------------------------------------------------------------------- |
| dataGraphEntityName | string | Required. The unique identifier of the data graph. Example: `individual_eng_dg` |

## Query Parameters

| 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

:::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.
:::

### Search Types

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.

## Header Parameters

| Parameter | Type   | Description                               |
| --------- | ------ | ----------------------------------------- |
| dataspace | string | The dataspace that the query executes in. |

## Using Projections to Retrieve Specific Fields

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.

### When to Use Projections

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.

### Projection Syntax

**Field Selection**: Specify fully qualified field paths by using dot notation from the root DMO:

```
fields=[
  UnifiedIndividual.ID,
  UnifiedIndividual.FirstName,
  UnifiedIndividual.Case.CaseNumber
]
```

**Field Aliasing**: Rename fields in the output by using the `=` syntax:

```
fields=[
  UnifiedIndividual.ID=customer_id,
  UnifiedIndividual.FirstName=first_name
]
```

**Filtering Records**: Use comparison operators to filter records within DMOs:

```
fields=[
  Case.CreatedDate >= '2024-01-01',
  SalesOrder.Amount > 50000
]
```

### Projection Limitations

- **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.

## Response Structure

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

## Examples

### Primary Key Example

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**

```http
GET https://{TSE}.360a.salesforce.com/api/v1/dataGraph/UnifiedIndividual_DG?lookupKeys=[UnifiedLinkssotIndividualIr1__dlm.SourceRecordId__c=10000001]
```

**Response**

```json
{
  "data": [
    {
      "json_blob__c": "{\"ssot__Id__c\":\"eabf8b8a0ec83c3aea36ac8359b65f97\",\"UnifiedLinkssotIndividualIr1__dlm\":[{\"SourceRecordId__c\":\"10000001\",\"UnifiedRecordId__c\":\"eabf8b8a0ec83c3aea36ac8359b65f97\",\"ssot__Individual__dlm\":[{\"ssot__FirstName__c\":\"Jean\",\"ssot__Id__c\":\"10000001\",\"ssot__LastName__c\":\"Johnson\",\"ssot__SalesOrder__dlm\":[{\"ssot__PurchaseOrderDate__c\":\"2023-07-26T07:37:57.927Z\",\"ssot__Id__c\":\"100002\",\"ssot__SoldToCustomerId__c\":\"10000001\",\"ssot__TotalProductAmount__c\":557.000000000000000000},{\"ssot__PurchaseOrderDate__c\":\"2023-07-26T19:52:26.525Z\",\"ssot__Id__c\":\"100001\",\"ssot__SoldToCustomerId__c\":\"10000001\",\"ssot__TotalProductAmount__c\":192.000000000000000000},{\"ssot__PurchaseOrderDate__c\":\"2023-07-06T20:30:18.255Z\",\"ssot__Id__c\":\"100005\",\"ssot__SoldToCustomerId__c\":\"10000001\",\"ssot__TotalProductAmount__c\":590.000000000000000000}]}]}]}"
    }
  ],
  "done": true
}
```

### Primary Key and Key Qualifier Example

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**

```http
GET https://{TSE}.360a.salesforce.com/api/v1/dataGraph/Individual_DG?lookupKeys=[LinkssotIndividualIr1__dlm.SourceRecordId__c=10000001]
```

**Response**

```json
{
  "data": [
    {
      "json_blob__c": "{\"ssot__Id__c\":\"eabf8b8a0ec83c3aea36ac8359b65f97\",\"LinkssotIndividualIr1__dlm\":[{\"SourceRecordId__c\":\"10000001\",\"RecordId__c\":\"eabf8b8a0ec83c3aea36ac8359b65f97\",\"ssot__Individual__dlm\":[{\"ssot__FirstName__c\":\"Jean\",\"ssot__Id__c\":\"10000001\",\"ssot__LastName__c\":\"Johnson\",\"ssot__SalesOrder__dlm\":[{\"ssot__PurchaseOrderDate__c\":\"2023-07-26T07:37:57.927Z\",\"ssot__Id__c\":\"100002\",\"ssot__SoldToCustomerId__c\":\"10000001\",\"ssot__TotalProductAmount__c\":557.000000000000000000},{\"ssot__PurchaseOrderDate__c\":\"2023-07-26T19:52:26.525Z\",\"ssot__Id__c\":\"100001\",\"ssot__SoldToCustomerId__c\":\"10000001\",\"ssot__TotalProductAmount__c\":192.000000000000000000},{\"ssot__PurchaseOrderDate__c\":\"2023-07-06T20:30:18.255Z\",\"ssot__Id__c\":\"100005\",\"ssot__SoldToCustomerId__c\":\"10000001\",\"ssot__TotalProductAmount__c\":590.000000000000000000}]}]}]}"
    }
  ],
  "done": true
}
```

### Projection Example: Customer Support Context

This example retrieves only customer contact information and recent case data, filtering cases created after January 1, 2024:

**Request**

```http
GET https://{TSE}.360a.salesforce.com/api/v1/dataGraph/UnifiedIndividual_DG?lookupKeys=[UnifiedIndividual__dlm.ID__c=100005]&fields=[UnifiedIndividual.ID,UnifiedIndividual.FirstName,UnifiedIndividual.ContactPointEmail.EmailAddress,UnifiedIndividual.Case.CaseNumber,UnifiedIndividual.Case.Status,UnifiedIndividual.Case.CreatedDate]&filters=[Case.CreatedDate>='2024-01-01']
```

**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.

### Projection Example: High-Value Order Filtering

This example identifies orders over $50,000 paid via COD:

**Request**

```http
GET https://{TSE}.360a.salesforce.com/api/v1/dataGraph/UnifiedIndividual_DG?lookupKeys=[UnifiedIndividual__dlm.ID__c=100005]&fields=[UnifiedIndividual.ID,UnifiedIndividual.SalesOrder.OrderId,UnifiedIndividual.SalesOrder.Amount,UnifiedIndividual.SalesOrder.PaymentMethod]&filters=[SalesOrder.Amount>50000,SalesOrder.PaymentMethod='COD']
```

**Response**

Returns only orders matching both filter criteria with the specified fields.

### Projection Example: Field Aliasing for Integration

This example renames fields to match a downstream system's expected schema:

**Request**

```http
GET https://{TSE}.360a.salesforce.com/api/v1/dataGraph/UnifiedIndividual_DG?lookupKeys=[UnifiedIndividual__dlm.ID__c=100005]&fields=[UnifiedIndividual.ID=customer_id,UnifiedIndividual.FirstName=first_name,UnifiedIndividual.LastName=last_name,UnifiedIndividual.ContactPointEmail.EmailAddress=email]
```

**Response**

Returns the projected fields with aliased names instead of the original data graph field names.