asterixdb-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From AsterixDB Code Review <do-not-re...@asterix-gerrit.ics.uci.edu>
Subject Change in asterixdb[master]: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
Date Tue, 15 Jun 2021 05:12:51 GMT
>From <milesh1@uci.edu>:

milesh1@uci.edu has uploaded this change for review. ( https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/11946
)


Change subject: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
......................................................................

[ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update

-user model changes: no
-storage format changes: no
-interface changes: yes

Details:
-Changed "explain" insertion to before first SELECT term
-Updated dashboard.md docs to match thesis paper

Change-Id: I68bc6fa27374217c460640ad2cff34a41b2d9ea4
---
M asterixdb/asterix-dashboard/src/node/src/app/dashboard/query/input.component.ts
M asterixdb/asterix-doc/src/site/markdown/dashboard.md
2 files changed, 120 insertions(+), 93 deletions(-)



  git pull ssh://asterix-gerrit.ics.uci.edu:29418/asterixdb refs/changes/46/11946/1

diff --git a/asterixdb/asterix-dashboard/src/node/src/app/dashboard/query/input.component.ts
b/asterixdb/asterix-dashboard/src/node/src/app/dashboard/query/input.component.ts
index 582b2f2..f885edb 100755
--- a/asterixdb/asterix-dashboard/src/node/src/app/dashboard/query/input.component.ts
+++ b/asterixdb/asterix-dashboard/src/node/src/app/dashboard/query/input.component.ts
@@ -93,7 +93,7 @@
     //sql++ keywords
     sqlppKeywords = "alter and as asc between by count create delete desc distinct drop from
group having in insert into " +
       "is join like not on or order select set union update values where limit use let dataverse
dataset exists with index type" +
-      "inner outer offset value type if exists declare function";
+      "inner outer offset value type if exists declare function explain";
 
     //sql++ builtin types
     sqlppTypes = "boolean tinyint smallint integer int bigint string float double binary
point line rectangle circle polygon" +
@@ -294,12 +294,18 @@
     }
 
     onClickExplain() {
-      let use_regex = /use .*?;/i
+      //for future use...currently we do not support explaining for INSERT, UPDATE, or DELETE
+      /*
+      let insert_regex = /insert/i;
+      let update_regex = /update/i;
+      let delete_regex = /delete/i;
+       */
+      let select_regex = /select/i;
 
       let explainString = "";
 
-      if (use_regex.test(this.queryString))
-        explainString = this.queryString.replace(use_regex, "$& explain ");
+      if (select_regex.test(this.queryString))
+        explainString = this.queryString.replace(select_regex, "explain $& ");
       else
         explainString = "explain " + this.queryString;
 
diff --git a/asterixdb/asterix-doc/src/site/markdown/dashboard.md b/asterixdb/asterix-doc/src/site/markdown/dashboard.md
index 2d6a519..35d196d 100644
--- a/asterixdb/asterix-doc/src/site/markdown/dashboard.md
+++ b/asterixdb/asterix-doc/src/site/markdown/dashboard.md
@@ -30,60 +30,62 @@
  
 ## <a id="basics">Basic Usage</a><font size="4"> <a href="#toc">[Back
to TOC]</a></font>
 
-Executing a query on this console is easy. First, select from the input options and then
select your execution mode.
+Executing a query is easy. Type your query into the query input box, select your run configurations,
and then click the 
+green play button to run the query. The output will appear below in the “Output” section.
 
 __Input Options__
 
