SAP HANA - Time Travel Example.

Worked Example Demonstrating History Tables and Time

Travel

Jack Boers (jack.boers@sap.com)

Document Version 1.0

SAP HANA – TIME TRAVEL EXAMPLE

TABLE OF CONTENT
1 INTRODUCTION .......................................................................................................................... 3
1.1 Create Tables .............................................................................................................................. 3
1.2 Check Table is a History Table .................................................................................................. 3
1.3 Turn Off Auto Commit ................................................................................................................ 3
1.4 Get the Current Commit ID ......................................................................................................... 4
1.5 Add Initial Table Data ................................................................................................................. 4
1.6 Execute a Join Query ................................................................................................................. 5
1.7 Update Some Records................................................................................................................ 5
1.8 Execute the Query Again............................................................................................................ 5
1.9 Add More Records ...................................................................................................................... 5
1.10 Execute the Query Again............................................................................................................ 6
1.11 Modify Some More Data ............................................................................................................. 6
1.12 Execute the Query Again to Verify Update ................................................................................ 6
1.13 Get the List of Commit IDs ......................................................................................................... 6
2 VERIFYING HISTORY.................................................................................................................. 7
2.1 Execute a Modified Query to View History ................................................................................ 7
3 TIME TRAVELLING ..................................................................................................................... 8
3.1 Execute a Join Query With COMMIT ID ..................................................................................... 8
3.2 SET HISTORY SESSION TO COMMIT ID .................................................................................... 9
3.3 SET HISTORY SESSION TO UTCTIMESTAMP ........................................................................... 9
4 BEHAVIOUR WHEN DELETING RECORDS ..............................................................................10
4.1 Delete a Record .........................................................................................................................10
4.2 Execute the Query Again...........................................................................................................10
4.3 Execute a Modified Query to View History ...............................................................................10
4.4 Execute the Query With AS OF COMMIT ID..............................................................................10
5 HISTORY TABLE MEMORY USAGE ..........................................................................................11
6 PERMANENTLY REMOVING RECORDS FROM A HISTORY TABLE .......................................12
6.1 Query the Contents of the History Table ..................................................................................12
6.2 Verify Current TRANSACTION_HISTORY COMMIT_IDs...........................................................12
6.3 Remove All History Prior to '2011-11-09 05:00:00’ ...................................................................12
6.4 Clean-out History.......................................................................................................................13
6.5 Redisplay the History Table Contents ......................................................................................13

2
SAP HANA – TIME TRAVEL EXAMPLE

1 INTRODUCTION
The SAP In-Memory Computing Engine (NewDB) provides support for History Tables. In such a History
Table, updates to and deletion of a record, results in a new version of the existing record, with the original
record being invalidated.

This document demonstrates how to create, update and query History Tables using two sample tables, some
simple sample data, and sample code showing the results of each step.

1.1 Create Tables

CREATE HISTORY COLUMN TABLE "SYSTEM"."MODEL"(

"KEY1" VARCHAR (2) NOT NULL DEFAULT '',
"VALUE" INTEGER,
PRIMARY KEY ("KEY1"));

CREATE COLUMN TABLE "SYSTEM"."COLOUR"(

"VALUE" INTEGER NOT NULL DEFAULT 0,
"HUE" VARCHAR (10),
PRIMARY KEY ("VALUE"));

ALTER TABLE "SYSTEM"."COLOUR" CREATE HISTORY;

A History Table can be created as a History Table, as shown for the MODEL table in the code example, or if
it is subsequently determined that a standard table requires history, then the table can be modified as shown
for the COLOUR table.

1.2 Check Table is a History Table

SELECT SESSION_TYPE FROM SYS.TABLES

WHERE SCHEMA_NAME = 'SYSTEM' AND TABLE_NAME = 'COLOUR';

The SESSION_TYPE shows that table COLOUR is a HISTORY table.

1.3 Turn Off Auto Commit

Using the SAP HANA Studio, select the Properties tab for the SQL Editor and turn the Auto Commit from On
to Off. This is required in order for time travel to work correctly, and limits the number of Commit IDs that
need to be worked with.

After changing the setting it is important to click elsewhere within the tab in order for the property change to
be applied.

Because Auto Commit has now been turned off, you will need to issue the COMMIT command after making
changes to the data in the tables.

