soql/execute

Execute a custom SOQL (Salesforce Object Query Language) query and retrieve the first page of results.

SOQL Injection Warning: Never interpolate raw user input directly into a SOQL query string. This creates SOQL injection vulnerabilities. Always sanitize dynamic values, use static query patterns, or validate input before constructing the query.

When to Use

Complex multi-object queries using relationship traversal (e.g., Account with its Opportunities).
Aggregate queries using COUNT, SUM, or AVG across records.
Fetch recently modified records for an incremental sync with an external system.
Custom reports combining fields across multiple related objects.

Configuration

Connection

Field	Type	Required	Description
`InstanceUrl`	string	required	Salesforce org URL.
`AccessToken`	string	required	Valid OAuth2 access token.

Operation Fields

Field	Type	Required	Description
`Query`	string	required	A valid SOQL query string, e.g. `SELECT Id, Name, Email FROM Contact WHERE CreatedDate = LAST_30_DAYS LIMIT 100`.

Sample Configuration

{
  "Resource": "soql",
  "Operation": "execute",
  "InstanceUrl": "https://myorg.my.salesforce.com",
  "AccessToken": "{{credentials.salesforce.accessToken}}",
  "Query": "SELECT Id, Name, Email FROM Contact WHERE CreatedDate = LAST_30_DAYS LIMIT 100"
}

Validation Errors

Error Code	Condition
`CFG_MISSING_INSTANCE`	`InstanceUrl` is missing.
`CFG_MISSING_TOKEN`	`AccessToken` is missing.
`VAL_MISSING_FIELD`	`Query` is missing or empty.
`UNEXPECTED_ERROR`	Unexpected exception or SOQL syntax error.

Output

Success Port

Field	Type	Description
`records`	array	Array of result objects. Each object contains the fields specified in your SELECT clause.
`totalSize`	int	Total number of records matching the query in this response page.
`done`	bool	`true` if all results are included. `false` if more pages exist — use `soql/executeWithPagination` instead.
`resource`	string	Always `soql`.
`operation`	string	Always `execute`.

Error Port

Field	Type	Description
`errorCode`	string	Machine-readable error code.
`message`	string	Error description including SOQL error details.

Sample Output

{
  "records": [
    { "Id": "0035g000006LmnOPQ", "Name": "Alex Rivera", "Email": "alex@acme.com" },
    { "Id": "0035g000006XyzABC", "Name": "Sam Torres", "Email": "sam@beta.com" }
  ],
  "totalSize": 2,
  "done": true,
  "resource": "soql",
  "operation": "execute"
}

Expression Reference

Expression	Description
`{{nodes.SOQLQuery.records}}`	Array of query results.
`{{nodes.SOQLQuery.totalSize}}`	Number of records returned in this page.
`{{nodes.SOQLQuery.done}}`	Whether all pages are included.
`{{nodes.SOQLQuery.records[0].Id}}`	First result's Salesforce ID.

Node Policies & GuardRails

Policy	Detail
SOQL injection prevention	Never interpolate unsanitized user input into the `Query` field. Always construct queries from static templates with validated dynamic values.
Pagination check	If `done` is `false`, the result is paginated. Use `soql/executeWithPagination` to retrieve all records automatically.
LIMIT clause	Always include a `LIMIT` clause in queries unless you specifically need all records. Without a LIMIT, large orgs may return very large result sets.
Credential storage	Store `AccessToken` in BizFirst Credentials Manager.
Error port wiring	Always wire the error port. Invalid SOQL syntax routes to the error port with details.

Examples

Aggregate Count Query

{
  "Query": "SELECT COUNT(Id) totalLeads, Status FROM Lead WHERE CreatedDate = THIS_MONTH GROUP BY Status"
}
// records[0].totalLeads, records[0].Status

Multi-Object Relationship Query

{
  "Query": "SELECT Id, Name, (SELECT Id, LastName FROM Contacts) FROM Account WHERE Type = 'Customer' LIMIT 50"
}

Incremental Sync — Recently Modified

{
  "Query": "SELECT Id, Name, Email, LastModifiedDate FROM Contact WHERE LastModifiedDate > {{variables.lastSyncTimestamp}} LIMIT 500"
}