soql-using-scope-clause

name	soql-using-scope-clause
description	Use when writing or reviewing a SOQL query (in Apex, a selector, or via the API) that must return only a subset of records defined by ownership, team, territory, delegation, or an active scoping rule — through the optional USING SCOPE filterScope clause (mine, everything, team, delegated, my_territory, my_team_territory, mine_and_my_groups, scopingRule) placed after FROM and before WHERE. Also covers the mandatory USING SCOPE EVERYTHING requirement for the Scoping Rules SOQL operator. NOT a sharing/FLS enforcement mechanism (use WITH USER_MODE + with sharing + CRUD/FLS for that), NOT the Metadata API ListView filterScope enum (different casing and value set), and NOT for authoring scoping rules beyond their SOQL-operator criteria.
category	apex
salesforce-version	Spring '25+
well-architected-pillars	["Security","Performance"]
triggers	["limit a SOQL query to records owned by the running user without hardcoding an OwnerId filter","return only my records or my team's records from an Apex query","figure out where USING SCOPE goes in a SELECT statement — before or after WHERE","query only delegated tasks or records in the running user's territory","fix an error from USING SCOPE EVERYTHING inside a scoping rule's SOQL operator"]
tags	["soql","using-scope","filterscope","query-scope","scoping-rules"]
inputs	["The SOQL query or selector method to scope, and the sObject it targets","The desired audience filter: owned-by-me, my team, my territory, delegated, queues, or a scoping rule","The execution context (interactive user vs. async/scheduled/system) so 'the running user' is unambiguous"]
outputs	["A correctly positioned USING SCOPE clause (after FROM, before WHERE) using a valid filterScope value","A describe-backed confirmation that the target object supports the chosen scope","Guidance on pairing the scope with WITH USER_MODE / with sharing so the query is also secure"]
dependencies	[]
version	1.0.0
author	Pranav Nagrecha
updated	"2026-07-08T00:00:00.000Z"

SOQL USING SCOPE Clause

This skill activates when a query needs to return records for a specific audience — the running user, their team, their territory, their queues, or an active scoping rule — using the optional USING SCOPE filterScope clause instead of a hand-written OwnerId/relationship filter. It also covers the one place the clause is mandatory: the USING SCOPE EVERYTHING requirement of the Scoping Rules SOQL operator.

---

Before Starting

Gather this context before working on anything in this domain:

• Confirm the object supports the scope you want. Supported scopes vary per object. The docs are explicit: "To get a list of scopes supported by an object, call describeSObject() for SOAP API or sObject Describe for REST API." Do not assume team or my_territory exists on an arbitrary object.
• Know it is a filter, not a security boundary. USING SCOPE mine limits which rows come back by ownership; it does not enforce CRUD, FLS, or sharing. Pair it with WITH USER_MODE (Summer '23+) or a with sharing + SecurityUtils edge check.
• Pin down "the running user." mine, my_territory, and my_team_territory resolve against the user running the query. In a scheduled job, batch, @future, or trigger-driven automation that may be the Automated Process user or the enqueuing user — not the end user you pictured.
• Check prerequisites. Territory scopes require territory management enabled; scopingRule requires an admin to have activated at least one scoping rule on the object; mine_and_my_groups applies only to ProcessInstanceWorkItem.
• Know the API floor and maturity. The clause is "Available in API version 32.0 and later." The docs give no GA/Beta/Pilot label for the clause itself — treat it as a standard SOQL language feature and do not assert a maturity level. The related Scoping Rules SOQL-operator feature is edition-gated (see Core Concepts).

---

Core Concepts

What the clause does and where it goes

"The optional USING SCOPE clause of a SOQL query returns records within a specified scope." Its position in the SELECT grammar is fixed — immediately after FROM, before :