IntenseWebs/pgadmin4
3
0
Fork 0
mirror of https://github.com/pgadmin-org/pgadmin4.git synced 2025-02-03 04:00:55 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update query tool docs.

Browse Source
This commit is contained in:
Susan Douglas 2017-12-11 12:01:54 +00:00 committed by Dave Page
parent 4bcec932a3
commit 61080ce513
5 changed files with 214 additions and 110 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/en_US/developer_tools.rst
View File

@ -12,3 +12,4 @@ Contents:
debugger
query_tool
editgrid

98
docs/en_US/editgrid.rst Normal file
View File

@ -0,0 +1,98 @@
.. _editgrid:
***********************************
`Reviewing and Editing Data`:index:
***********************************
To review or modify data, right click on a table or view name in the *Browser* tree control. When the context menu opens, use the *View/Edit Data* menu to specify the number of rows you would like to display in the editor panel.
.. image:: images/editgrid.png
To modify the content of a table, each row in the table must be uniquely identifiable. If the table definition does not include an OID or a primary key, the displayed data is read only. Note that views cannot be edited; updatable views (using rules) are not supported.
The editor features a toolbar that allows quick access to frequently used options, and a work environment divided into two panels:
* The upper panel displays the SQL command that was used to select the content displayed in the lower panel.
* The lower panel (the Data Grid) displays the data selected from the table or view.
**The View/Edit Data Toolbar**
The toolbar includes context-sensitive icons that provide shortcuts to frequently performed tasks.
.. image:: images/editgrid_toolbar.png
Hover over an icon to display a tooltip that describes the icon's functionality.
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| Icon | Behavior | Shortcut |
+======================+===================================================================================================+=============+
| *Save* | Use the *Save* icon to save your changes to the currently displayed table contents. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Find* | Use options on the *Find* menu to access Search and Replace functionality or to Jump to another | Ctrl/Cmd +F |
| | line. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Copy* | Click the *Copy* icon to copy the currently selected data. | Ctrl+C |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Paste Row* | Click the *Paste Row* icon to paste the content that is currently on the clipboard. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Delete Row* | Use the *Delete Row* icon to add a new row in the output panel. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Filter* | Click the *Filter* icon to open a dialog that allows you to write and apply a filter for the | |
| | content currently displayed in the output panel. Click the down arrow to open the *Filter* drop- | |
| | down menu and select from pre-defined options: | |
| | | |
| | Use options on the *Filter* menu to quick-sort or quick-filter the data set: | |
| | | |
| | * Filter: This option opens a dialog that allows you to define a filter. A filter is a | |
| | condition that is supplied to an arbitrary WHERE clause that restricts the result set. | |
| | | |
| | * Remove Filter: This option removes all selection / exclusion filter conditions. | |
| | | |
| | * By Selection: This option refreshes the data set and displays only those rows whose | |
| | column value matches the value in the cell currently selected. | |
| | | |
| | * Exclude Selection: This option refreshes the data set and excludes those rows whose | |
| | column value matches the value in the cell currently selected. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *No limit* | Use the *No limit* drop-down listbox to specify how many rows to display in the output panel. | |
| | Select from: *No limit* (the default), *1000 rows*, *500 rows*, or *100 rows*. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Execute/Refresh* | Click the *Execute/Refresh* icon to execute the SQL command that is displayed in the top panel. | F5 |
| | If you have not saved modifications to the content displayed in the data grid, you will be | |
| | prompted to confirm the execution. To preserve your changes before refreshing the content, click | |
| | the *Save* toolbar button before executing the refresh. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Stop* | Click the *Stop* icon to cancel the execution of the currently running query. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Clear query window* | Use the *Clear query window* drop-down menu to erase the contents of the *History* tab. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Download as CSV* | Click the *Download as CSV* icon to download the result set of the current query to a | F8 |
| | comma-separated list. You can control the CSV settings through | |
| | *Preferences -> SQL Editor -> CSV output* dialogue. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
**The Data Grid**
The top row of the data grid displays the name of each column, the data type, and if applicable, the number of characters allowed. A column that is part of the primary key will additionally be marked with [PK].
To modify the displayed data:
* To change a numeric value within the grid, double-click the value to select the field. Modify the content in the square in which it is displayed.
* To change a non-numeric value within the grid, double-click the content to access the edit bubble. After modifying the contentof the edit bubble, click the *Save* button to display your changes in the data grid, or *Cancel* to exit the edit bubble without saving.
To enter a newline character, click Ctrl-Enter or Shift-Enter. Newline formatting is only displayed when the field content is accessed via an edit bubble.
To add a new row to the table, enter data into the last (unnumbered) row of the table. As soon as you store the data, the row is assigned a row number, and a fresh empty line is added to the data grid.
To write a SQL NULL to the table, simply leave the field empty. When you store the new row, the will server fill in the default value for that column. If you store a change to an existing row, the value NULL will explicitly be written.
To write an empty string to the table, enter the special string '' (two single quotes) in the field. If you want to write a string containing solely two single quotes to the table, you need to escape these quotes, by typing \'\'
To delete a row, press the *Delete* toolbar button. A popup will open, asking you to confirm the deletion.
To commit the changes to the server, select the *Save* toolbar button. Modifications to a row are written to the server automatically when you select a different row.