-* `Dataverse` -  the dataverse that the query will use. The default is the `Default` dataverse.
This is not required to
-run a query and the console will try and autodetect the dataverse used in the query.
-* `Plan Format` - specifies what format of the resulting query plan. 
-    * `JSON` - results in the showing the interactive query plan viewer. 
-    * `STRING` - results in the text/string format of the query plan. Equivalent to the text
format from the old 19001 
-    console.
-* `Output Format` - the format of the result of the query.
-    * `JSON` - the default and will return the results in JSON. Can also view in `Tree` and
`Table` views in the output
-    section.
-    * `CSV (no header)` - will return CSV format but without the header. Can only view this
in `Table` view in the output
-    section.
-    * `CSV (header)` - will return CSV format with the header. Can only view this in `Table`
view in the output
-    section. See the [Exporting Data](#exporting) section for more information and examples.
+* `Dataverse` -   the dataverse that the query will use. The default is the `Default` dataverse.

+This input is not required and can be autodetected by running the query. 
+* `Output Format` - specifies the format of the result of the query.
+    * `JSON` (default) - query results are returned in JSON. Viewable in “Tree” and “Table”
mode.
+    * `CSV (no header)` - query results are returned in CSV format without the header. Viewable
only in “Table” mode.
+    * `CSV (header)` -  query results are returned in CSV format with the header. Viewable
only in “Table” mode. 
+    See the [Exporting Data](#exporting) section for more information and examples.
+* `Plan Format` -  specifies the format of the query plan (if requested). 
+    * `JSON` (default) - results in showing the interactive query plan viewer.
+    * `STRING` - results in the text / string format of the query plan. Equivalent to the
text format from the legacy 19001 console.
 
-To execute the query click the green triangle in the bottom right. Users may also choose
to click the `Explain` button.
-This will not actually run the query (no results returned) and will only return the query
plan. The console will default
-the view in the output section to `Plan`.
+To execute the query, click the green triangle in the bottom right of the query input section.

+Users may also choose to click the “Explain” button. This option will not actually run
the query. 
+It will return only the query plan instead. The console will default the view in the output
section to “Plan” as well.
 
-To cancel the query click the red stop button in the bottom right. This will send a `DELETE`
request to the server and cancel the previous
-request.
+To cancel the query, click the red stop button in the bottom right of the query input section.

+This will send a “DELETE” request to the server and cancel the previous request.
 
-The dashboard now supports autocomplete for SQL++ keywords. Use `CTRL+Space` to activate
the autocomplete.
+The dashboard also now supports autocomplete of SQL++ keywords. Use `CTRL+Space` to activate
the autocomplete feature. 
 
 ## <a id="qnav">Query Navigation</a><font size="4"> <a href="#toc">[Back
to TOC]</a></font>
 
-This console supports query history and has two different ways of navigating the query history.
On the input bar there is a section
-for `QUERY HISTORY` and there are also two arrows `<` and `>`.
+This console supports query history and has two different ways of navigating the query history.
On the input bar there 
+is a section for `QUERY HISTORY` and there are also two arrows (`<` and `>`).
 
-Utilizing the arrows will let you traverse the queries one by one. However, if the console
is already at the most recent query
-in the history and the user clicks the `>` or forward arrow, it will create a new empty
query. 
+Utilizing the arrows will let you traverse all previously run queries one by one. However,
if the console is already at 
+the most recent query in the history and the user clicks the `>` or forward arrow, it
will create a new empty query.
 
-The `QUERY HISTORY` dropdown allows users to jump through the history without having to step
through it with the arrows.
+The `QUERY HISTORY` drop down allows users to jump to a specific query in the history without
having to step through it with the arrows.
 
-When executing a query, this query will be counted as a new query if it is different (purely
the text of the query, not 
-the results) from the most recent query. It will subsequently be added to the query history.

+When executing a query, this query will be counted as a new query if it is different 
+(comparison is purely based on the query text, not the results) from the most recent query.

+It will subsequently be added to the front of the query history.
 
 ## <a id="metadatainspector">Metadata Inspector</a><font size="4"> <a
href="#toc">[Back to TOC]</a></font>
 
-The metadata inspector is the column on the rightside of the console. The `Refresh` button
is used to update the current metadata.
-When a user creates or drops a Dataverse, Dataset, Datatype, or Index the changes will not
be automatically reflected. User must
-click the `Refresh` button to get the most up to date data. 
+The metadata inspector is the column on the right side of the console. The `Refresh` button
is used to 
+update the current metadata. When a user creates or drops a dataverse, dataset, datatype,
user-defined function, or index, 
+the changes will not be automatically reflected. The user must click the `Refresh` button
to get the most up to date metadata.
 
 The console supports multiple dialogs/windows open at once. All of these are resizable and
draggable as well.
 
-Users can also click the `JSON` / `SUMMARY` button to toggle from the raw and parsed views.
`SUMMARY` is the default.
+Users can also click the `JSON` / `SUMMARY` button in the dialog windows to toggle between
the raw and parsed views of 
+the metadata objects. `SUMMARY` is the default.
 
 #### Dataverse
 
-Clicking a dataverse will add it to the shown metadata in this inspector. Users can select
as many dataverses as desired.
-The corresponding datasets, datatypes, and indices will appear.
+Clicking a dataverse will add it to the shown metadata in the inspector. Users can easily
see which dataverses are 
+currently being shown by the check mark to the left of the dataverse name. Users can select
as many dataverses as desired. 
+The datasets, datatypes, indices, and user-defined functions that are contained in the selected
dataverses will appear 
+in their corresponding sections.
 
 #### Datasets
 
@@ -94,20 +96,21 @@
 * `Datatype Name` - the name of the datatype of the dataset.
 * `Primary Keys` - the primary keys of the dataset.
 * `Sample` - if there is data inserted into the dataset, this is a section where viewers
can see a sample of the dataset.
-It is a `SELECT * FROM {dataset} LIMIT 1` query.
+It is equivalent to the user querying: `SELECT * FROM {dataset} LIMIT 1`.
 
 #### Datatypes
 
-Clicking on a datatypes will open a draggable and expandable window that contains information
about the datatype. This console
-does support nested datatypes.
+Clicking on a datatype will open a draggable and expandable window that contains information
about the datatype. 
+The console includes support for nested datatypes.
 
 * `Dataverse` - which dataverse the datatype belongs to.
 * `Datatype Name` - the name of the datatype.
-* `Fields` - a list of the fields in the dataset. Each field has information on whether it
is nullable or required. If the
-field is nested / not a primitive type, click on it to see the information of that type.
If the field is wrapped in `[ ]` or `{{ }}`,
-then it is an ordered list or unordered of that type respectively. If a field is italicized,
it is an anonymous type.
+* `Fields` - a list of the fields in the dataset. Each field has information on whether it
is nullable or required. If 
+the field is nested (not a primitive type), click on it to see the information about that
type. If the field is wrapped 
+in `[...]` or `{{...}}`, then it is an ordered list or unordered list respectively. If a
field is italicized, it means 
+it is an anonymous type.
 
-NOTE: the `JSON` view does not support nested like `SUMMARY` does.
+NOTE: the `JSON` view does not support nested like the `SUMMARY` view does.
 
 #### Index
 
@@ -115,85 +118,103 @@
 
 * `Dataverse` - which dataverse the index belongs to.
 * `Index Name` - the name of the index.
-* `Index Type` - the type of the index.
+* `Index Type` - the type of the index (primary or not primary).
 * `Search Key(s)` - the key(s) of the index.
 
+#### User-Defined Functions
 
+Clicking on an user-defined function will open a draggable and expandable window that contains
information about the 
+user-defined function.
+
+* `Dataverse` - which dataverse the user defined function (UDF) belongs to
+* `Function Name` - the name of the UDF
+* `Arity` - the number of parameters of the UDF
+* `Parameters` - the name of the parameters
+* `Definition` - the definition of the UDF
 
 ## <a id="planviewer">Interactive Plan Viewer</a><font size="4"> <a
href="#toc">[Back to TOC]</a></font>
 
-To view the interactive plan viewer, execute a query and switch to the `PLAN` tab in the
output section. Alternatively,
-users can click explain the query by clicking `EXPLAIN` instead of execute and the output
section will default to the 
-`PLAN` tab.
+To view the interactive plan viewer, either execute a query and switch to the `PLAN` tab
in the output section or `EXPLAIN` 
+the query and it will default to the `PLAN` view.
 
-To interact with the query plan, drag to move the view of the graph. Use the scroll wheel
or scroll movement to zoom in and out
-of the plan. 
+To interact with the query plan, drag to move around the graph. Users can also choose to
utilize the scroll function to 
+zoom in and out of the plan. To the left of the plan will be the `Plan Explorer`. This is
the main way that users will 
+be able to interact with the plan.
 
-The default plan orientation is `Bottom to Top` and can be swapped for `Top to Bottom` if
so desired.
+The plan orientation can be changed with the `Plan Explorer` under the `View` title. The
default is 
+`bottom to top`, but it can be swapped to `top to bottom` if desired.
 
-The default view of the plan is not detailed (just operator IDs and operator names). To look
at a more detailed plan, check
-the `Detailed` checkbox and the plan will reload with more detail per node.
+The default view of the plan is not detailed (just showing operator IDs and operator names).
To look at a more detailed 
+view of the plan, check the `Detailed` checkbox in the plan explorer and the plan will reload
with more detail per node.
 
 #### Traversing
 
-There are multiple ways to traverse the query plan. the `Go to Node` dropdown will keep track
of the currently selected
-node. Using the arrows next to the `Go to Node` dropdown will traverse the plan node by node
in a Depth First Search (DFS) 
-fashion. Selecting nodes on the `Go to Node` dropdown will jump the plan to the selected
node. 
+There are two main ways to traverse the query plan. The dropdown under `Node` will display
the node the user is currently at. 
+This dropdown will keep track of the node the user is at throughout.
 
-Utilizing both the arrows and the `Go to Node` dropdown, it is easy to trace through a plan.
+The arrows next to the dropdown can be used to step through the plan node by node in a Depth
First Search (DFS) fashion.
 
-#### Search (Detailed mode only)
+Selecting a node from the dropdown will jump the viewer to the node in the plan that was
selected. 
 
-The `Search` function appears when the plan is in `Detailed` mode. Search for specific string
occurrences in the plan. When
-the search icon is clicked, the first mathc will be selected (if there is a match). Use the
arrows that appear next to it
-to iterate through every match. 
-
-Must click `Clear Selections` after done with the search. 
-
-Unfortunately, at this time regular expression search is not supported.
+Utilizing both the dropdown and arrows, it is easy to trace through an entire plan.
 
 #### Variables (Detailed mode only)
 
-The `See Variable Occurences` dropdown will appear when the plan is in `Detailed` mode. Users
can select from any variable
-that appears in the plan. Selecting a variable will jump to the node of last occurrence.
The user can see how many occurence there
-are by the `See Variable Occurences` dropdown title (it will now include a fraction). 
+Under the `Variable` section of the `Plan Explorer`, there is a dropdown that will contain
all the variables that occur 
+in the plan. Selecting a variable there will jump the plan viewer to the node that contains
the last (top-most in the plan) 
+occurrence of that variable. The user can see how many occurrences there are via the `Variable
Occurrences` title above the dropdown. 
+The arrows to the right can be used to step through the occurrences.
 
-The arrows that appear can iterate through the occurences. 
+To skip to the variable’s declaration, click the `DECLARATION` button. This will jump the
plan viewer to the node of the 
+very first occurrence of that variable. To get back to the previous node, click `BACK`.
 
-Often, it is useful to be able to skip right to the declaration of a variable. By clicking
on the skip button, the plan
-will select the node where that variable was declared. To jump back to whatever node before,
click the undo button.
+#### Search (Detailed mode only)
 
-#### Clear Selections
+Use the `Search` bar to type in a string of interest. The plan explorer will search the plan
for that specific string in 
+each node. The number of matches will be displayed in the title above the search bar. Users
can use the arrows to the 
+right to step through the nodes that matched. 
 
-Clicking `Clear Selections` will reset the graph and focus on the first node in the plan.
+Users must click `Clear` after finishing with a search.
+
+Unfortunately, at this time, regular expression search is not supported.
+
+#### Clear
+
+Clicking `Clear` will reset the query plan graph and focus the viewer on the first node in
the plan.
 
 ## <a id="exporting">Exporting Data</a><font size="4"> <a href="#toc">[Back
to TOC]</a></font>
 
