Query

---

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

Syntax

QueryResultSet3[] = Query(qString As String, async As Boolean); 

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 an extensive discussion about the syntax and rules used for queries, see Sforce Object Query Language (SOQL).

Upon invocation, the Web service executes the query against the specified object, caches the results of the query on the 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 API. To query an object via the Query call, its object must be configured as queryable (Queryable is True in the SObject3).Queries that take longer than two minutes to process will be timed out. For timed out queries, the AppExchange Web service returns an SError. 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. Note that client applications are responsible for the conversion of Base64 values between binary data and the Strings representing the Base64 data.

:: Note

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-VBA

Query-Synchronous Example

Public Function Query() 
 
    Dim qr As QueryResultSet3 
    Dim v As Variant 
    Dim s As SObject3 
     
    Set qr = g_sfApi.Query("select * from task", False) 
 
    For Each v In qr 
 
'loop through the results 
'cast to a sobject3 to see more helpful debug info 
 
        Set s = v 
 
'use the object 
 
        s("Name") = "Query" 
 
        's.Update 
 
    Next v 
 
End Function 

Query-Asynchronous Example

Public Function AsyncQuery() 
 
'run a query 
 
    g_sfApi.Query "select * from task", True 
 
End Function 
 
'Asynchronous query callback 
 
Public Sub g_sfApi_QueryFinished(qr As QueryResultSet3) 
 
    Dim v As Variant 
    Dim s As SObject3 
     
'check session for errors 
 
    If g_sfApi.Error <> NO_SF_ERROR Then 
     
'query has failed 
     
        Debug.Print g_sfApi.ErrorMessage 
     
        Exit Sub 
     
    End If 
     
'look at query result attributes 
'The size is the TOTAL size of the result 
 
    Debug.Print "Size of result set:" & qr.Size 
     
    For Each v In qr 
     
'loop through the results 
'cast to a sobject3 to see more helpful debug info 
         
        Set s = v 
         
'use the object 
'NOTE you cannot call async methods until this method returns 
 
        's.Update 
     
    Next v 
 
End Sub 

Arguments

Name	Type	Description
qString	String	Query string that specifies the object to query, the fields to return, and any conditions for including a specific object in the query. For more information, see Sforce Object Query Language (SOQL).
async	Boolean	Specifies whether this invocation should be processed asynchronously (True) or not (False).

Event

QueryFinished

See Also

Sforce Object Query Language (SOQL)

Using API Calls

Changing the Batch Size in Queries