You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@asterixdb.apache.org by AsterixDB Code Review <do...@asterix-gerrit.ics.uci.edu> on 2021/06/15 05:12:51 UTC
Change in asterixdb[master]: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
From <mi...@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
Change in asterixdb[master]: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
Posted by AsterixDB Code Review <do...@asterix-gerrit.ics.uci.edu>.
Anon. E. Moose #1000171 has posted comments on this change. ( https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/11946 )
Change subject: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
......................................................................
Patch Set 3:
Analytics Compatibility Compilation Successful
https://cbjenkins.page.link/weJ5m5n6bbPBJXh57 : SUCCESS
--
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: 3
Gerrit-Owner: milesh1@uci.edu
Gerrit-Reviewer: Anon. E. Moose #1000171
Gerrit-Reviewer: Jenkins <je...@fulliautomatix.ics.uci.edu>
Gerrit-Comment-Date: Fri, 18 Jun 2021 06:35:55 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: No
Gerrit-MessageType: comment
Change in asterixdb[master]: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
Posted by AsterixDB Code Review <do...@asterix-gerrit.ics.uci.edu>.
From <mi...@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
Change in asterixdb[master]: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
Posted by AsterixDB Code Review <do...@asterix-gerrit.ics.uci.edu>.
From Jenkins <je...@fulliautomatix.ics.uci.edu>:
Jenkins has posted comments on this change. ( https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/11946 )
Change subject: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
......................................................................
Patch Set 3: Integration-Tests+1
Integration Tests Successful
https://asterix-jenkins.ics.uci.edu/job/asterix-gerrit-integration-tests/12109/ : SUCCESS
--
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: 3
Gerrit-Owner: milesh1@uci.edu
Gerrit-Reviewer: Anon. E. Moose #1000171
Gerrit-Reviewer: Jenkins <je...@fulliautomatix.ics.uci.edu>
Gerrit-Comment-Date: Fri, 18 Jun 2021 07:29:53 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: Yes
Gerrit-MessageType: comment
Change in asterixdb[master]: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
Posted by AsterixDB Code Review <do...@asterix-gerrit.ics.uci.edu>.
Anon. E. Moose #1000171 has posted comments on this change. ( https://asterix-gerrit.ics.uci.edu/c/asterixdb/+/11946 )
Change subject: [ASTERIXDB-2907][DASHBOARD] Explain Fix and Docs Update
......................................................................
Patch Set 1:
Analytics Compatibility Compilation Successful
https://cbjenkins.page.link/Jyv5zeHFnCZvnVjK6 : SUCCESS
--
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-CC: Anon. E. Moose #1000171
Gerrit-CC: Jenkins <je...@fulliautomatix.ics.uci.edu>
Gerrit-Comment-Date: Tue, 15 Jun 2021 05:17:48 +0000
Gerrit-HasComments: No
Gerrit-Has-Labels: No
Gerrit-MessageType: comment