RETURNING FieldSpec
If you don’t specify this clause, the default behavior is to return the IDs of all searchable objects in advanced search up to the maximum limit. The maximum limit is specified in the LIMITn clause or 2,000 (API version 28.0 and later), whichever is smaller. The returned IDs include custom objects even if there’s no custom tab. Search results list objects in the order specified in the clause. API version 27.0 and earlier support a maximum of 200 results.
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 can be omitted. A comma indicates that the indicated segment can appear more than one time.
RETURNING ObjectTypeName
[(FieldList [WHERE] [USING Listview=listview name] [ORDER BY Clause] [LIMIT n] [OFFSETn])]
[, ObjectTypeName [(FieldList [WHERE] [ORDER BY Clause] [LIMITn] [OFFSETn])]]
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. If you specify more than one ObjectTypeName, each object must be distinct; you can't repeat an ObjectTypeName within a single RETURNING clause. The search() call only returns objects specified in the RETURNING clause. |
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. If you want to use relationship fields, the format and supported depth is the same as SOQL. |
USING ListView= | Optional clause used to search within a single given object’s list view. Only one list view can be specified. Only the first 2,000 records of the list view are searched, according to the sort order the user has set for the list view. ListView=Recent searches for the most recently accessed items viewed or referenced by the current user. |
WHERE | Optional description of how search results for the given object are filtered,
based on individual field values. If unspecified, the search retrieves all the rows
in the object that are visible to the user. If you want to specify a WHERE clause, you must include a FieldList with at least one specified field.
The following example isn’t proper
syntax:
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. If you want to specify an
ORDER BY clause, you must include a FieldList with at least one specified field.
The following example isn’t proper
syntax:
|
LIMITn | 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. If you want to specify a LIMIT clause, you must include a FieldList with at least one specified field. The following
example isn’t proper
syntax:
|
OFFSETn | Optional clause used to specify the starting row offset into the result set
returned by your query. OFFSET can be used only when
querying a single object.
OFFSET must be the last clause
specified in a query. If you want to specify an OFFSET clause,
you must include a FieldList with at
least one specified field. The following example isn’t proper
syntax:
|
Example RETURNING Clauses
Search Type | Examples |
---|---|
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 |
Single object offset | FIND {MyProspect} RETURNING Contact(FirstName, LastName OFFSET 10) |
List view | FIND {MyAcccount} IN ALL FIELDS RETURNING Account(Id, Name USING ListView=ListViewName) |