(If you do not change this setting, then an error message to this effect will be displayed when time travel
commands are executed)

3
SAP HANA – TIME TRAVEL EXAMPLE

1.4 Get the Current Commit ID

SELECT LAST_COMMIT_ID FROM M_TRANSACTIONS

WHERE CONNECTION_ID = CURRENT_CONNECTION;

This Commit ID is the starting ID before any data is entered into the tables. Obtaining this first may make
keeping track of the relevant timestamps and commit IDs easier.

1.5 Add Initial Table Data

INSERT INTO "SYSTEM"."MODEL" VALUES ('AA', 1);

INSERT INTO "SYSTEM"."MODEL" VALUES ('BB', 2);
INSERT INTO "SYSTEM"."MODEL" VALUES ('CC', 2);
COMMIT;
UPDATE "SYSTEM"."MODEL" MERGE DELTA INDEX;

SELECT LAST_COMMIT_ID FROM M_TRANSACTIONS

WHERE CONNECTION_ID = CURRENT_CONNECTION;

Since Auto Commit has been turned off, the COMMIT command is necessary to ensure that the data is
inserted into the table.

The MERGE DELTA INDEX is required in order to merge the newly added records into the main table, from
the delta table. Data in delta tables is not compressed, so take up more room than is otherwise necessary.

INSERT INTO "SYSTEM"."COLOUR" VALUES (1, 'GREEN');

INSERT INTO "SYSTEM"."COLOUR" VALUES (2, 'BLUE');
INSERT INTO "SYSTEM"."COLOUR" VALUES (3, 'RED');
COMMIT;
UPDATE "SYSTEM"."COLOUR" MERGE DELTA INDEX;

SELECT LAST_COMMIT_ID FROM M_TRANSACTIONS

4
SAP HANA – TIME TRAVEL EXAMPLE

WHERE CONNECTION_ID = CURRENT_CONNECTION;

1.6 Execute a Join Query

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

This query provides a simple view of the data currently in the tables. This query will be used throughout this
example to demonstrate the current as well as historic view of the table data.

1.7 Update Some Records

UPDATE "SYSTEM"."MODEL" SET "VALUE" = 4 WHERE "KEY1" = 'AA';

UPDATE "SYSTEM"."MODEL" SET "VALUE" = 5 WHERE "KEY1" = 'CC';
COMMIT;
UPDATE "SYSTEM"."MODEL" MERGE DELTA INDEX;

SELECT LAST_COMMIT_ID FROM M_TRANSACTIONS

WHERE CONNECTION_ID = CURRENT_CONNECTION;

By keeping track of the Commit ID it will make it easier to check that the History and Time Travel is working
correctly and verifiably.

1.8 Execute the Query Again

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

The record update replaced some of the VALUE fields in the table, resulting in a reduced record set for the
join.

1.9 Add More Records

INSERT INTO "SYSTEM"."COLOUR" VALUES (4, 'YELLOW');

INSERT INTO "SYSTEM"."COLOUR" VALUES (5, 'BLACK');
COMMIT;
UPDATE "SYSTEM"."COLOUR" MERGE DELTA INDEX;

5
SAP HANA – TIME TRAVEL EXAMPLE

SELECT LAST_COMMIT_ID FROM M_TRANSACTIONS

WHERE CONNECTION_ID = CURRENT_CONNECTION;

The new records should have corresponding entries in the other table which should now appear in the query.

1.10 Execute the Query Again

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

As can be seen, there are now more records returned in the dataset.

1.11 Modify Some More Data

UPDATE "SYSTEM"."COLOUR" SET "HUE" = 'RED' WHERE "VALUE" = 2;

UPDATE "SYSTEM"."COLOUR" SET "HUE" = 'WHITE' WHERE "VALUE" = 5;
COMMIT;
UPDATE "SYSTEM"."COLOUR" MERGE DELTA INDEX;

SELECT LAST_COMMIT_ID FROM M_TRANSACTIONS

WHERE CONNECTION_ID = CURRENT_CONNECTION;

1.12 Execute the Query Again to Verify Update

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

The dataset now contains the updated records.

1.13 Get the List of Commit IDs

SELECT * FROM TRANSACTION_HISTORY WHERE COMMIT_ID >= 4646 ORDER BY COMMIT_ID;