+Exporting data is a key part of the console’s functionality. Users can select from JSON,
JSONL, CSV (no header), 
+and CSV (header) as data types for the output.
+
 ### JSON/JSONL:
 
-1. Select `JSON` in the input `Output Format` option and run the query that you want to export.
-2. Click `Export` in the output section.
-3. Select between `JSON` and `JSONL` (JSON Lines). Adjust the filename to the desired name.
-4. Click `Export` to start the download. 
+1. Select `JSON` on the input `Output Format` option and run the query that you want to export
the results of
+2. Click `Export` in the output section
+3. Select between `JSON` and `JSONL` (JSON Lines) and adjust the filename to the desired
name
+4. Click `Export` to start the download
 
 ### CSV (no header):
 
-1. Select `CSV (no header)` in the input `Output Format` option and run the query that you
want to export.
-2. Click `Export` in the output section.
-3. Adjust the filename to the desired name.
-4. Click `Export` to start the download.
+1. Select `CSV (no header)` on the input `Output Format` option and run the query that you
want to export the results of
+2. Click `Export` in the output section
+3. Adjust the filename to the desired name
+4. Click `Export` to start the download
 
 ### CSV (header):
 
-1. Create a type that supports the query you want to run.
-2. Set the `output-record-type` before your query
-3. Select `CSV (no header)` in the input `Output Format` option and run the query that you
want to export.
-4. Click `Export` in the output section.
-5. Adjust the filename to the desired name.
-6. Click `Export` to start the download.
+1. Create a datatype that supports the query you want to run
+2. Set the `output-record-type` to this type before your query
+3. Select `CSV (no header)` on the input `Output Format` option and run the query that you
want to export the results of
+4. Click `Export` in the output section
+5. Adjust the filename to the desired name
+6. Click `Export` to start the download
 
