SAP OData V2 and V4 Query Options Cheat Sheet
OData is the default way to read and write S/4HANA data from outside SAP, but V2 and V4 differ in small ways that break requests. This cheat sheet lists the query options and operators with the version differences marked.
| Option or operator | V2 | V4 | Example | Notes |
|---|---|---|---|---|
$filter | Yes | Yes | $filter=Plant eq '1010' | Restricts the entities returned |
$select | Yes | Yes | $select=Material,Plant | Reduces payload, always use it on wide entities |
$expand | Yes | Yes | $expand=to_Item | V4 supports nested options such as $expand=to_Item($select=Material) |
$orderby | Yes | Yes | $orderby=CreationDate desc | Use asc or desc |
$top | Yes | Yes | $top=100 | Page size |
$skip | Yes | Yes | $skip=100 | Use with $top for client paging |
$inlinecount | Yes | No | $inlinecount=allpages | V2 way to return the total count with the page |
$count (option) | No | Yes | $count=true | V4 way to return the total count with the page |
$count (path segment) | Yes | Yes | /A_SalesOrder/$count | Returns a plain number |
$format | Yes | Yes | $format=json | Often replaced by the Accept header |
$search | No | Yes | $search=pump | Free text search, depends on service support |
$metadata | Yes | Yes | /$metadata | Service metadata document, appended to the service root |
$batch | Yes | Yes | POST /$batch | Groups several requests; V2 uses multipart, V4 can use JSON |
$skiptoken | Yes | Yes | $skiptoken=... | Server driven paging; use the next link the server returns |
$apply | No | Yes | $apply=groupby((Plant)) | Aggregation, only where the service supports it |
eq | Yes | Yes | Plant eq '1010' | Equal |
ne | Yes | Yes | Status ne 'C' | Not equal |
gt / ge | Yes | Yes | Quantity gt 10 | Greater than, greater or equal |
lt / le | Yes | Yes | Quantity le 500 | Less than, less or equal |
and / or / not | Yes | Yes | Plant eq '1010' and Status eq 'A' | Use parentheses to group |
in | No | Yes | Plant in ('1010','1020') | V4 only; in V2 chain eq with or |
substringof | Yes | No | substringof('PUMP',Description) | V2 contains test, note the argument order |
contains | No | Yes | contains(Description,'PUMP') | V4 replacement for substringof |
startswith | Yes | Yes | startswith(Material,'FG') | Prefix match |
endswith | Yes | Yes | endswith(Material,'01') | Suffix match |
tolower / toupper | Yes | Yes | tolower(Name) eq 'acme' | Case folding, many SAP services are case sensitive |
datetime literal | datetime'2026-01-31T00:00:00' | 2026-01-31T00:00:00Z | CreationDate ge datetime'2026-01-01T00:00:00' | Date literal syntax differs between versions |
guid literal | guid'...' | plain value | ID eq guid'00000000-0000-0000-0000-000000000000' | V4 drops the guid prefix |
string literal | 'text' | 'text' | Name eq 'O''Brien' | Escape a single quote by doubling it |
Behavior depends on the service implementation. SAP Gateway services built with SEGW support only part of the full OData standard, so confirm each option in the service metadata and by testing in the Gateway Client (transaction /IWFND/GW_CLIENT).
Want queries drafted against your own ERP?
Optional: see how a private, read-only assistant could draft and explain OData queries for your integration team.
Optional. The tool and every export work without this. No spam.
How to use this cheat sheet
Search for an option or operator and read the V2 and V4 columns. Copy the example into your URL and replace field names with the ones from the service's $metadata. Export the table if you want a local version for your team's wiki.
V2 versus V4 in SAP landscapes
Most released S/4HANA APIs on the SAP Business Accelerator Hub are still OData V2, while newer RAP based services and many cloud APIs use V4. A project often needs both. The usual breakers are $inlinecount versus $count, substringof versus contains, and different date literal formats. Always read the metadata first so you know the version and which operations the entity set allows.
Paging and performance
Use $select and $filter on every call. For big reads, prefer server driven paging with the next link over large $skip values, because deep skips get slower. Avoid $expand across several to-many associations in one call since the response can multiply in size. Group writes using $batch with a change set so related changes succeed or fail together.
- Set a sensible $top, many services cap results anyway
- Never rely on default ordering, add $orderby when paging
- Fetch an X-CSRF-Token with a GET before any POST, PATCH or DELETE
Common mistakes
Forgetting to URL encode spaces and quotes, using double quotes around strings, and comparing a key with the wrong leading zeros are the usual causes of HTTP 400 responses. Material numbers and customer numbers often need their internal format with leading zeros.
Frequently Asked Questions
Why does my $count=true return nothing in OData V2?
The $count query option belongs to V4. In V2 you use $inlinecount=allpages to get the total with the page, or call the entity set path with /$count to get a plain number. Check which version your service endpoint uses before choosing.
How do I filter on a date in an SAP OData V2 service?
Use the datetime literal, for example CreationDate ge datetime'2026-01-01T00:00:00'. Some services expose dates as Edm.DateTime and others as strings, so look at the property type in the metadata. V4 services use ISO format without the datetime prefix.
Can I use contains in V2?
Not in standard V2. Use substringof('text',Property) instead, with the search text first. Some Gateway services do not implement it at all, in which case use startswith or filter on the server side with a custom function import.
What is the X-CSRF-Token for?
SAP Gateway protects changing requests against cross-site request forgery. Send a GET with the header X-CSRF-Token set to Fetch, read the token from the response header, and include it in the following POST, PUT, PATCH or DELETE using the same session cookies.
If your integration team writes many one-off OData calls, Netray can set up a private assistant that drafts and explains queries against your own ERP, with human review before anything is written back.
Related Tools
SAP BAPI_GOODSMVT_CREATE ABAP Code Generator
Fill in plant, material, quantity and movement type to get a working ABAP skeleton for posting a goods movement through the standard BAPI.
SAPSAP Integration Readiness Assessment
Answer ten questions about interfaces, monitoring, API use, security and ownership to see how ready your SAP integration landscape is for change.
SAPSAP IDoc and ALE Transactions, Tables and Programs Reference
One searchable list of the transactions, tables and standard programs an SAP integration developer uses to build, monitor and repair IDoc and ALE interfaces.
SAPSAP IDoc Interface Go-Live Checklist
A practical checklist covering configuration, testing, monitoring and cutover steps before an IDoc interface goes into production.