Retrieve and Read Salesforce Records via the MuleSoft Salesforce Connector

To retrieve and read Salesforce records with the MuleSoft Salesforce Connector, use one of three read operations: Query to run a SOQL statement, Query All to include deleted and archived records, and Retrieve to fetch specific records by their IDs. Query with SOQL is the workhorse for most reads, and the connector streams large result sets automatically so you can process them without running out of memory.

This guide covers each read operation, how to write the SOQL, how to handle large data sets, and how to fix the errors that show up most — the read side of any MuleSoft and Salesforce integration.

‍

What Reading Salesforce Records Means

Reading records means pulling data out of Salesforce through the MuleSoft Salesforce Connector - querying records so a Mule application can process them, send them to another system, or make decisions on them. It's the read half of an integration; the write half is pushing records in.

In a typical flow, a Mule application queries Salesforce on a schedule or in response to an event, maps the results with DataWeave, and hands them to the next system — a data warehouse, an ERP, or a report. Before it reads anything, the connector authenticates with a Salesforce connection and needs read access to the objects and fields you query.

Query, Query All, or Retrieve: The Read Operations

The connector's read operations are Query, Query All, Retrieve, and Bulk Query. Picking the right one keeps your reads fast and inside API limits. For the exact parameters each takes, keep the connector's operations reference and documentation open as you build.
‍

The rule of thumb: use Query for everyday reads, Retrieve when you already hold the IDs, and Bulk Query when you're pulling more than the standard query limits comfortably handle.
‍

How to Query Salesforce Records with SOQL

Query is the operation you'll use most. It takes a SOQL statement and returns the matching records. Here's the flow.

• Write the SOQL. Select only the fields you need, for example SELECT Id, Name, Email FROM Contact WHERE CreatedDate = TODAY. Fewer fields mean faster, lighter reads.
• Add the Query operation to your flow and paste the SOQL into it.
• Filter selectively. Put a WHERE clause on indexed fields (Id, Name, external IDs, dates) so Salesforce can run the query efficiently.
• Process the results. The connector returns the records as a stream you can iterate with For Each or Batch, then map with DataWeave.

Keep queries selective. A broad SELECT across millions of rows without a good filter will time out or hit limits - narrow it with WHERE, LIMIT, and indexed fields.
‍

How to Retrieve Records by ID

When you already have the record IDs  carried from an earlier step or another system - Retrieve is faster and simpler than a query. Give it the object, the list of IDs, and the fields you want back, and it returns those records directly.-

Use Retrieve instead of a Query with a long WHERE Id IN (...) list when you hold the IDs already; it's built for exactly that and avoids an unnecessary SOQL statement.

Reading Large Data Sets

Standard queries are fine for thousands of records, but large extracts need a different approach so you stay inside Salesforce limits.

• Let the connector stream. Query returns results as a repeatable stream, so you process records in chunks rather than loading everything into memory at once.
• Use Bulk Query for very large pulls. For full extracts and data migrations, the Bulk Query job runs asynchronously and handles millions of records.
• Tune the fetch size and batch processing so each chunk moves through the flow without overwhelming downstream systems.

Bulk behavior and streaming defaults can change between connector releases, so pin your connector version (the Mule 4 line) and check the release notes before upgrading.

Authentication and Read Access

Reading data still needs a secure connection and the right permissions. The connector authenticates to Salesforce with OAuth 2.0 (JWT bearer for production) or Basic auth for testing, running as a dedicated integration user.

For reads specifically, that integration user needs read access to every object and field you query - object permissions plus field-level security. A query that silently returns fewer fields than expected is almost always a field-level security gap, not a SOQL problem.
‍

Common Errors When Reading Records

Read operations fail for a small set of predictable reasons. Here's how to clear them.
‍

For platform detail on SOQL limits and access, the Salesforce Developer blog and Salesforce Admins resources are the primary references, and Apex Hours and Salesforce Ben have MuleSoft query examples.
‍

Best Practices for a Salesforce MuleSoft Integration

A few habits keep your reads fast, complete, and inside Salesforce limits:

• Select only the fields you need. Never SELECT everything - narrow fields cut payload size and speed up the query.
• Filter on indexed fields. WHERE clauses on Id, external IDs, and dates let Salesforce run selective, fast queries.
• Stream, don't load. Process query results as a stream with For Each or Batch so large reads don't exhaust memory.
• Use Bulk Query for big extracts. Switch to the async Bulk Query well before you hit standard query limits.
• Grant least-privilege read access. Give the integration user read rights only on the objects and fields it queries.

These are the same standards we hold on every Salesforce integration with MuleSoft, and we keep flows healthy afterward through managed services.
‍

Frequently Asked Questions

1. How do you read Salesforce records with MuleSoft?

Use the connector's Query operation with a SOQL statement, or Retrieve when you already have the record IDs. Add the operation to your flow, select the fields you need, and process the returned records with DataWeave.

2. What is the difference between Query and Query All?

Query returns active records that match your SOQL. Query All returns the same records plus deleted and archived ones, which is useful for auditing or syncing deletions to another system.

3. How do you read large volumes of Salesforce records?

Let the connector stream standard Query results so you process them in chunks, and switch to the asynchronous Bulk Query for full extracts or millions of records. Filter selectively to stay inside SOQL and API limits.

4. Is this the same as the MuleSoft SFDC connector?

Yes - "SFDC" is shorthand for Salesforce, so the MuleSoft SFDC connector is the same Anypoint Connector. Its Query, Query All, and Retrieve operations read records the same way regardless of which name you see.

5. Why is my query returning fewer fields than expected?

Almost always field-level security. The integration user needs read access to every field in your SELECT; without it, Salesforce simply omits those fields rather than erroring. Grant the field access on the user's profile or permission set.

6. How does the connector authenticate for reads?

Through the Salesforce connection you configure - OAuth 2.0 (JWT bearer for production) or Basic authentication for testing - running as a dedicated integration user with read access to the objects you query.
‍

Read Salesforce Data Reliably With Minuscule Technologies

Retrieving and reading Salesforce records with the MuleSoft Salesforce Connector comes down to choosing the right operation - Query, Query All, or Retrieve - writing selective SOQL, streaming large results, and giving the integration user the read access it needs. Get those right and data flows out of Salesforce cleanly, fast, and within limits.

That's what we do at Minuscule Technologies. As a trusted Salesforce engineering partner with 160+ specialists and 75+ projects delivered since 2014, we design and build Salesforce integrations and MuleSoft-based data flows for enterprises - including Nasdaq-listed firms - that need reliable reads out of Salesforce into every system they run, backed by the DevOps discipline to keep them running.

Need Salesforce data flowing to the rest of your stack? Talk to Minuscule Technologies and let's build the flow.