{"ref":"capability:temporal-data","page":"/capabilities/temporal-data","json":"/capabilities/temporal-data.json","generated":"2026-10-26","drafted_with_ai":true,"entity":{"id":"temporal-data","name":"Temporal data","domain":"data-and-persistence","ecosystems":["cap"],"universal":true,"description":"Keeping every version of a record that was valid for a period, and reading the one that held at a given moment — the assignment somebody had on the first of March, not the one they have now — without the application filtering time slices by hand.","short":"Keeping every version of a record valid for a period","core_coverage":{"state":"core-only","assessed_at":"2026-09-27","what_core_does":"Built in: two elements annotated `@cds.valid.from` and `@cds.valid.to`, or the `temporal` aspect from `@sap/cds/common`, turn an entity into time slices keyed by its conceptual key plus `validFrom`, while the served API keeps the timeless key. A read with no temporal parameter returns what is valid as of now; `sap-valid-at` reads a snapshot at a moment and `sap-valid-from` the history since one, expanded along associations. Nothing is installed for that.","where_it_stops":"At the read. Writing a time slice is a custom handler of the application's own, SQLite serves no time-travel or time-period query because it has no session variables, and a time-period query that expands across two temporal entities needs care the guide spells out. The guide names neither runtime, so which flavor serves it is what the artifacts state and no more. Nothing outside the core is mapped here yet.","sources":[{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"CAP provides out-of-the-box support for declaring and serving date-effective entities with application-controlled validity, in particular to serve as-of-now and time-travel queries."},{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"The annotation pair @cds.valid.from/to actually triggers the built-in mechanisms for serving temporal data. It specifies which elements form the application-time period, similar to SQL:2011."},{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"READ requests without specifying any temporal query parameter will automatically return data valid as of now."},{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"We can run the same OData query as in the previous sample to read a snapshot data as valid on January 1, 2017 using the sap-valid-at query parameter"},{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"Time-travel queries aren't supported on SQLite due to the lack of session_context variables."},{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"Writing temporal data must be done in custom handlers."},{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"Special care has to be taken though if time-period queries transitively expand across two or more temporal data entities."},{"url":"https://cap.cloud.sap/docs/guides/domain/temporal-data","title":"Temporal Data — capire","checked":"2026-09-27","quote":"While timeless entities are uniquely identified by the declared primary key — we call that the conceptual key in CDS — time slices are uniquely identified by the conceptual key + validFrom."}]},"history":[{"date":"2026-09-27","field":"id","from":"none","to":"temporal-data","reason":"Proposed by the capire audit of 2026-09-27: capire documents date-effective entities as a concern of their own, no capability named it, and nothing in the graph touched it, so the audit script could never admit it. Created by the maintainer's decision from that audit, with the core's answer read from the page."}],"drafted_with_ai":true},"sap_delivery":{"door":"cap","all":{"built_in":[{"ref":"artifact:sap-cds","name":"@sap/cds","json":"/artifacts/sap-cds.json"}],"documented_pattern":[],"announced":[],"packages":[]},"by_flavor":{"node":{"built_in":[{"ref":"artifact:sap-cds","name":"@sap/cds","json":"/artifacts/sap-cds.json"}],"documented_pattern":[],"announced":[],"packages":[]},"java":null}},"edges":{"use_cases":[],"shared_tasks":[],"related_tasks":[],"options":[{"ref":"artifact:sap-cds","name":"@sap/cds","json":"/artifacts/sap-cds.json","ecosystem":"cap","origin_ring":"sap-official"}],"samples":[],"explained_by":[{"ref":"content:my-cap-projects-toolbox","name":"My CAP Projects Toolbox","json":"/content/my-cap-projects-toolbox.json"}],"normative_context":[]}}