KysoqlSupport boundaries and limits
See what Kysoql validates and what remains a Salesforce runtime concern.
Kysoql models SOQL SELECT queries. It is Kysely-inspired, not a drop-in Kysely
implementation, and it does not try to represent every Salesforce API feature.
Outside the builder
Kysoql does not provide DML/CRUD, SOSL, SQL joins, SELECT *, live runtime schema
loading, automatic schema refresh, Bulk API exports, or Apex execution.
Use soql.raw() only for trusted SOQL syntax that the typed builder does not yet
model. Raw fragments deliberately opt out of normal structural safeguards.
Common validated limits
| Feature | Kysoql boundary |
|---|---|
LIMIT | Non-negative safe integer, with extra rules where Salesforce requires them |
Root OFFSET | 0..2000 |
Child OFFSET | Pilot API only and immediate parent must have literal LIMIT 1 |
| Parent paths | Up to five child-to-parent levels in typed references |
| Nested child subqueries | Up to four levels below the root builder |
| Query relationships | Up to 20 parent-to-child and 55 child-to-parent relationships |
| Semi and anti-joins | At most two at the root WHERE level |
| ROLLUP and CUBE | Up to three grouping fields |
| Data categories | Up to three conditions with distinct category groups |
FOR UPDATE | Apex record queries only, without ORDER BY or ALL ROWS |
TYPEOF | Cannot be mixed with aggregate/grouping or conflicting selections |
Filtered codegen objects cannot use selectFields(...). Explicit selections are
still available. See field filtering.
Object-specific rules
Some Salesforce objects have stricter query shapes. Kysoql catches the cases it can identify from the query and generated metadata.
KnowledgeArticleVersion and concrete __kav article versions require a root
filter on PublishStatus or Id. UserProfileFeed requires withUserId().
Feed relationship-path ordering is restricted. See Knowledge and feeds.
Queries require a user filter plus a record filter. Record ID lists are limited to 200 IDs, and selected access fields have matching ordering rules.
__mdt filtering supports a narrower set of operators and boolean shapes.
Metadata relationship fields can be selected and filtered where Salesforce
supports them, but are not available for relationship-path ordering.
__x objects reject several aggregate, grouping, function, tracking, and
filtering features that are available on normal CRM objects. Bare COUNT()
remains available. Salesforce Connect can impose additional runtime rules.
Generated DLO and DMO capabilities control SET OPTIONS and related query
restrictions. See Data 360 and query options.
Salesforce still has the final say
Generated types are a snapshot. They cannot guarantee current sharing, CRUD/FLS, package licensing, feature enrollment, selectivity, governor limits, or the behaviour of every API version.
The bundled executors validate Salesforce response envelopes and paging metadata,
but they do not runtime-validate every selected field value against your generated
TypeScript schema. A CompiledQuery is also not a server-validated query plan.
Native REST can iterate root pages and records with explicit budgets and
cancellation. execute() collects root pages into memory. The JSforce adapter
handles root pagination but does not recursively drain child query locators in
the same way as the native REST adapter. See REST execution
and JSforce.
Experimental and versioned features
Some features depend on Salesforce API version, org type, or feature enrollment. The compiler does not negotiate these for you. Check the target org when using beta or pilot features, external objects, Data 360, or Apex-specific syntax.
See beta and pilot features for the opt-in APIs and the Salesforce reference map for the upstream documentation.