Skip to contents

[Stable]

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

Usage

sf_query(
  soql,
  object_name = NULL,
  queryall = FALSE,
  guess_types = TRUE,
  api_type = c("REST", "SOAP", "Bulk 1.0", "Bulk 2.0"),
  control = list(...),
  ...,
  page_size = deprecated(),
  next_records_url = NULL,
  bind_using_character_cols = deprecated(),
  object_name_append = FALSE,
  object_name_as_col = FALSE,
  verbose = FALSE
)

Arguments

soql

character; a string defining a SOQL query (e.g. "SELECT Id, Name FROM Account").

object_name

character; the name of the Salesforce object that the function is operating against (e.g. "Account", "Contact", "CustomObject__c").

queryall

logical; indicating if the query recordset should include records that have been deleted because of a merge or delete. Setting this argument to TRUE will also return information about archived Task and Event records. It is available in API versions 29.0 and later.

guess_types

logical; indicating whether or not to use col_guess() to try and cast the data returned in the recordset. If TRUE then col_guess() is used along with anytime() and anydate(). If FALSE then all fields will be returned as character. Specifying FALSE helpful when guessing the column data type will result in NA values and you would like to return the results as strings and then cast in your script according to your unique specifications.

api_type

character; one of "REST", "SOAP", "Bulk 1.0", or "Bulk 2.0" indicating which API to use when making the request.

control

list; a list of parameters for controlling the behavior of the API call being used. For more information of what parameters are available look at the documentation for sf_control.

...

arguments passed to sf_control or further downstream to sf_query_bulk.

page_size

numeric; a number between 200 and 2000 indicating the number of records per page that are returned. Speed benchmarks should be done to better understand the speed implications of choosing high or low values of this argument.

next_records_url

character (leave as NULL); a string used internally by the function to paginate through to more records until complete

bind_using_character_cols

logical; an indicator of whether to cast the data to all character columns to ensure that bind_rows does not fail because two paginated recordsets have differing datatypes for the same column. Set this to TRUE rarely, typically only when having this set to FALSE returns an error or you want all columns in the data to be character.

object_name_append

logical; whether to include the object type (e.g. Account or Contact) as part of the column names (e.g. Account.Name).

object_name_as_col

logical; whether to include the object type (e.g. Account or Contact) as a new column.

verbose

logical; an indicator of whether to print additional detail for each API call, which is useful for debugging. More specifically, when set to TRUE the URL, header, and body will be printed for each request, along with additional diagnostic information where available.

Value

tbl_df of records

Note

Bulk API query doesn't support the following SOQL:

  • COUNT

  • ROLLUP

  • SUM

  • GROUP BY CUBE

  • OFFSET

  • Nested SOQL queries

  • Relationship fields

Additionally, Bulk API can't access or query compound address or compound geolocation fields.

Examples

if (FALSE) { # \dontrun{
sf_query("SELECT Id, Account.Name, Email FROM Contact LIMIT 10")
} # }