6
SAP HANA – TIME TRAVEL EXAMPLE

Restricting the query by using the Commit ID means that a smaller dataset is returned. Otherwise it would
be necessary to scan the COMMIT_TIME column to locate the relevant time.

2 VERIFYING HISTORY

2.1 Execute a Modified Query to View History

SELECT *, "$validfrom$", "$validto$"

FROM "SYSTEM"."MODEL"('REQUEST_FLAGS'='ALLROWS');

SELECT *, "$validfrom$", "$validto$"

FROM "SYSTEM"."COLOUR"('REQUEST_FLAGS'='ALLROWS');

The hidden columns “$validfrom$” and “$validto$” (case sensitive) contain the Commit ID when the record
was added – “$validfrom$” – and superceded or deleted - “$validto$”.

Records without an entry in either column have not yet been committed. Records that only have an entry in
the “$validfrom$” column are current records and will appear in normal queries (as above) and are stored in
the “Main” or “Main Delta” tables, while records that have entries in both columns will be excluded from

7
SAP HANA – TIME TRAVEL EXAMPLE

normal queries and have been moved to the “History” or “History Delta” tables. (Records in the “Delta”
tables have not yet been merged into the main tables, and are therefore not compressed.)

3 TIME TRAVELLING

There are a number of ways of “Time Travelling” which will be shown. As the data displayed using the
various methods will be identical, the first method will look at all possible “Time Travel” scenarios and the
datasets returned each time, whereas subsequent methods will only look at one or two particular examples.

3.1 Execute a Join Query With COMMIT ID

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE"
AS OF COMMIT ID 4646;

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE"
AS OF COMMIT ID 4661;

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE"
AS OF COMMIT ID 4667;

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE"
AS OF COMMIT ID 4669;

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE"
AS OF COMMIT ID 4671;

8
SAP HANA – TIME TRAVEL EXAMPLE

Executing the query using each of the LAST_COMMIT_IDs obtained after records were added or updated
shows the same datasets that were observed when the queries were executed immediately after the original
changes were made. Using the Commit ID requires knowing what it is. Unless the value of the Commit ID is
stored after the data has been committed, then the TRANSACTION_HISTORY table would need to be
queried to locate the appropriate Commit ID value.

Running a query “AS AT COMMIT ID” will return any matching data that was relevant at the time the
COMMIT associated with the Commit ID was executed. For HISTORY tables, that will be data that was
current at the time of the COMMIT. For non-HISTORY tables, it will return data current as of the time of
running the query. (As this may not be the value of the data that was current at the time of the specified
COMMIT ID, care must be taken when using “Time Travel” with both HISTORY and non-HISTORY” tables in
the same query.)

3.2 SET HISTORY SESSION TO COMMIT ID

SET HISTORY SESSION TO COMMIT ID 4646;

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M
JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

SET HISTORY SESSION TO COMMIT ID 4661;

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M
JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

SET HISTORY SESSION TO NOW;

By setting the HISTORY SESSION to a particular Commit ID, all subsequent queries will return data current
as of that Commit ID, until the command is cancelled by setting the history session to another value, or
cancelling it by setting it to NOW.

3.3 SET HISTORY SESSION TO UTCTIMESTAMP

SET HISTORY SESSION TO UTCTIMESTAMP '2011-11-09 04:21:47';

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M
JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

9
SAP HANA – TIME TRAVEL EXAMPLE

SET HISTORY SESSION TO NOW;

When using a timestamp to set the history point-in-time, the time need not be exact, but should fall after the
timestamp for the Commit ID of interest, but before the timestamp following it.

4 BEHAVIOUR WHEN DELETING RECORDS

4.1 Delete a Record

DELETE FROM "SYSTEM"."COLOUR" WHERE "VALUE" = 5;

COMMIT;
UPDATE "SYSTEM"."COLOUR" MERGE DELTA INDEX;

4.2 Execute the Query Again

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE";

As expected the record no longer appears.

4.3 Execute a Modified Query to View History

SELECT *, "$validfrom$", "$validto$"

FROM "SYSTEM"."COLOUR"('REQUEST_FLAGS'='ALLROWS');

