View as Markdown
Salesforce icon

Salesforce ACTION

SOQL Query

Execute a SOQL query against Salesforce. This is the primary tool for querying Salesforce data — use for all structured queries. For free-text search across multiple objects, use Text Search instead.

When the user uses first-person language ('my', 'I', 'me'), filter by OwnerId using the userId from Get User Info. Use Describe Object to discover field names and picklist values before querying non-obvious fields.

SOQL syntax reference:

  • Basic: SELECT Id, Name, Email FROM Contact WHERE AccountId = '001xxx'
  • Operators: =, !=, >, <, >=, <=, LIKE '%text%', IN ('a','b'), NOT IN
  • Date literals: TODAY, THIS_MONTH, LAST_N_DAYS:30, THIS_QUARTER, LAST_QUARTER, THIS_YEAR
  • NULL checks: WHERE Email != null
  • Aggregates: SELECT StageName, COUNT(Id) c, SUM(Amount) s FROM Opportunity GROUP BY StageName
  • SOQL does NOT support the AS keyword — write COUNT(Id) c, not COUNT(Id) AS c
  • Reserved words cannot be aliasescount, sum, avg are reserved. Use short aliases like c, s, a
  • Cannot ORDER BY alias — repeat the aggregate: ORDER BY COUNT(Id) DESC, not ORDER BY c DESC
  • Parent relationship: SELECT Name, Account.Name FROM Contact
  • Child subquery: SELECT Name, (SELECT Name FROM Contacts) FROM Account
  • Sorting/limits: ORDER BY CreatedDate DESC LIMIT 10

Always include Id in SELECT. Include a clickable Salesforce link for every record using the format {instanceUrl}/lightning/r/{objectType}/{Id}/view (get instanceUrl from Get User Info). See the documentation

  • Action
  • Read only
  • OAuth
  • SDK
  • MCP

IMPLEMENTATION

Call this tool

Connect a user's Salesforce account once, then configure and run SOQL Query from your backend or agent.

import { PipedreamClient } from "@pipedream/sdk"

const pd = new PipedreamClient({
  projectId: process.env.PIPEDREAM_PROJECT_ID!,
  clientId: process.env.PIPEDREAM_CLIENT_ID!,
  clientSecret: process.env.PIPEDREAM_CLIENT_SECRET!,
  projectEnvironment: "production",
})

const result = await pd.actions.run({
  id: "salesforce_rest_api-soql-query",
  externalUserId: "{external_user_id}", // any stable ID for this user in your system
  configuredProps: {
    salesforce_rest_api: { authProvisionId: "apn_xxxxxxx" },
    query: "SOQL Query",
  },
})

console.log(result)

SCHEMA

Inputs

Pipedream supplies the connected account. Your application provides the operation-specific values below. Dynamic inputs are resolved against that user's account.

SOQL Query inputs
Property Type Description
query SOQL Query string
The SOQL query string to execute. Example: SELECT Id, Name, Amount, StageName FROM Opportunity WHERE OwnerId = '005xxx' AND StageName = 'Closed Won' ORDER BY Amount DESC LIMIT 10
Required

REFERENCE

Tool details

Behavior hints are published with the component in the Pipedream registry and surface as MCP tool annotations, so an agent can reason about a tool before it calls it.

Registry key
salesforce_rest_api-soql-query
Version
0.0.4
App
Salesforce
Authentication
OAuth
Read-only
Yes
Destructive
No
Open world
Yes