retrieve()

Retrieves one or more records based on the specified IDs.

Syntax

sObject[] result = connection.retrieve(string fieldList, string sObjectType, ID ids[]);

Usage

Use the retrieve() call to retrieve individual records from an object. The client application passes the list of fields to retrieve, the object, and an array of record IDs to retrieve. The retrieve() call does not return records that have been deleted.

In general, you use retrieve() when you know in advance the IDs of the records to retrieve. Use query() instead to obtain records when you do not know the IDs or when you want to specify other selection criteria.

Client applications can use retrieve() to perform a client-side join. For example, a client application can run a query() to obtain a set of Opportunity records, iterate through the returned opportunity records, obtain the accountId for each opportunity, and then call retrieve() to obtain Account information for those accountIds.

Records for certain objects cannot be retrieved via the API. To retrieve a record via the retrieve() call, its object must be configured as retrieveable (retrieveable is true). To determine whether an object can be retrieved, your client application can invoke the describeSObjects() call on the object and inspect its retrievable property.

Your client application must be logged in with sufficient access rights to retrieve records within the specified object and to retrieve the fields in the specified field list. For more information, see Factors that Affect Data Access.

Sample Code—Java

This sample retrieves the Id, Name, and Website of the specified Account records. It writes the fields of the retrieved records to the console.

public void retrieveRecords(String[] ids) {
   try {
      SObject[] sObjects = connection.retrieve("ID, Name, Website",
            "Account", ids);
      // Verify that some objects were returned.
      // Even though we began with valid object IDs,
      // someone else might have deleted them in the meantime.
      if (sObjects != null) {
         for (int i = 0; i < sObjects.length; i++) {
            // Cast the SObject into an Account object
            Account retrievedAccount = (Account) sObjects[i];
            if (retrievedAccount != null) {
               System.out.println("Account ID: " + retrievedAccount.getId());
               System.out.println("Account Name: " + retrievedAccount.getName());
               System.out.println("Account Website: "
                     + retrievedAccount.getWebsite());
            }
         }
      }
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }
}

Sample Code—C#

This sample retrieves the Id, Name, and Website of the specified Account records. It writes the fields of the retrieved records to the console.

public void retrieveRecords(String[] ids)
{
   try
   {
      sObject[] sObjects = binding.retrieve("ID, Name, Website",
            "Account", ids);
      // Verify that some objects were returned.
      // Even though we began with valid object IDs,
      // someone else might have deleted them in the meantime.
      if (sObjects != null) { for (int i = 0; i < sObjects.Length; i++) { // Cast the SObject into an Account object Account retrievedAccount = (Account)sObjects[i]; if (retrievedAccount != null) { Console.WriteLine("Account ID: " + retrievedAccount.Id); Console.WriteLine("Account Name: " + retrievedAccount.Name); Console.WriteLine("Account Website: " + retrievedAccount.Website); } } } } catch (SoapException e) { Console.WriteLine("An unexpected error has occurred: " + e.Message + "\n" + e.StackTrace); } }

Arguments

Name Type Description
fieldList string List of one or more fields in the specified object, separated by commas. You must specify valid field names and must have read-level permissions to each specified field. The fieldList defines the ordering of fields in the result.
sObjectType string Object from which to retrieve data. The specified value must be a valid object for your organization. For a complete list of objects, see Standard Objects.
ids ID[] Array of one or more IDs of the objects to retrieve. You can pass a maximum of 2000 object IDs to the retrieve() call. For information on IDs, see ID Field Type.

Response

Name Type Description
result sObject[] Array of one or more sObjects representing individual records of the specified object. The number of sObjects returned in the array matches the number of IDs passed into the retrieve() call. If you do not have access to an object or if a passed ID is invalid, the array returns null for that object. For information on IDs, see ID Field Type.

Faults

InvalidSObjectFault

InvalidFieldFault

UnexpectedErrorFault

© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.