The recently deleted record, number 7, shows with a Commit ID in both the “$validfrom$” and “$validto$”
columns, indicating that the record is no longer in the Main table, but has been moved to the History table,
where it is only accessed during “Time Travel” type queries.

4.4 Execute the Query With AS OF COMMIT ID

10
SAP HANA – TIME TRAVEL EXAMPLE

SELECT M."KEY1", C."HUE" FROM "SYSTEM"."MODEL" M

JOIN "SYSTEM"."COLOUR" C ON M."VALUE" = C."VALUE"
AS OF COMMIT ID 4671;

Running the query using a Commit ID for when the record was still valid, returns the record in the dataset, as
expected.

5 HISTORY TABLE MEMORY USAGE

SELECT MEMORY_SIZE_IN_TOTAL,
MEMORY_SIZE_IN_MAIN,
MEMORY_SIZE_IN_DELTA,
MEMORY_SIZE_IN_HISTORY_MAIN,
MEMORY_SIZE_IN_HISTORY_DELTA,
RAW_RECORD_COUNT_IN_MAIN,
RAW_RECORD_COUNT_IN_DELTA,
RAW_RECORD_COUNT_IN_HISTORY_MAIN,
RAW_RECORD_COUNT_IN_HISTORY_DELTA
FROM SYS.M_CS_TABLES
WHERE SCHEMA_NAME = 'SYSTEM' AND TABLE_NAME = 'COLOUR';

11
SAP HANA – TIME TRAVEL EXAMPLE

Referring to the figure in 4.3, there are 4 records that don’t have an entry in the “$validto$” column, which
indicates that they are current records, and there are 3 records that have an entry in the “$validto$” column,
which indicates that they are no longer current records and are part of the history for this table.

Running the query to determine the memory use for the table confirms that there are 4 records in Main and 3
records in History. The memory used by each of the 4 parts of the table are also shown.

6 PERMANENTLY REMOVING RECORDS FROM A HISTORY TABLE

6.1 Query the Contents of the History Table

SELECT *, "$validfrom$", "$validto$"

FROM "SYSTEM"."COLOUR"('REQUEST_FLAGS'='ALLROWS');

6.2 Verify Current TRANSACTION_HISTORY COMMIT_IDs

SELECT * FROM TRANSACTION_HISTORY WHERE COMMIT_ID >= 4646 ORDER BY COMMIT_ID;

6.3 Remove All History Prior to '2011-11-09 05:00:00’

DELETE HISTORY FROM "SYSTEM"."COLOUR"

WHERE "$validto$" <= (SELECT MAX(COMMIT_ID) FROM TRANSACTION_HISTORY
WHERE COMMIT_TIME <= '2011-11-09 05:00:00');

12
SAP HANA – TIME TRAVEL EXAMPLE

COMMIT;

6.4 Clean-out History

MERGE HISTORY DELTA OF "SYSTEM"."COLOUR";

ALTER SYSTEM reclaim version space;

6.5 Redisplay the History Table Contents

SELECT *, "$validfrom$", "$validto$"

FROM "SYSTEM"."COLOUR"('REQUEST_FLAGS'='ALLROWS');

13
www.sap.com

©2011 SAP AG. All rights reserved.

SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign,
SAP BusinessObjects Explorer, StreamWork, SAP HANA, and other
SAP products and services mentioned herein as well as their
respective logos are trademarks or registered trademarks of SAP AG
in Germany and other countries.

Business Objects and the Business Objects logo, BusinessObjects,

Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and
other Business Objects products and services mentioned herein as
well as their respective logos are trademarks or registered trademarks
of Business Objects Software Ltd. Business Objects is an SAP
company.

Sybase and Adaptive Server, iAnywhere, Sybase 365, SQL

Anywhere, and other Sybase products and services mentioned herein
as well as their respective logos are trademarks or registered
trademarks of Sybase, Inc. Sybase is an SAP company.

All other product and service names mentioned are the trademarks of
their respective companies. Data contained in this document serves
informational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials

are provided by SAP AG and its affiliated companies ("SAP Group")
for informational purposes only, without representation or warranty of
any kind, and SAP Group shall not be liable for errors or omissions
with respect to the materials. The only warranties for SAP Group
products and services are those that are set forth in the express
warranty statements accompanying such products and services, if
any. Nothing herein should be construed as constituting an additional
warranty.