Salesforce has made huge progress by introducing GraphQL as part of its modern API layer. If you're used to SOQL or REST API queries, GraphQL may feel like a breath of fresh air—especially when it comes to writing flexible and powerful filters.

One of the most common things developers need is applying OR logic to multiple fields or conditions. In SOQL, this is simple. But in GraphQL, the structure is different and often confusing at first.

This guide walks you through exactly how to use OR in Salesforce GraphQL with examples, best practices, and common mistakes to avoid.

The Salesforce GraphQL API is a modern query language designed to fetch exactly the data you need in a single request. It is flexible, developer-friendly, and efficient compared to traditional APIs.

For deeper context, refer to the Salesforce GraphQL API documentation:

Salesforce introduced GraphQL to address issues such as:

• Multiple REST calls

• Complicated joins

• Heavy payloads

• Difficult data shaping

GraphQL offers several advantages:

• Fetch nested data in a single call

• Retrieve only the fields you want

• Combine logic filters easily

• Better performance with large datasets

GraphQL uses object-based filtering instead of SQL-like operators.

filter: { name: { eq: "John Doe" } }

• AND is applied automatically when multiple conditions are placed in the same filter block.

• OR must be defined explicitly using an array.

Learn more from the GraphQL official site:
https://graphql.org/learn/

filter: { or: [ { Name: { eq: "John" } }, { Name: { eq: "Jane" } } ] }

filter: { and: [ { Status: { eq: "Active" } }, { or: [ { Country: { eq: "USA" } }, { Country: { eq: "Canada" } } ] } ] }

• Filtering contacts by multiple countries

• Returning accounts from different industries

• Getting leads with several matching statuses

query { uiapi { query { Contact( filter: { or: [ { FirstName: { eq: "John" } }, { FirstName: { eq: "David" } } ] } ) { edges { node { Id Name } } } } } }

filter: { or: [ { Email: { like: "%gmail.com" } }, { Phone: { eq: "1234567890" } } ] }

filter: { and: [ { IsActive: { eq: true } }, { or: [ { Industry: { eq: "Tech" } }, { Industry: { eq: "Finance" } } ] } ] }

filter: { or: [ { Account: { Name: { eq: "Salesforce" } } }, { Account: { Industry: { eq: "Software" } } } ] }

Explore more Salesforce development articles at:
https://appnigma.ai/blogs/

Large OR arrays may lead to:

• Query too large errors

• API timeouts

Salesforce limits how deeply filters can be nested.

Some fields do not support every filter operator.

Reference Salesforce entity documentation:
https://developer.salesforce.com/docs/

Use arrays for clarity and maintainability.

Avoid unnecessary AND/OR nesting.

Fetch only the fields required.

Learn how Appnigma accelerates native Salesforce development:
https://appnigma.ai/

Incorrect:

or: { Name: { eq: "John" } }

Correct:

or: [ { Name: { eq: "John" } } ]

Break complex logic into separate queries when required.

Some formula fields may behave differently.

Using OR in Salesforce GraphQL becomes simple once you understand the structure. GraphQL uses nested objects and arrays for logical expressions rather than SQL-like syntax. Once you adapt to this approach, building flexible, modern Salesforce queries becomes much easier.

GraphQL is becoming the preferred Salesforce API layer, and mastering OR filters is essential for scalable development.

Further reading:
https://appnigma.ai/

Yes, OR can be applied across any supported fields.

Yes, using nested arrays.

Not always, but very large OR arrays may reduce performance.

No. SOQL still powers Salesforce internally, but GraphQL is the modern API layer.

Use the Salesforce GraphQL Playground or API Explorer.