diff --git a/docs/en_US/developer_tools.rst b/docs/en_US/developer_tools.rst index 2e48cfd3c..eebbdf201 100644 --- a/docs/en_US/developer_tools.rst +++ b/docs/en_US/developer_tools.rst @@ -12,3 +12,4 @@ Contents: debugger query_tool + editgrid diff --git a/docs/en_US/editgrid.rst b/docs/en_US/editgrid.rst new file mode 100644 index 000000000..7d44e91ab --- /dev/null +++ b/docs/en_US/editgrid.rst @@ -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. + + + + diff --git a/docs/en_US/images/editgrid.png b/docs/en_US/images/editgrid.png new file mode 100644 index 000000000..f978805ef Binary files /dev/null and b/docs/en_US/images/editgrid.png differ diff --git a/docs/en_US/images/editgrid_toolbar.png b/docs/en_US/images/editgrid_toolbar.png new file mode 100644 index 000000000..ec55a9ae9 Binary files /dev/null and b/docs/en_US/images/editgrid_toolbar.png differ diff --git a/docs/en_US/query_tool.rst b/docs/en_US/query_tool.rst index e6dec553f..6d78f11e7 100644 --- a/docs/en_US/query_tool.rst +++ b/docs/en_US/query_tool.rst @@ -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 `. .. 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. \ No newline at end of file +To erase the content of the *Query History* tab, select *Clear history* from the *Clear* drop-down menu. \ No newline at end of file