feat: add explain support for SELECT queries

[BobdenOs]

It is best practice when using HANA to use execution plan visualization files to identify the root cause of slow performing queries. This change targets to add native support for generating and downloading the plan visualization files directly from the HANA service.

As all public facing documentation only instructs on how to use execution plan visualizations with HANA Studio (deprecated for HANA Cloud) and Hana Runtime Tools (Only available in development environments). It is difficult to understand how to get access to the execution plan visualization files and their contents. Therefor providing a direct API in the HANA Service will allow us to direct our users to a clear path to get a better insight into their application performance.

The ability to open the generated files is available in the Visual Studio Code plugin SAP HANA SQL Analyzer.

[BobdenOs]

Examples

Here are some example explain results for each database. To show how they provide their internal behavior and details.

SQLite

In the case of SQLite it will be quire rare that it is required to understand what is causing performance issues, but if provides a very detailed format on what it is exactly doing. So when it really matters it can be identified exactly where it is going wrong. It does not provide time measurements, but operations should be consistent in their execution times for each platform.

SQLite byte code

https://www.sqlite.org/opcode.html#codes

addr	opcode	p1	p2	p3	p4	p5	comment
0	Init	0	39	0	null	0	null
1	InitCoroutine	1	29	2	null	0	null
2	Noop	4	5	0	null	0	null
3	OpenRead	1	19	0	2	0	null
4	Rewind	1	28	0	null	0	null
5	Rowid	1	2	0	null	0	null
6	Column	1	1	3	null	0	null
7	BeginSubrtn	0	5	0	null	0	null
8	Null	0	6	6	null	0	null
9	Integer	1	7	0	null	0	null
10	Null	0	8	10	null	0	null
11	OpenRead	3	18	0	3	0	null
12	Rewind	3	21	0	null	0	null
13	Rowid	1	11	0	null	0	null
14	Column	3	2	12	null	0	null
15	Ne	12	20	11	BINARY-8	83	null
16	Rowid	3	15	0	null	0	null
17	Column	3	1	17	null	0	null
18	Function	11	13	12	jsonb_insert(-1)	0	null
19	AggStep	0	12	10	jsonb_group_array(1)	1	null
20	Next	3	13	0	null	1	null
21	AggFinal	10	1	0	jsonb_group_array(1)	0	null
22	Copy	10	6	0	null	0	null
23	DecrJumpZero	7	24	0	null	0	null
24	Return	5	8	1	null	0	null
25	Copy	6	4	0	null	0	null
26	Yield	1	0	0	null	0	null
27	Next	1	5	0	null	1	null
28	EndCoroutine	1	0	0	null	0	null
29	InitCoroutine	1	0	2	null	0	null
30	Yield	1	38	0	null	0	null
31	Copy	2	21	0	null	2	null
32	Copy	3	23	0	null	2	null
33	Copy	4	26	0	null	2	null
34	Function	2	26	25	->(2)	0	null
35	Function	43	19	18	json_insert(-1)	0	null
36	ResultRow	18	1	0	null	0	null
37	Goto	0	30	0	null	0	null
38	Halt	0	0	0	null	0	null
39	Transaction	0	0	32	0	1	null
40	String8	0	13	0	{}	0	null
41	String8	0	14	0	$."ID"	0	null
42	String8	0	16	0	$."title"	0	null
43	String8	0	19	0	{}	0	null
44	String8	0	20	0	$."ID"	0	null
45	String8	0	22	0	$."name"	0	null
46	String8	0	24	0	$."books"	0	null
47	String8	0	27	0	$	0	null
48	Goto	0	1	0	null	0	null

Postgres

The Postgres explain results show roughly what is being done and what entities are involved. Additionally it includes the time measurements for each node. To prevent confusion the execution times are resolved into their own execution time. As Postgres only provides total execution times which makes it look like the final node is always the longest running node, but it just includes all the sub nodes their runtime as well.

The results from Postgres are luckily much more straight forward to be understood what is going on then the SQLite results. Allowing people to actually analyze their productive queries. There are free tools that can be used to render the Postgres explain results, but there is no official solutions or vscode plugins that can do it in a secure way. Without uploading your explain JSON to their servers. Therefor the result is a simple mermaid graph that shows most of the critical information.

classDiagram

%% If you see this line, there is no Mermaid extension installed.
%% For example, use https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid

  namespace plan {

        class `0`["Subquery Scan (0.004 ms)"] {
          + to_jsonb(ROW(authors.id, authors.name, authors.books))
        }
  
        class `1`["Index Scan (0.009000000000000001 ms)
complex_associations_authors"] {
          + authors_1.id
        + authors_1.name
        + (SubPlan 1)
        }
  
        class `2`["Aggregate (0.008 ms)"] {
          + COALESCE(jsonb_agg(to_jsonb(ROW(books.id, books.title))), '[]'::jsonb)
        }
  
        class `3`["Seq Scan (0.003 ms)
complex_associations_books"] {
          + books.id
        + books.title
        + books.author_id
        }
  
  }

    `0` <-- `1`
    `1` <-- `2`
    `2` <-- `3`

Loading

SAP HANA

The most feature rich of the explain implementation is provide by HANA and the vscode plugin for visualizing execution plans. Which will be stored at the same location the other markdown files would be stored.