RETURNING FieldSpec

The optional RETURNING clause allows you to specify the information that is returned in the text search result. If unspecified, then the default behavior is to return the IDs of all objects that are searchable in advanced search as well as custom objects (even if they don't have a custom tab), up to the maximum specified in the LIMIT n clause or 200, whichever is smaller. In the results, objects are listed in the order specified in the clause. For information on searchable fields in advanced and global search, see “Search Fields” in the Salesforce online help.

Note

Articles, documents, feed comments, feed items, files, products, and solutions must be specified explicitly in a RETURNING clause to be returned in search results. For example:

FIND {MyProspect} RETURNING KnowledgeArticleVersion, Document, FeedComment, FeedItem, ContentVersion, Product2, Solution

Use the RETURNING clause to restrict the results data that is returned from the search() call. For information on IDs, see ID Field Type.

Syntax

In the following syntax statement, square brackets [] represent optional elements that may be omitted. A comma indicates that the indicated segment can appear more than one time.

RETURNING ObjectTypeName 
[(FieldList [WHERE conditionExpression] [ORDER BY clause] [LIMIT n])] 
[, ObjectTypeName [(FieldList) [WHERE conditionExpression] [ORDER BY clause] [LIMIT n])]]

RETURNING can contain the following elements:

Name	Description
ObjectTypeName	Object to return. If specified, then the search() call returns the IDs of all found objects matching the specified object. Must be a valid sObject type. You can specify multiple objects, separated by commas. Objects not specified in the RETURNING clause are not returned by the search() call.
FieldList	Optional list of one or more fields to return for a given object, separated by commas. If you specify one or more fields, the fields are returned for all found objects.
WHERE conditionExpression	Optional description of how search results for the given object should be filtered, based on individual field values. If unspecified, the search retrieves all the rows in the object that are visible to the user. Note that if you want to specify a WHERE clause, you must include a FieldList with at least one specified field. For example, this is not legal syntax: RETURNING Account (WHERE name like 'test') But this is: RETURNING Account (Name, Industry WHERE Name like 'test') See conditionExpression for more information.
ORDER BY clause	Optional description of how to order the returned result, including ascending and descending order, and how nulls are ordered. You can supply more than one ORDER BY clause. Note that if you want to specify an ORDER BY clause, you must include a FieldList with at least one specified field. For example, this is not legal syntax: RETURNING Account (ORDER BY id) But this is: RETURNING Account (Name, Industry ORDER BY Name)
LIMIT n	Optional clause that sets the maximum number of records returned for the given object. If unspecified, all matching records are returned, up to the limit set for the query as a whole. Note that if you want to specify a LIMIT clause, you must include a FieldList with at least one specified field. For example, this is not legal syntax: RETURNING Account (LIMIT 10) But this is: RETURNING Account (Name, Industry LIMIT 10)

Note

The RETURNING clause affects what data is returned, not what data is searched. The IN clause affects what data is searched.

Example RETURNING Clauses

Search Type	Example(s)
No Field Spec	FIND {MyProspect}
One sObject, no fields	FIND {MyProspect} RETURNING Contact
Multiple sObject objects, no fields	FIND {MyProspect} RETURNING Contact, Lead
One sObject, one or more fields	FIND {MyProspect} RETURNING Account(Name)
	FIND {MyProspect} RETURNING Contact(FirstName, LastName)
Custom sObject	FIND {MyProspect} RETURNING CustomObject_c
	FIND {MyProspect} RETURNING CustomObject_c(CustomField_c)
Multiple sObject objects, one or more fields, limits	FIND {MyProspect} RETURNING Contact(FirstName, LastName LIMIT 10), Account(Name, Industry)
Multiple sObject objects, mixed number of fields	FIND {MyProspect} RETURNING Contact(FirstName, LastName), Account, Lead(FirstName)
Unsearchable sObject objects	FIND {MyProspect} RETURNING RecordType
	FIND {MyProspect} RETURNING Pricebook
Invalid sObject objects	FIND {MyProspect} RETURNING FooBar
Invalid sObject field	FIND {MyProspect} RETURNING Contact(fooBar)
Single object limit	FIND {MyProspect} RETURNING Contact(FirstName, LastName LIMIT 10)
Multiple object limits and a query limit	FIND {MyProspect} RETURNING Contact(FirstName, LastName LIMIT 20), Account(Name, Industry LIMIT 10), Opportunity LIMIT 50

Note

Apex requires that you surround SOQL and SOSL statements with square brackets in order to use them on the fly. Additionally, Apex script variables and expressions can be used if preceded by a colon (:).