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

Query lookupValues by using this schema.

The lookupValues type has these arguments.

  • objectApiName - The object API name of a supported object. 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 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.

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

The LookupValues type contains these fields.

  • targetApiName - API name of the target object type for this lookup result set.
  • records - A RecordLookupConnection 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.

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

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.

The RecordLookupEdge type ties together the record and its cursor.

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.

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

The RecordLookupPayload type contains these fields.

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

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

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.

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

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.

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

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.

The lookupValues type has these enumerations.

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

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

Get Lookup Values Examples