Named Query API
Named Query API is a Salesforce feature that lets administrators define and govern reusable SOQL queries that external systems can invoke through the API by name and parameter values rather than by sending the full SOQL string.
Definition
Named Query API is a Salesforce feature that lets administrators define and govern reusable SOQL queries that external systems can invoke through the API by name and parameter values rather than by sending the full SOQL string. Each Named Query is a server-side stored query with declared parameters, controlled access, and predictable performance characteristics. The API consumer passes the query's name and parameter values, and Salesforce executes the predefined query.
The feature solves several problems with the traditional REST or SOAP query approach. Direct SOQL execution from external clients requires the client to know the data model in detail, including object and field API names. It also requires the org to trust each client with enough access to construct any query. Named Queries reverse the trust model: the admin defines what queries are allowed, the client only passes parameters, and the org governs which clients can call which queries. The result is safer, more performant, and more maintainable than the do-it-yourself SOQL approach.
Anatomy of a Named Query
Definition: query, parameters, return shape
A Named Query consists of a SOQL string with bind variable placeholders, a set of named parameters with declared types (Id, String, Date, Decimal), and a return shape describing which fields and child relationships the query returns. The SOQL string is authored once and stored in the org's metadata. Each call to the Named Query passes the parameter values, and Salesforce substitutes them into the query before execution. The bind-variable model prevents SOQL injection: the parameters cannot change the query's structure, only the filter values. This is significantly safer than building SOQL strings on the client side and passing them through.
Access control and trust boundaries
Each Named Query has its own access controls separate from the org's general API permissions. The admin specifies which Connected Apps, integration users, or external client IDs are allowed to invoke the query. Two clients calling the same API endpoint can have access to entirely different Named Queries. This per-query authorization model lets the org grant specific data access to specific partners without giving them broader query rights. For multi-tenant integration platforms (a single Connected App serving many partner systems), Named Query access can be further scoped by header values or client metadata passed at request time.
Performance and query optimization
Named Queries can be analyzed and optimized at definition time, before any client invokes them. Salesforce's query optimizer looks at the predefined SOQL and the expected parameter distribution, then identifies the right indexes and execution plan. The information from this analysis flows back to the admin as recommendations: add a custom index on this field, restructure this filter for better selectivity, watch out for this potential timeout. Client-constructed queries do not benefit from this design-time review because there is no query until the moment of invocation. For high-volume integrations, this performance predictability is a meaningful advantage.
Versioning and lifecycle
Named Queries are versioned metadata. Each save creates a new version, and consumers reference a specific version. This lets the admin make changes to a query (add a field, tighten a filter) without breaking existing consumers, because the consumers continue to use the version they were built against. Migrating consumers to a new version is an explicit step coordinated with the integration owner. The Setup page lists every version with creation timestamp, author, and a summary of changes from the prior version. The audit trail records every save and every version transition, which is useful when an integration begins behaving differently and the question is whether the query changed.
Limits and pagination
Like any SOQL query, Named Queries are subject to the platform's row limit (50,000 rows per query by default, configurable through the Bulk API). For larger result sets, Named Queries support cursor-based pagination: the first call returns a chunk plus a cursor token, and subsequent calls pass the token to retrieve the next chunk. This is the right pattern for integrations that need to export large datasets without holding open a connection or implementing manual offset paging. Heap size and query timeout limits apply normally; very expensive queries should be moved to Bulk API jobs rather than synchronous Named Query calls.
Field-level security and sharing
Named Queries respect the running user's field-level security and record-level sharing. A query that requests a field the integration user cannot read returns null for that field. A query that returns records the integration user cannot see through sharing rules simply skips those records. This is the right behavior because it means Named Queries cannot be used to bypass the platform's standard access controls. Admins should define the integration user's profile and permission sets carefully, because the data the user sees through a Named Query is exactly the data they could see through any other API call. Stricter Named Query access controls layer on top of this base, not in place of it.
When Named Queries are the right tool
Named Queries are the right answer for three patterns. First, partner integrations that need specific data access without trusting the partner with full SOQL rights. Second, high-volume, repeatable queries that benefit from design-time optimization rather than runtime planning. Third, mobile or low-trust clients (browser-based extensions, third-party tools) where embedded SOQL would expose query structure to inspection. They are the wrong answer for ad-hoc reporting (use Reports), for one-off data extracts (use Workbench or Data Loader), and for highly variable query shapes that the admin cannot predict in advance. The boundary between Named Query and direct API is roughly the boundary between governed integration and exploratory access.
Create and govern a Named Query
Building a Named Query is a four-step process: design the query and parameters, register the Named Query in Setup, grant access to the right clients, and validate from a test client. The walkthrough below covers a typical partner-integration scenario where an external system needs to fetch Accounts by a custom external ID.
- Design the query and its parameters
Decide what data the integration needs, what filters it should pass at runtime, and what return shape makes sense. For an Account-by-external-ID lookup, the parameter is the external ID value, the query is SELECT Id, Name, Industry, BillingCity FROM Account WHERE External_Id__c = :param, and the return shape is the four selected fields. Confirm the parameter type (String, Id, Date, Decimal). Document the design before writing it into Setup so the integration owner can sign off on the contract before you ship anything.
- Register the Named Query in Setup
From Setup, navigate to Named Query API and click New. Provide a name (AccountByExternalId), a description, the SOQL string with bind variable placeholders, and the parameter definitions (name, type, required flag). Save. Salesforce validates the SOQL syntax and the parameter mappings, surfacing any errors. Iterate until the query saves without errors. The Setup page shows the Named Query with a unique API name that consumers will reference.
- Grant access to specific clients
On the Named Query's detail page, configure the access list. Add the specific Connected Apps, integration users, or client IDs that should be allowed to invoke this query. For each one, set whether they can invoke any version or only specific versions. Save the access control. Test the query from an unauthorized client to confirm it returns a 403 error, then test from an authorized client to confirm it returns the expected data.
- Document the API contract and validate from a test client
Document the Named Query's API contract: the endpoint URL, the parameter names and types, the return shape, and any rate or volume considerations. Share this with the integration owner so their developer can build against the contract. Run a sample request from Postman or another test client and confirm the response matches the documented contract. Promote the Named Query to production after sandbox testing, granting production access only to the production client IDs.
The unique identifier the client uses to invoke the query. Cannot contain spaces; must be globally unique within the org.
The query definition with named parameter placeholders. Must be syntactically valid SOQL at save time.
Each bind variable in the SOQL must be declared with a name, type, and required flag.
Required to create and edit Named Queries in Setup.
Without a configured access list, the Named Query cannot be invoked by anyone.
- SOQL injection is prevented by the bind-variable model, but the SOQL string itself must still be reviewed for performance and correctness. Bad SOQL is bad SOQL whether it is stored or constructed.
- Field-level security still applies. A Named Query that requests a field the integration user cannot read returns null for that field, which can confuse the consumer's logic.
- Versioning is per Named Query. Adding a field is a new version, not an in-place edit. Plan for consumer migration when you make changes.
- Result sets above 50,000 rows must use pagination cursors. Trying to return larger sets in a single call hits the standard SOQL row limit.
- Access control is at the Named Query level, not the parameter level. A client granted access to AccountByExternalId can pass any external ID value, not just the IDs that belong to their company.
Trust & references
Cross-checked against the following references.
- REST API Developer GuideSalesforce Developer Docs
Straight from the source - Salesforce's reference material on Named Query API.
- Named Query APISalesforce Help
- SOQL ReferenceSalesforce Developer Docs
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What is a Governor Limit in the context of Named Query API?
Q2. Where would a developer typically work with Named Query API?
Q3. What skill set is typically needed to work with Named Query API?
Discussion
Loading discussion…