query()

Syntax

QueryResult = connection.query(string queryString);

Usage

Use the query() call to retrieve data from an 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 details about the syntax and rules used for queries, see the Salesforce SOQL and SOSL Reference Guide: SOQL SELECT Syntax.

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

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

An object must be configured to query using the API, and some objects can't be queried via the API. To determine if an object can be queried, use the describeSObjects() call on the object and inspect its queryable property.

If you use the enterprise WSDL, don't use describe to populate a select list. For example, if a Salesforce admin adds a field to the sObject after you consume it, the describe call pulls down the field but your toolkit won't know how to serialize it, and your integration fails.

Tip

The query() call automatically filters out deleted and archived records. Use queryAll() to include deleted or archived records in the results.

The query result object can return up to 2,000 rows of data. The max is also the default. However, to optimize performance, the returned batch size can be lower than the max or what's set in the request, based on the size and complexity of records queried. If the query results exceed the default, use the queryMore() call to retrieve additional rows in batches. Adjust the default results batch in the QueryOptions header. For more information and examples on updating batch size, see Change the Batch Size in Queries in the SOQL and SOSL Reference.

Queries that take longer than two minutes to process time out. For timed out queries, the API returns an API fault element of InvalidQueryLocatorFault. If a timeout occurs, refactor your query to return or scan a smaller amount of data.

When querying for fields of type base64 the query response object returns only one record at a time. You can't alter this process by changing the batch size of the query() call.

For multicurrency 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 $10 USD, the query expression looks 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')

Note

Arguments

Name	Type	Description
queryString	string	Contains the SOQL query, which specifies the object to query, the fields to return, and any conditions for including a specific object in the query. See Salesforce SOQL and SOSL Reference Guide.

Sample Code—Java

This sample executes a query that fetches the first names and last names of all contacts. It calls query() with the query string to get the first batch of records. This example also calls queryMore() in a loop to get subsequent batches of records until no records are returned. It writes the first and last names of the contacts queried to the console.

public void queryRecords() {
   QueryResult qResult = null;
   try {
      String soqlQuery = "SELECT FirstName, LastName FROM Contact";
      qResult = connection.query(soqlQuery);
      boolean done = false;
      if (qResult.getSize() > 0) {
         System.out.println("Logged-in user can see a total of "
            + qResult.getSize() + " contact records.");
         while (!done) {
            SObject[] records = qResult.getRecords();
            for (int i = 0; i < records.length; ++i) {
               Contact con = (Contact) records[i];
               String fName = con.getFirstName();
               String lName = con.getLastName();
               if (fName == null) {
                  System.out.println("Contact " + (i + 1) + ": " + lName);
               } else {
                  System.out.println("Contact " + (i + 1) + ": " + fName
                        + " " + lName);
               }
            }
            if (qResult.isDone()) {
               done = true;
            } else {
               qResult = connection.queryMore(qResult.getQueryLocator());
            }
         }
      } else {
         System.out.println("No records found.");
      }
      System.out.println("\nQuery succesfully executed.");
   } catch (ConnectionException ce) {
      ce.printStackTrace();
   }
}

Sample Code—C#

This sample executes a query that fetches the first names and last names of all contacts. It calls query() with the query string to get the first batch of records. This example also calls queryMore() in a loop to get subsequent batches of records until no records are returned. It writes the first and last names of the contacts queried to the console.

public void queryRecords()
{
   QueryResult qResult = null;
   try
   {
      String soqlQuery = "SELECT FirstName, LastName FROM Contact";
      qResult = binding.query(soqlQuery);
      Boolean done = false;
      if (qResult.size > 0)
      {
         Console.WriteLine("Logged-in user can see a total of "
            + qResult.size + " contact records.");
         while (!done)
         {
            sObject[] records = qResult.records;
            for (int i = 0; i < records.Length; ++i)
            {
               Contact con = (Contact)records[i];
               String fName = con.FirstName;
               String lName = con.LastName;
               if (fName == null)
               {
                  Console.WriteLine("Contact " + (i + 1) + ": " + lName);
               }
               else
               {
                  Console.WriteLine("Contact " + (i + 1) + ": " + fName
                        + " " + lName);
               }
            }
            if (qResult.done)
            {
               done = true;
            }
            else
            {
               qResult = binding.queryMore(qResult.queryLocator);
            }
         }
      }
      else
      {
         Console.WriteLine("No records found.");
      }
      Console.WriteLine("\nQuery succesfully executed.");
   }
   catch (SoapException e)
   {
      Console.WriteLine("An unexpected error has occurred: " +
                                 e.Message + "\n" + e.StackTrace);
   }
}