---
schema_version: "1"
id: 6d0da341739d48f95e617e4b086e1118b3f11eed78e8795ab0306326b81631e3
title: Get Lookup Values
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/graphql-api/graphql/guides/query/query-lookup-values.md
canonical_url: https://developer.salesforce.com/docs/platform/graphql/guide/query-lookup-values.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: a15c42c44dd4e7543e1146dd5cbcddeb1f8b2c1954369dc9eaab85eaa31316e2
products:
  - GraphQL API
---
# Get Lookup Values

| AVAILABLE API VERSION |
| --------------------- |
| API v68.0 and later   |

The `lookupValues` field of `LookupValues` type provides lookup search for Salesforce lookup and relationship fields. The GraphQL lookup values feature mirrors the UI API [Get Lookup Field Suggestions With POST](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_resources_lookup_post.htm) resource. The response includes matching records and display metadata for lookup target object types. This feature supports type-ahead search, recent lookups, and full search capabilities.

Pass in `lookupValues` in the `uiapi` field. For example, use `objectApiName: "Opportunity"` and `fieldApiName: "AccountId"` to return lookup values for the account lookup field on the opportunity object.

```
{
  uiapi {
    lookupValues(objectApiName: "Opportunity", fieldApiName: "AccountId") {
      # fields
    }
  }
}
```

## Lookup Values Schema

Query `lookupValues` by using this schema.

```
type UIAPI {
   lookupValues(
      objectApiName: String!
      fieldApiName: String!
      q: String
      searchType: LookupSearchType
      targetApiName: String
      sourceRecord: RecordSnapshotInput
   ): [LookupValues!]
}
```

The `lookupValues` type has these arguments.

- `objectApiName` - The object API name of a [supported object](https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/ui_api_all_supported_objects.htm). This argument is required.
- `fieldApiName` - The API name of the lookup or reference field on the object. This argument is required.
- `q` - Search query string for filtering lookup results. This argument is required with `TYPE_AHEAD` and `SEARCH` search types.
- `searchType` - Search strategy that the [LookupSearchType enum](#lookupsearchtype) provides. Default value is `RECENT`.
- `targetApiName` - For polymorphic lookup fields, filters results to a specific target object type.
- `sourceRecord` - A `RecordSnapshotInput` type with the record’s live, possibly unsaved, field values for filtered lookups that depend on other field values on the source record. This argument must contain only one top-level key and it must use the `ObjectApiName`, for example, `Opportunity: OpportunitySnapshotFields`.

## LookupValues Type

The `LookupValues` type returns matching records and display metadata for a single lookup target object type.

```
type LookupValues {
  targetApiName: String!
  records(first: Int, after: String, orderBy: RecordLookupOrderBy): RecordLookupConnection
  secondaryField: String
  suggestionsInfo: LookupDisplayInfo
  advancedDisplayFields: [LookupAdvancedDisplayInfoField!]
}
```

The `LookupValues` type contains these fields.

- `targetApiName` - API name of the target object type for this lookup result set.
- `records` - A [RecordLookupConnection](#recordlookupconnection-type) with relay-style paginated matching records.
  - `first` - Number of records per page. Default value is `10`.
  - `after` - Returns the results after the given cursor.
  - `orderBy` - A `RecordLookupOrderBy` type that accepts one field per target object, named after the object’s search type, such as `OpportunitySearch`. This argument isn’t supported for recent or type-ahead search types.
- `secondaryField` - API name of the secondary field to display alongside the primary name field.
- `suggestionsInfo` - Display layout and matching field configuration for lookup suggestions.
- `advancedDisplayFields` - Column configuration for the Advanced Lookup modal.

## RecordLookupConnection Type

The `RecordLookupConnection` type represents a result set of lookup records that ties together the records and page info.

```
type RecordLookupConnection {
  edges: [RecordLookupEdge]
  pageInfo: PageInfo!
  totalCount: Int
}
```

The `RecordLookupConnection` type contains these fields.

- `edges` - A list of RecordLookupEdge types.
- `pageInfo` - Information about the relative location in the result set.
- `totalCount` - This value is always null because the lookup service doesn’t provide a total count.

## RecordLookupEdge Type

The `RecordLookupEdge` type ties together the record and its cursor.

```
type RecordLookupEdge {
  node: RecordLookupPayload
  cursor: String!
}
```

The `RecordLookupEdge` type contains these fields.

- `node` - A RecordLookupPayload containing the record and secondary field value.
- `cursor` - An opaque string used to page directly to this item in the result set.

## RecordLookupPayload Type

The `RecordLookupPayload` type wraps a search record returned in lookup results.

```
type RecordLookupPayload {
  Record: RecordSearch
  SecondaryFieldValue: String
}
```

The `RecordLookupPayload` type contains these fields.

- `Record` - A RecordSearch record matching the lookup query.
- `SecondaryFieldValue` - Value of the secondary display field for this record.

## RecordSearch Interface

The `RecordSearch` interface is a marker interface for search record results. Field types are limited to those returnable by the search RETURNING clause.

```
interface RecordSearch {
  Id: ID!
  ApiName: String!
  DisplayValue: String
  WeakEtag: Long!
  LastModifiedById: IDValue
  LastModifiedDate: DateTimeValue
  SystemModstamp: DateTimeValue
  RecordTypeId: IDValue
}
```

The `RecordSearch` interface contains these fields.

- `Id` - The record ID.
- `ApiName` - The API name of the record’s object type.
- `DisplayValue` - The display value for the record (typically the name field).
- `WeakEtag` - The weak entity tag for the record.
- `LastModifiedById` - ID of the user who last modified the record.
- `LastModifiedDate` - Date and time when the record was last modified.
- `SystemModstamp` - System modification timestamp.
- `RecordTypeId` - ID of the record type, if applicable.

## LookupDisplayInfo Type

The `LookupDisplayInfo` type describes fields to display and fields to match on for lookup suggestions.

```
type LookupDisplayInfo {
  displayFields: [String!]!
  matchingFields: [String!]!
}
```

The `LookupDisplayInfo` type contains these fields.

- `displayFields` - List of field API names to display in lookup results.
- `matchingFields` - List of field API names to match against the search query.

## LookupAdvancedDisplayInfoField Type

The `LookupAdvancedDisplayInfoField` type describes a single field entry in the advanced lookup display configuration.

```
type LookupAdvancedDisplayInfoField {
  label: String
  objectApiName: String
  fieldPath: String
}
```

The `LookupAdvancedDisplayInfoField` type contains these fields.

- `label` - Display label for the field.
- `objectApiName` - API name of the object containing the field.
- `fieldPath` - Path to the field for relationship fields.

## Enumeration Types

The `lookupValues` type has these enumerations.

### LookupSearchType

The `LookupSearchType` enumeration specifies the search strategy for the lookup field.

```
enum LookupSearchType {
  RECENT
  TYPE_AHEAD
  SEARCH
}
```

- `RECENT` - Returns most recently used records for the lookup field in order of recency and doesn’t support custom ordering.
- `TYPE_AHEAD` - Returns records matching the query string for type-ahead suggestions in order of relevance and doesn’t support custom ordering or after cursor ordering.
- `SEARCH` - Performs a full search across the target object.

## See Also

[Get Lookup Values Examples](https://developer.salesforce.com/docs/platform/graphql/guide/query-lookup-values-examples.md)