query

Executes a query against the specified object and returns data that matches the specified criteria.

Syntax

QueryResult = sfdc.query(string queryString);

Usage

Use the query call to retrieve data from an sforce API object. When a client application invokes the query call, it passes in a query expression that specifies the object to query, the fields to retrieve, and any conditions that determine whether a given object qualifies. For an extensive discussion about the syntax and rules used for queries, see sforce Object Query Language (SOQL).

Upon invocation, the sforce Web service executes the query against the specified object, caches the results of the query on the sforce Web service, and returns a query response object to the client application. The client application can then use methods on the query response object to iterate through rows in the query response and retrieve information.

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

Certain objects cannot be queried via the sforce API. To query an object via the query call, its object must be configured as queryable (queryable=True). To determine whether an object can be queried, your client application can invoke the describeSObject call on the object and inspect its queryable property.

The query response object contains up to 2,000 rows of data. If the query results exceed 2,000 rows, then the client application uses the queryMore call and a server-side cursor to retrieve additional rows in 2,000-row chunks. You can customize this option in the QueryOptions header, as described in Changing the Batch Size in Queries.

Queries that take longer than two minutes to process will be timed out. For timed out queries, the sforce Web service returns an ExceptionCode of QUERY_TIMEOUT. If a timeout occurs, refactor your query to return or scan a smaller amount of data.

When querying for fields of type Base64 (see Base64 Field Type), the query response object returns only one record at a time. You cannot alter this by changing the batch size of the query call.

For multi-currency organizations, special handling is required when querying currency fields containing values in different currencies. For example, if a client application is querying PricebookEntry objects based on values in the UnitPrice field, and if the UnitPrice amounts are expressed in different currencies, then the query logic must handle this case correctly. For example, if the query is trying to retrieve the product codes of all products with a unit price greater than or equal to $10USD. the query expression might look something like this:

select Product2Id,ProductCode,UnitPrice from PricebookEntry where (UnitPrice >= 
10 and CurrencyIsoCode="USD") or (UnitPrice >= 5.47 and CurrencyIsoCode="GBP") or 
(UnitPrice >= 8.19 and CurrencyIsoCode="EUR")

Sample Code-Java

public void querySample() { 
 
   QueryResult queryResult = null; 
   // Set up query options. Set the max batch size to 3 
   // so that we can exercise the queryMore call as well 
   _QueryOptions queryOptions = new _QueryOptions(); 
   queryOptions.setBatchSize(new Integer(3)); 
 
   // Add the query options to the SOAP header 
   binding.setHeader(new 
SforceServiceLocator().getServiceName().getNamespaceURI(), "QueryOptions", 
queryOptions); 
 
   // Invoke the query call and save the results 
   queryResult = binding.query("select FirstName, LastName from Contact"); 
   // Determine whether the query returned all the possible records 
      if (queryResult.isDone()) { 
      // Iterate through the records and process them 
         for (int i = 0; i < queryResult.getRecords().length; i++) { 
            Contact con = (Contact) queryResult.getRecords(i); 
            String firstName = con.getFirstName(); 
            String lastName = con.getLastName(); 
            System.out.println("Contact " + (i + 1) + ": " + firstName + " " + 
lastName); 
         } 
      } 
      else { 
         // Need to use queryMore call after processing 
         // the first set of records from the query result 
         while (queryResult.getRecords() != null) { 
            for (int i = 0; i < queryResult.getRecords().length; i++) { 
               Contact con = (Contact) queryResult.getRecords(i); 
               String firstName = con.getFirstName(); 
               String lastName = con.getLastName(); 
               System.out.println("Contact " + (i + 1) + ": " + firstName + " " + 
lastName); 
            } 
         // Invoke the queryMore call to get the next set of returned rows 
         queryResult = binding.queryMore(queryResult.getQueryLocator()); 
      } 
   } 
}

Sample Code-C#

private void contactQuery()  
{ 
   // Set the query options (Optional; default batch size is 2000) 
   binding.QueryOptionsValue = new QueryOptions(); 
   binding.QueryOptionsValue.batchSize = 10; 
   binding.QueryOptionsValue.batchSizeSpecified = true; 
    
   // Invoke the query call and save the result in a QueryResult 
   QueryResult qr = binding.query("select FirstName, LastName from contact where 
MailingPostalCode = '94062'"); 
 
   // Get the returned records 
   sObject[] records = qr.records; 
 
   // Determine whether some records where returned 
   if (records.Length > 0)  
   { 
      bool done = false;  // Use this for loop control 
      while (done = false)  
      { 
         for (int i=0; i<records.Length; i++)  
         { 
            Contact contact = (Contact)records[i]; 
            System.Diagnostics.Trace.WriteLine(contact.FirstName + " " + 
contact.LastName); 
         } 
         // Update the loop control 
         done = qr.done; 
         // Determine whether we need to retrieve another batch of result records 
         if (done == false)  
         {  
             qr = binding.queryMore(qr.queryLocator);  
             records = qr.records;  
         }  
    else  
        {  
            done = qr.done;  
       } 
   else 
   { 
      System.Diagnostics.Trace.WriteLine("no records matched criteria"); 
   } 
}

query

Syntax

Usage

Sample Code-Java

Sample Code-C#

Arguments

Response

Fault

See Also