BIN
docs/en_US/images/editgrid.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 126 KiB

BIN
docs/en_US/images/editgrid_toolbar.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.5 KiB

225
docs/en_US/query_tool.rst
View File

@ -4,7 +4,7 @@
The Query tool
**************
The Query tool is a powerful, feature-rich environment that allows you to execute arbitrary SQL commands and review the result set. If you access the Query tool via the *Query Tool* menu option on the *Tools* menu, you can:
The Query tool is a powerful, feature-rich environment that allows you to execute arbitrary SQL commands and review the result set. You can access the Query tool via the *Query Tool* menu option on the *Tools* menu, or through the context menu of select nodes of the Browser tree control. The Query Tool allows you to:
* Issue ad-hoc SQL queries.
* Execute arbitrary SQL commands.
@ -12,105 +12,121 @@ The Query tool is a powerful, feature-rich environment that allows you to execut
* Review the execution plan of a SQL statement in either a text or a graphical format.
* View analytical information about a SQL statement.
If you open the Query tool via the *View Data* context-menu, the Query tool acts as a data editor, allowing you to:
* View or modify the data that is stored in a table.
* Filter the result set.
* Save the data displayed in the output panel to a CSV file.
* Review the execution plan of a SQL statement in either a text or a graphical format.
* View analytical information about a SQL statement.
.. image:: images/query_tool.png
The Query tool features a toolbar that allows quick access to frequently used options, and a work environment divided into two panels:
You can open multiple copies of the Query tool in individual tabs simultaneously. To close a copy of the Query tool, click the *X* in the upper-right hand corner of the tab bar.
* The upper panel of the Query tool contains the *SQL Editor*. You can use the panel to manually enter a query, or review the query that generated the result set displayed in the lower panel.
* The lower panel of the Query tool contains the *Data Output* panel. The output panel displays the result of a query, or information about a query's execution plan.
The Query Tool features two panels:
pgAdmin allows you to open multiple copies of the Query tool (in individual tabs) simultaneously. For example, if you select *Query tool* from the *Tools* menu, the Query tool opens in a tab labeled *Query-1*; if you open the Query tool again (without closing *Query-1*), a second copy will open in *Query-2*. To close a copy of the Query tool, click the *X* in the upper-right hand corner of the tab bar.
* The upper panel displays the *SQL Editor*. You can use the panel to enter, edit, or execute a query.
* The lower panel displays the *Data Output* panel. The tabbed panel displays the result set returned by a query, information about a query's execution plan, server messages related to the query's execution, and a history of the queries invoked in the SQL Editor.
**The Query tool Toolbar**
**The Query Tool Toolbar**
The *Query tool* toolbar uses context-sensitive icons that provide shortcuts to frequently performed tasks. If an icon is highlighted, the option is enabled; if the icon is grayed-out, the task is disabled.
The *Query Tool* toolbar uses context-sensitive icons that provide shortcuts to frequently performed tasks. If an icon is highlighted, the option is enabled; if the icon is grayed-out, the task is disabled. Please note that disabled icons may support functionality accessed via the :ref:`data editor <editgrid>`.
.. image:: images/query_toolbar.png
Hover over an icon to display a tooltip that describes the icon's functionality:
+----------------------+---------------------------------------------------------------------------------------------------+
| Icon | Behavior |
+======================+===================================================================================================+
| *Open File* | Click the *Open File* icon to display a previously saved query in the SQL Editor. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Save* | Click the *Save* icon to save the query that is currently displayed in the SQL Editor. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Copy* | Click the *Copy* icon to copy the currently selected row. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Paste* | Click the *Paste* icon to paste the content that is currently on the clipboard. You can control |
| | the copied data settings through *Preferences -> SQL Editor -> Results grid* dialogue. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Add New Row* | Use the *Add New Row* icon to add a new row in the output panel. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Filter* | Click the *Filter* icon to open a dialog that allows you to write and apply a filter for the |
| | content currently displayed in the output panel. Click the down arrow to open the *Filter* drop- |
| | down menu and select from pre-defined options: |
| | |
| | Select *Remove* to remove the currently applied filter and display the complete result set. |
| | |
| | Select *By selection* to refresh the displayed data, displaying only those rows that have columns|
| | that match the currently highlighted value. |
| | |
| | Select *Exclude selection* to refresh the displayed data, excluding those rows that have columns |
| | that match the currently highlighted value. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *No limit* | Use the *No limit* drop-down listbox to specify how many rows to display in the output panel. |
| | Select from: *No limit* (the default), *1000 rows*, *500 rows*, or *100 rows*. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Execute/Refresh* | Click the *Execute/Refresh* icon to either execute or refresh the query highlighted in the SQL |
| | editor panel. Click the down arrow to access other execution options: |
| | |
| | Select *Execute/Refresh* to invoke the SQL command and refresh the result set. |
| | |
| | Select *Explain* to view an explanation plan for the current query. The result of the |
| | EXPLAIN is displayed graphically on the *Explain* tab of the output panel, and in text |
| | form on the *Data Output* tab. |
| | |
| | Select *Explain analyze* to invoke an EXPLAIN ANALYZE command on the current query. |
| | |
| | Navigate through the *Explain Options* menu to select options for the EXPLAIN command: |
| | |
| | Select *Verbose* to display additional information regarding the query plan. |
| | |
| | Select *Costs* to include information on the estimated startup and total cost of each |
| | plan node, as well as the estimated number of rows and the estimated width of each |
| | row. |
| | |
| | Select *Buffers* to include information on buffer usage. |
| | |
| | Select *Timing* to include information about the startup time and the amount of time |
| | spent in each node of the query. |
| | |
| | Add a check next to *Auto-Rollback* to instruct the server to automatically roll back a |
| | transaction if an error occurs during the transaction. |
| | |
| | Add a check next to *Auto-Commit* to instruct the server to automatically commit each |
| | transaction. Any changes made by the transaction will be visible to others, and |
| | durable in the event of a crash. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Stop* | Click the *Stop* icon to cancel the execution of the currently running query. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Clear query window* | Use options on the *Clear query window* drop-down menu to erase the contents of |
| | the SQL editor panel or the *History* tab. |
+----------------------+---------------------------------------------------------------------------------------------------+
| *Download as CSV* | Click the *Download as CSV* icon to download the result set of the current query to a |
| | comma-separated list. You can control the CSV settings through |
| | *Preferences -> SQL Editor -> CSV output* dialogue. |
+----------------------+---------------------------------------------------------------------------------------------------+
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| Icon | Behavior | Shortcut |
+======================+===================================================================================================+=============+
| *Open File* | Click the *Open File* icon to display a previously saved query in the SQL Editor. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Save* | Click the *Save* icon to perform a quick-save of a previously saved query, or to access the | |
| | *Save* menu: | |
| | | |
| | * Select *Save* to save the selected content of the SQL Editor panel in a file. | |
| | | |
| | * Select *Save As* to open a new browser dialog and specify a new location to which to save the | |
| | selected content of the SQL Editor panel. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Find* | Use the *Find* menu to search, replace, or navigate the code displayed in the SQL Editor: | |
| | | |
| | * Select *Find* to provide a search target, and search the SQL Editor contents. | Cmd+F |
| | | |
| | * Select *Find next* to locate the next occurrence of the search target. | Cmd+G |
| | | |
| | * Select *Find previous* to move to the last occurrence of the search target. | Cmd+Shift+G |
| | | |
| | * Select *Pesistent find* to identify all occurrences of the search target within the editor. | |
| | | |
| | * Select *Replace* to locate and replace (with prompting) individual occurrences of the target. | Cmd+Shift+F |
| | | |
| | * Select *Replace all* to locate and replace all occurrences of the target within the editor. | |
| | | |
| | * Select *Jump* to navigate to the next occurrence of the search target. | Alt+G |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Copy* | Click the *Copy* icon to copy the content that is currently highlighted in the Data Output panel. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Edit* | Use options on the *Edit* menu to access text editing tools; the options operate on the text | |
| | displayed in the SQL Editor panel: | |
| | | |
| | * Select *Indent Selection* to indent the currently selected text. | Tab |
| | | |
| | * Select *Unindent Selection* to remove indentation from the currently selected text. | Shift+Tab |
| | | |
| | * Select *Inline Comment Selection* to enclose any lines that contain the selection in | Cmd+/ |
| | SQL style comment notation. | |
| | | |
| | * Select *Inline Uncomment Selection* to remove SQL style comment notation from the | Cmd+. |
| | selected line. | |
| | | |
| | * Select *Block Comment* to enclose all lines that contain the selection in C style | Shift+Cmd+/ |
| | comment notation. This option acts as a toggle. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Execute/Refresh* | Click the *Execute/Refresh* icon to either execute or refresh the query highlighted in the SQL | |
| | editor panel. Click the down arrow to access other execution options: | |
| | | |
| | * Select *Execute/Refresh* to invoke the SQL command and refresh the result set. | F5 |
| | | |
| | * Select *Explain* to view an explanation plan for the current query. The result of the | F7 |
| | EXPLAIN is displayed graphically on the *Explain* tab of the output panel, and in text | |
| | form on the *Data Output* tab. | |
| | | |
| | * Select *Explain analyze* to invoke an EXPLAIN ANALYZE command on the current query. | Shift+F7 |
| | | |
| | * Navigate through the *Explain Options* menu to select options for the EXPLAIN command: | |
| | | |
| | Select *Verbose* to display additional information regarding the query plan. | |
| | | |
| | Select *Costs* to include information on the estimated startup and total cost of each | |
| | plan node, as well as the estimated number of rows and the estimated width of each | |
| | row. | |
| | | |
| | Select *Buffers* to include information on buffer usage. | |
| | | |
| | Select *Timing* to include information about the startup time and the amount of time | |
| | spent in each node of the query. | |
| | | |
| | * Add a check next to *Auto-Rollback* to instruct the server to automatically roll back a | |
| | transaction if an error occurs during the transaction. | |
| | | |
| | * Add a check next to *Auto-Commit* to instruct the server to automatically commit each | |
| | transaction. Any changes made by the transaction will be visible to others, and | |
| | durable in the event of a crash. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Stop* | Click the *Stop* icon to cancel the execution of the currently running query. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Clear query window* | Use options on the *Clear* drop-down menu to erase display contents: | |
| | | |
| | * Select *Clear Query Window* to erase the content of the SQL Editor panel. | |
| | | |
| | | |
| | * Select *Explain analyze* to invoke an EXPLAIN ANALYZE command on the current query. | Shift+F7 |
| | | |
| | the SQL editor panel or the *History* tab. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
| *Download as CSV* | Click the *Download as CSV* icon to download the result set of the current query to a | F8 |
| | comma-separated list. You can specify the CSV settings through | |
| | *Preferences -> SQL Editor -> CSV output* dialogue. | |
+----------------------+---------------------------------------------------------------------------------------------------+-------------+
**The SQL Editor Panel**
The *SQL editor* panel contains a workspace for entering commands; you can read a query from a file, or type a query. The SQL editor features syntax coloring and autocompletion to help you develop queries.
The *SQL editor* panel is a workspace where you can manually provide a query, copy a query from another source, or read a query from a file. The SQL editor features syntax coloring and autocompletion.
.. image:: images/query_sql_editor.png
@ -118,44 +134,35 @@ To use autocomplete, begin typing your query; when you would like the Query edit
.. image:: images/query_autocomplete.png
After entering a query, select the *Execute/Refresh* icon from the toolbar. The complete contents of the SQL editor panel will be sent to the database server for execution. To execute only a section of the code that is displayed in the SQL editor, highlight the text that you want the server to execute, and click the *Execute/Refresh* icon:
After entering a query, select the *Execute/Refresh* icon from the toolbar. The complete contents of the SQL editor panel will be sent to the database server for execution. To execute only a section of the code that is displayed in the SQL editor, highlight the text that you want the server to execute, and click the *Execute/Refresh* icon.
.. image:: images/query_execute_section.png
The message returned by the server when a command executes is displayed on the *Messages* tab of the output panel. If the command is successful, the *Messages* tab displays execution details:
The message returned by the server when a command executes is displayed on the *Messages* tab. If the command is successful, the *Messages* tab displays execution details.
.. image:: images/query_tool_message.png
The editor also offers several features that help with code formatting:
Options on the *Edit* menu offer functionality that helps with code formatting and commenting:
* The auto-indent feature will automatically indent text to the same depth as the previous line when you press the Return key.
* Block indent text by selecting two or more lines and pressing the Tab key.
* Implement or remove SQL style or toggle C style comment notation within your code.
**The Data Output Panel**
Use the *Data Output* panel of the *Query tool* to view data and information generated by a query in the *SQL editor*, or to *View Data* for an object currently selected in the *pgAdmin* tree control.
The *Data Output* panel organizes output through the following tabs: *Data Output*, *Explain*, *Messages*, and *History*.
The *Data Output* panel displays data and statistics generated by the most recently executed query.
.. image:: images/query_output_data.png
If the Query tool is opened through the *Query tool* menu option on the *Tools* menu, you can use the *Data Output* tab to view the results of an arbitrary query in a table format. If the Query tool is opened through a *View Data* context menu, the *Data Output* tab will display the data stored in the table from which the Query tool was opened.
The *Data Output* tab displays the result set of the query in a table format. You can:
* If enabled, use the *Filter* options from the Query tool toolbar to refine the result set displayed on the *Data Output* tab.
* If enabled, use the *No limit* drop-down to specify how many rows to display on the *Data Output* tab.
* If enabled, use the *Execute/Refresh* options to retrieve query execution information and set query execution options.
* Select and copy from the displayed result set.
* Use the *Execute/Refresh* options to retrieve query execution information and set query execution options.
* Use the *Download as CSV* icon to download the content of the *Data Output* tab as a comma-delimited file.
All rowsets from previous queries or commands that are displayed in the *Data Output* panel will be discarded when you invoke another query; open another query tool browser tab to keep your previous results available.
If the Query Tool is opened using the *View Data* menu option and the data is updatable and has a primary key, then you can double-click on values on the *Data Output* tab and edit them:
* To enter a NULL, clear the value of the string.
* To enter a blank set the value of the cell to ''.
* To enter the string ''. enter the value \'\'.
Once the data has been edited as required, use the Save button to save the changes to the database.
Use the *Explain* tab to view a graphical representation of a query:
.. image:: images/query_output_explain.png
@ -166,21 +173,19 @@ To generate a graphical explain diagram, open the *Explain* tab, and select *Exp
Note that the query plan that accompanies the *Explain analyze* is available on the *Data Output* tab.
Use the *Messages* tab to view information about the last-executed query:
Use the *Messages* tab to view information about the most recently executed query:
.. image:: images/query_output_error.png
If the server returns an error, the error message will be displayed on the *Messages* tab, and the syntax that cause the error will be underlined in the SQL editor.
If a query succeeds, the *Messages* tab displays how long the query took to complete and how many rows were retrieved:
If the server returns an error, the error message will be displayed on the *Messages* tab, and the syntax that caused the error will be underlined in the SQL editor. If a query succeeds, the *Messages* tab displays how long the query took to complete and how many rows were retrieved:
.. image:: images/query_output_messages.png
Use the *History* tab to review activity for the current session:
Use the *Query History* tab to review activity for the current session:
.. image:: images/query_output_history.png
The History tab displays:
The Query History tab displays information about recent commands:
* The date and time that a query was invoked.
* The text of the query.
@ -188,4 +193,4 @@ The History tab displays:
* The amount of time it took the server to process the query and return a result set.
* Messages returned by the server (not noted on the *Messages* tab).
To erase the content of the *History* tab, select *Clear history* from the *Clear query window* drop-down menu.
To erase the content of the *Query History* tab, select *Clear history* from the *Clear* drop-down menu.