PUBLIC SAP HANA Platform 2.0 SPS 04 Document Version: 1.1 – 2019-10-31 SAP HANA JSON Document Store Guide company. All rights reserved. All rights company. affiliate THE BEST RUN 2019 SAP SE or an SAP SE or an SAP SAP 2019 © Content 1 SAP HANA JSON Document Store Guide..........................................4 2 Introduction to SAP HANA JSON Document Store...................................5 3 Getting Started with the JSON Document Store.....................................7 4 Collections.................................................................8 5 JSON Document Store Statements.............................................. 9 5.1 Enable/Disable the JSON Document Store...........................................9 Enable the SAP HANA JSON Document Store...................................... 9 Disable the SAP HANA JSON Document Store.....................................10 5.2 Data Definition Statements.....................................................10 CREATE COLLECTION Statement..............................................10 DROP COLLECTION Statement................................................11 TRUNCATE COLLECTION Statement............................................12 RENAME COLLECTION Statement..............................................13 ALTER COLLECTION Statement (Checkpoints).....................................14 5.3 SELECT Statement...........................................................16 5.4 Data Manipulation Statements...................................................21 INSERT Statement.........................................................21 UPDATE Statement........................................................23 DELETE Statement........................................................28 5.5 Data Types.................................................................30 5.6 Load/Unload a Collection......................................................32 LOAD Statement..........................................................32 UNLOAD Statement........................................................33 5.7 Native Aggregation...........................................................34 6 Import and Export.......................................................... 35 7 Data Type Handling and Schema-Flexibility.......................................36 7.1 Data Types within the Document Store.............................................36 7.2 Crossing Engine Boundaries.................................................... 37 8 Changes from SPS 03 to SPS 04...............................................38 9 Escape Sequences and Unicode in the SAP HANA Document Store.....................39 9.1 Background................................................................39 9.2 Special Case "Forward Slash"....................................................41 SAP HANA JSON Document Store Guide 2 PUBLIC Content 9.3 Special Case "Unicode"........................................................42 9.4 Identifiers................................................................. 43 9.5 Corrections................................................................43 SAP HANA JSON Document Store Guide Content PUBLIC 3 1 SAP HANA JSON Document Store Guide This guide explains the SAP HANA JSON Document Store. The information in the guide is organized as follows: ● SAP HANA JSON Document Store Guide ● Introduction to SAP HANA JSON Document Store ● Getting Started with JSON Document Store ● Collections ● SQL Statements ● Import and Export ● Data Type Handling and Schema-Flexibility ● Changes from SPS 03 to SPS 04 ● Escape Sequences and Unicode in the SAP HANA Document Store SAP HANA JSON Document Store Guide 4 PUBLIC SAP HANA JSON Document Store Guide 2 Introduction to SAP HANA JSON Document Store The SAP HANA Database provides a Document Store for JSON documents. This is an independent store, in addition to the Column and Row Stores that are well-known in SAP HANA. The Document Store is available for the SAP HANA Express Edition. Definition of SAP HANA JSON Document Store Usually data is being stored in tables, with columns and rows, where for each column a strict definition or schema defines layout and data types. Moreover, tables are "flat" in the sense that they are not deeply nested or hierarchical. To represent a piece of information in the normalized representation, joins among multiple flat tables may be required. Note The features "Flexible table" and "Multi-value attributes" break up these hard constraints. The SAP HANA JSON Document Store follows the rules of JSON documents: ● Data may be deeply nested. ● There is no a priori definition of which fields exist or which data type they are associated with (schema- less). ● The stored data describes its own structure, which is being referred to as "semi-structured". ● Whereas in the Column and Row Store, data is stored in tables, JSON data is stored in so-called "collections". Benefits of SAP HANA JSON Document Store The SAP HANA Document Store is an ordinary SAP HANA service. This means that the JSON data is part of SAP HANA's backup & recovery, failover, system replication, point-in-time recovery etc. Also, a single transaction may span Row, Column and Document Store, commits are of course atomic. There is no asterisk after "ACID" that somehow limits any of the four properties. With the Document Store – and it being a full member of the SAP HANA family – you can store your JSON data in it and use it across various SAP HANA engines, like hierarchies, graph and spatial. The full ACID properties allow you to use your JSON data without worrying about lesser consistency. With the built-in Document Store, there are no additional operational tasks that would be needed to maintain a dedicated, secondary database. SAP HANA JSON Document Store Guide Introduction to SAP HANA JSON Document Store PUBLIC 5 Usage of the SAP HANA JSON Document Store One of the main use cases for using the Document Store is of course if your application already uses JSON. If your data is JSON and you need to store it, for long-term processing or for intermediates, the Document Stores is beneficial. It allows you to work on JSON data using filters, offers native aggregation and allows using your JSON data in other SAP HANA engines. For example, you may join your JSON data with Column Store tables. More than that, the Document Store may be beneficial for you in the following ways: ● Have a data model that requires many tables and joins are costly (de-normalization, using schema- flexibility) ● Have the need for many or changing attributes, like attributes for a "Product" object ("lumen", "mileage", etc.) that cannot be defined upfront ● Need a means for extensibility (using schema-flexibility) Diagnostics You can use database diagnostics (tracing) to analyze the details of Document Store operations. All Document Store trace components are identifiable by the "docstore*" prefix. Traces which are explicitly designed to trace SQL strings and intermediate results have the suffix "*_data". These traces may contain sensitive data therefore set the trace level of these data tracers only to DEBUG, INFO or WARNING if tracing sensitive information is acceptable. The trace levels ERROR and FATAL will not print any extra sensitive information and are safe to use in this respect. For more information, see Configure Traces in the SAP HANA Administration Guide. The Term "Document Store" The term "Document Store" was defined by the NoSQL community - as JSON "artifacts" are named "documents". Do not confuse "documents" with text or PDF files - the JSON Document Store cannot handle them. In technical terms, e.g. in process names, the Document Store is sometimes referred to as "DocStore". This is a synonym. Related Information SAP HANA Administration Guide SAP HANA JSON Document Store Guide 6 PUBLIC Introduction to SAP HANA JSON Document Store 3 Getting Started with the JSON Document Store To access the SQL features of JSON Document Store, you must first enable the feature on the System DB for a tenant (for example ALTER DATABASE XYZ123 ADD 'docstore'). For more information, see Enable the SAP HANA JSON Document Store [page 9] and Disable the SAP HANA JSON Document Store [page 10]. The following example shows how the Document Store may be used: CREATE COLLECTION Customers; INSERT INTO Customers VALUES({"name": 'Paul', "address": { "street": 'Hauptstraße 10', "city": 'Heidelberg' } }); SELECT * FROM Customers WHERE "address"."city" = 'Heidelberg' SELECT "address"."city", COUNT(*) FROM Customers GROUP BY "address"."city"; In the INSERT statement you can see the newly introduced "Object Expression" that allows the formation of JSON objects directly in SQL. But please note that this really is SQL and not JSON. It follows the SAP HANA SQL rules for identifiers and string literals: identifiers are in double-quotes, whereas string literals are in single- quotes. There is also a string interface available if you have a JSON-formatted string at hand. In the same example, you can see a SELECT using a path expression ("address"."city") to filter for the documents of interest. The last SELECT statement shows a native aggregation that is directly being performed within the Document Store. It is also possible to join with Column Store table, with explicit or implicit views: CREATE COLUMN TABLE SomeColumnStoreTable ("name" NVARCHAR(20), "age" INT); INSERT INTO SomeColumnStoreTable VALUES('Paul', 34); WITH myView AS (SELECT "name", "address"."city" AS "city" FROM Customers) SELECT cst."name", cst."age", myView."city" FROM myView