Salesforce SOQL toLabel() Function

In Salesforce SOQL, we use the toLabel() function in the queries to retrieve translated field labels in multi-language Salesforce orgs. This means it translates SOQL query results into the user’s language, which submits the query using the toLabel function. 

In this Salesforce tutorial, I will explain the toLabel() function in Salesforce and its use cases for executing SOQL queries in various scenarios.

What is the toLabel() function in Salesforce SOQL?

In Salesforce SOQL, the toLabel() function is used to translate the data from a field in the user’s locale language. It converts the results into the user’s language if the translation workbench is enabled.

The toLabel() function is available in all editions of Salesforce, and using this, we can translate the values of supported fields, including Picklist, Lookup, and standard fields, with translations.

Syntax to use the toLabel() function in Salesforce SOQL:

The basic syntax to execute the toLabel() function in Salesforce SOQL is as follows:

SELECT toLabel(<field name>) FROM <object name>

For example, you have to query the Picklist value Rating in your org language from the custom object Product_c. Then the query will be executed as follows.

SELECT toLabel(Rating__c) FROM Order_c

After executing the query, the returned records will be translated into the language of the user who issued the query.

If the translation settings are not enabled, then you might not get the translated values in the SOQL queries.

To enable the translation language settings, follow the steps below.

  • On the setup page, search for and select Translation Language Settings.
  • In the language setup, click on the Add button, select the Language, and select the Active checkbox.
  • In the section Identify Translators for this Language, select the users and click the Save button.

Now, the enabled language will be available for the selected users.

Use the toLabel() function to translate Picklist values in Salesforce SOQL

In Salesforce SOQL queries, we can use the toLabel() function to filter records using a translated picklist value from any standard or custom Salesforce object.

For example, we have to filter records using the picklist value “Is draft“, which is translated in German as “ist Entwurf“. Then, the SOQL will be executed as the below query.

SELECT Company, toLabel(Status)
FROM Lead
WHERE toLabel(Status) = 'ist Entwurf'

The query returns lead records with a picklist value for Status equal to ‘ist Entwurf.’ The comparison is made against the value of the user’s language. If no translation is available for the picklist, the comparison will be made against the master values.

There are some limitations to translating the picklist values using the toLabel() function.

  • The LIKE operator can only query on the label of the picklist, not on its API name.
  • We can’t use the toLabel() function with the operator ORDER BY. SOQL always uses the picklist’s defined order.
  • We can’t use the toLabel()function for division or currency ISO code picklists in a WHERE clause.

Using toLabel() function with the Lookup field in SOQL

The toLabel() function can also be used to fetch the translated names of Lookup field values, and for that, we can execute the SOQL query in the following w