-This one is trickier. In order to get the header in the CSV format, we need to set the `output-record-type`
in the query
-in order to get the headers. To explain further, here is an example using the TinySocial
dataset from the Using SQL++ Primer.
+This one is clearly a little more involved. In order to get the desired header in the CSV
format, it is necessary to 
+set an `output-record-type` for the query. To better illustrate how to control this format,
here is an example using the 
+TinySocial dataset from the “Using SQL++” AsterixDB primer.
+
+For context, here’s the GleambookMessages DDL statement.
 
     CREATE TYPE GleambookMessageType AS {
         messageId: int,
@@ -206,8 +227,8 @@
     CREATE DATASET GleambookMessages(GleambookMessageType)
         PRIMARY KEY messageId;
 
-If we wanted to export `messageId`, `authorId`, and `senderLocation` in CSV format with headers,
we would have to create
-an additional type to support this export.
+First, create the type of the expected output. If the goal is to export `messageId`, `authorId`,
and `senderLocation` in 
+CSV format with headers, create an additional type to support this export. 
 
     CREATE TYPE GleambookMessages_exportCSV AS {
         messageId: int,
@@ -215,7 +236,7 @@
         senderLocation: point
     };
     
-The query would then look something like this:
+The query should then look something like this:
     
     USE TinySocial;
     
@@ -224,7 +245,7 @@
     SELECT messageId, authorId, senderLocation
     FROM GleambookMessages;
     
-Now run the query with the `CSV (header)` input option and the result will contain the hedaer
`messageId`, `authorId`,
+Now run the query with the `CSV (header)` input option and the result will contain the header
`messageId`, `authorId`, 
 and `senderLocation`.
 
 ## <a id="development">Development</a><font size="4"> <a href="#toc">[Back
to TOC]</a></font>

-- 
To view, visit https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/11946
To unsubscribe, or for help writing mail filters, visit https://asterix-gerrit.ics.uci.edu/settings

Gerrit-Project: asterixdb
Gerrit-Branch: master
Gerrit-Change-Id: I68bc6fa27374217c460640ad2cff34a41b2d9ea4
Gerrit-Change-Number: 11946
Gerrit-PatchSet: 1
Gerrit-Owner: milesh1@uci.edu
Gerrit-MessageType: newchange

Mime
View raw message