diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 353ece1d50..9f7b2d31a5 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -17,17 +17,8 @@ include::develop:partial$nav.adoc[] include::tutorials:partial$nav.adoc[] include::guides:partial$nav.adoc[] -include::search:partial$nav.adoc[] - -* xref:home:ROOT:sdk.adoc[SDKs] - ** xref:sdk-extensions::distributed-acid-transactions.adoc[Distributed ACID Transactions] - ** xref:sdk-extensions::field-level-encryption.adoc[Field Level Encryption] - ** xref:sdk-extensions::response-time-observability.adoc[Response Time Observability] - ** xref:sdk-extensions::spring-data-couchbase.adoc[Spring Data Couchbase] - ** xref:getting-started:starter-kits.adoc[Starter Kits] - ** xref:sdk:sdk-doctor.adoc[Troubleshooting Connections with SDK Doctor] - include::n1ql:partial$nav.adoc[] +include::search:partial$nav.adoc[] * xref:fts:fts-introduction.adoc[Search] ** xref:fts:fts-quickstart-guide.adoc[Quickstart Guide] ** xref:fts:fts-creating-indexes.adoc[Create Search Indexes] @@ -201,6 +192,14 @@ include::n1ql:partial$nav.adoc[] ** xref:eventing:troubleshooting-best-practices.adoc[Troubleshooting and Best Practices] ** xref:eventing:eventing-faq.adoc[Frequently Asked Questions] include::analytics:partial$nav.adoc[] +* xref:home:ROOT:sdk.adoc[SDKs] + ** xref:sdk-extensions::distributed-acid-transactions.adoc[Distributed ACID Transactions] + ** xref:sdk-extensions::field-level-encryption.adoc[Field Level Encryption] + ** xref:sdk-extensions::response-time-observability.adoc[Response Time Observability] + ** xref:sdk-extensions::spring-data-couchbase.adoc[Spring Data Couchbase] + ** xref:getting-started:starter-kits.adoc[Starter Kits] + ** xref:sdk:sdk-doctor.adoc[Troubleshooting Connections with SDK Doctor] +include::third-party:partial$nav.adoc[] .Learn * xref:learn:architecture-overview.adoc[Overview] @@ -331,8 +330,6 @@ include::analytics:partial$nav.adoc[] ** xref:manage:manage-security/manage-system-secrets.adoc[Manage System Secrets] ** xref:manage:manage-security/manage-connections-and-disks.adoc[Manage Connections and Disks] * xref:manage:manage-statistics/manage-statistics.adoc[Manage Statistics] -* xref:manage:manage-indexes/manage-indexes.adoc[Manage Indexes] -* xref:manage:import-documents/import-documents.adoc[Import Documents] * xref:manage:manage-backup-and-restore/manage-backup-and-restore.adoc[Manage Backup and Restore] ** xref:backup-restore:enterprise-backup-restore.adoc[cbbackupmgr] *** xref:backup-restore:cbbackupmgr-strategies.adoc[Strategies] @@ -341,8 +338,6 @@ include::analytics:partial$nav.adoc[] *** xref:backup-restore:cbbackupmgr-network-filesystems.adoc[Network Filesystems] *** xref:backup-restore:cbbackupmgr-encryption.adoc[Encryption] * xref:manage:monitor/monitor-intro.adoc[Monitor] - ** xref:manage:monitor/monitoring-n1ql-query.adoc[Monitor Queries] - ** xref:manage:monitor/monitoring-indexes.adoc[Monitor Indexes] ** xref:manage:monitor/xdcr-monitor-timestamp-conflict-resolution.adoc[Monitor Clock Drift] ** xref:manage:monitor/set-up-prometheus-for-monitoring.adoc[Configure Prometheus to Collect Couchbase Metrics] * xref:manage:troubleshoot/troubleshoot.adoc[Troubleshoot] diff --git a/modules/manage/pages/import-documents/import-documents.adoc b/modules/manage/pages/import-documents/import-documents.adoc index a00a231966..a07ad1e9bb 100644 --- a/modules/manage/pages/import-documents/import-documents.adoc +++ b/modules/manage/pages/import-documents/import-documents.adoc @@ -1,9 +1,16 @@ = Import Documents +:imagesdir: ../../assets/images +:page-pagination: :description: Couchbase Web Console provides a graphical interface for the importing of data, in both JSON and other formats. [abstract] {description} +[.signpost] +image:ROOT:couchbase-logo.svg["Couchbase Server", 25.6] +This page is for Couchbase Server. +For Couchbase Capella, see xref:cloud:clusters:data-service/import-data-documents.adoc[]. + [#importing-data] == Options for Importing Data @@ -17,7 +24,7 @@ Data can be imported into Couchbase Server by means of the following: The *cbimport json* and *cbimport csv* command-line utilities should be used in preference to Couchbase Web Console whenever high-performance importing is required; and especially when the data-set to be imported is greater in size than 100 MB. -For information on the *cbimport* command-line utilities, access the *cbimport* entry, in the *CLI Reference*, in the vertical navigation bar, to the left. +For information on the *cbimport* command-line utilities, see xref:tools:cbimport.adoc[]. The remainder of this page explains how to import data by means of Couchbase Web Console. Note the following prerequisites: @@ -29,7 +36,7 @@ The procedures below assume that a bucket named `testBucket` has been created. * Before attempting to import data with Couchbase Web Console, ensure that the *Query Service* has been deployed on the cluster: data-import with Couchbase Web Console depends on this service. [#access-the-import-documents-panel] -== Accessing the Import Documents Panel +== Access the Import Documents Panel Access the *Import Documents* panel of Couchbase Web Console, as follows: @@ -46,7 +53,7 @@ The *Import* panel is now displayed: image::import-documents/importDocumentsPanel.png[,720,align=left] [#understanding-the-import-panel] -== Understanding the Import Panel +== Understand the Import Panel The *Import* panel displays the following interactive graphical elements: @@ -107,7 +114,7 @@ Status on the operation is displayed immediately below the button. Note that if the operation takes a long time, the button's label is changed to *Cancel*; at which point, by left-clicking, the user can cancel the import operation. [#import-a-json-list] -== Importing a JSON List +== Import a JSON List To be imported, JSON documents must be specified in a file: the file itself must then specified as the target for import. Within the file, the documents can be specified in either of two ways: as a _list_, or as a series of _lines_. @@ -207,7 +214,7 @@ Each has been automatically assigned an id. The documents can now be inspected and edited, by means of the *Workbench*. [#importing-into-scopes-and-collections] -=== Importing into Scopes and Collections +=== Import into Scopes and Collections A _collection_ is a data container, defined on Couchbase Server, within a bucket whose type is either _Couchbase_ or _Ephemeral_. A _scope_ is a mechanism for the grouping of multiple collections. @@ -234,7 +241,7 @@ This can be validated by accessing the *Documents* panel, and specifying the app image::import-documents/documentsImportedIntoCollection.png[,720,align=left] [#importing-json-lines] -== Importing JSON Lines +== Import JSON Lines A _JSON Lines_ file is one that contains one or more JSON documents, each on a separate line. The following procedure demonstrates how to import such a file. @@ -279,7 +286,7 @@ image::import-documents/importedDocumentsWithEmployeeNumberID.png[,720,align=lef Thus, each document has been imported, with its `employeeNumber` value as the id of the document. [#importing-csv-and-tsv-files] -== Importing CSV and TSV Files +== Import CSV and TSV Files To import a CSV (_comma-separated values_) file, proceed as follows: @@ -318,7 +325,7 @@ davis 0009324 ---- [#handling-errors] -== Handling Errors +== Handle Errors If the contents of a file selected for import are inconsistent, Couchbase Server displays an error notification. For example: diff --git a/modules/manage/pages/manage-documents/manage-documents.adoc b/modules/manage/pages/manage-documents/manage-documents.adoc new file mode 100644 index 0000000000..efbf09a408 --- /dev/null +++ b/modules/manage/pages/manage-documents/manage-documents.adoc @@ -0,0 +1,117 @@ += Manage Documents +:imagesdir: ../../assets/images +:page-topic-type: guide +:page-pagination: +:description: Couchbase Web Console provides a graphical interface that you can use to view and edit documents. + +// FIXME: Needs further information about spreadsheet view, copying existing records, etc. + +[abstract] +{description} + +[.signpost] +image:ROOT:couchbase-logo.svg["Couchbase Server", 25.6] +This page is for Couchbase Server. +For Couchbase Capella, see xref:cloud:clusters:data-service/manage-documents.adoc[]. + +== Access Documents in the Couchbase Web Console + +You can use the *Documents* tool to view and manage documents in a database. + +To display the *Documents* tool, do one of the following: + +* In the Couchbase Web UI, click menu:Documents[]. + +* Alternatively, click menu:Buckets[], then click the *Documents* link for any bucket, scope, or collection. + +[#retrieve-documents] +== Retrieve Documents + +You can use the *Documents* tool to retrieve and view the individual documents contained within a bucket, scope, or collection on the database. +The retrieved documents are summarized in a table format, with a row for each retrieved document. +Document retrieval controls at the top of the summary control the retrieval and display of documents. + +The *Documents* tool has the following controls: + +* *Keyspace*: A set of three related drop-down menus: + +** A drop-down menu that displays the name of the bucket whose documents are shown. +You can use the drop-down menu to select from a list of buckets in the current database. + +** A drop-down menu that displays the name of the scope whose documents are shown. +The `_default` scope is the default. +You can use the drop-down menu to select from a list of all the scopes within the current bucket. + +** A drop-down menu that displays the name of the collection whose documents are shown. +The `_default` collection is the default. +You can use the drop-down menu to select from a list of all the collections within the current scope. + +* *Limit*: The maximum number of rows (documents) to retrieve and display at once. + +* *Offset*: The number of documents in the entire set of the current bucket that is skipped, before display begins. + +* *Document ID*: Accepts the ID value of a specific document. +Leave this field blank to retrieve documents based on *Limit* and *Offset*. + +* *show range*: Enables you to enter starting ID and ending ID values to specify a range of ID values. + +* *SQL++ WHERE*: Accepts a {sqlpp} query -- specifically, a WHERE clause which determines the subset of documents to show. + +To retrieve a set of documents: + +. Use the *Keyspace* drop-down menus to specify the location of the documents you want to view. +The set of retrieved documents is automatically updated based on your selections. + +. (Optional) Use *Limit*, *Offset*, *Document IT*, or *SQL++ WHERE* to specify a set of documents, then click btn:[Retrieve Docs] to retrieve the documents based on your configuration. + +== View and Edit Existing Documents + +To view and edit a document: + +. <> a set of documents. + +. Click on a document name, or click the pencil icon icon:pencil[] next to the document name. + ++ +Toggle the following tabs: + ++ +[#json-metadata,cols="1,2",options="header"] +|=== + +|Tab +|Description + +|*Data* +|Comprises a series of key-value pairs sometimes expressed as name-value pairs. +You can make modifications to key-values. + +|*Metadata* +|View the document's metadata. + +It's not possible to edit a document's metadata as Couchbase Server generates when the document is saved. +For more information, see xref:learn:data/data.adoc#metadata[document metadata]. + +|=== + +. Click btn:[Save] to save your changes. + +== Create Documents + +To create a document: + +. Click btn:[Add Document]. +. Enter the *Document ID* and edit the *Data* contents of the document. +. Click btn:[Save] to create the document. + +== Delete Documents + +To delete a document: + +. <> the document to display it in the results area. +. Click the Trash icon icon:trash[] next to the document name. +. Click btn:[Delete]. + +== Related Links + +To import a set of JSON documents or a CSV file, see xref:manage:import-documents/import-documents.adoc[]. diff --git a/modules/manage/pages/manage-indexes/manage-indexes.adoc b/modules/manage/pages/manage-indexes/manage-indexes.adoc index 5b4cdd8cc2..260656eab1 100644 --- a/modules/manage/pages/manage-indexes/manage-indexes.adoc +++ b/modules/manage/pages/manage-indexes/manage-indexes.adoc @@ -155,99 +155,7 @@ image::manage-indexes/indexInQueryWorkbench.png[,700,align=left] . Modify the {sqlpp} index-definition, as required. (Note that you cannot change the definition of the existing index, but you can create a new index with the modified definition.) -Immediately beneath the *Query Editor*, four buttons are displayed. -These can be used to test queries, and to determine how to design corresponding indexes; so as to maximize query-performance. -The buttons are as follows. - -==== Execute - -When left-clicked on, this executes the query that has been typed into the *Query Editor*. -For example, type the following query into the *Query Editor*: `SELECT icao FROM `travel-sample` WHERE name = "SeaPort Airlines";`. -This selects every `icao` key-value pair from the bucket `travel-sample`, where the host document also contains a `name` value that is `SeaPort Airlines`: - -image::manage-ui/queryEditorWithSelectQuery.png[,540,align=left] - -Left-click on the *Execute* button. - -image::manage-ui/leftClickOnExecuteButton.png[,110,align=left] - -Couchbase Web Console now provides feedback on the ongoing execution of the query, to the right of the buttons. -When query-execution has concluded, the results are duly displayed: - -image::manage-indexes/resultsOfqueryExecution.png[,520,align=left] - -Note also that the default appearance of the *Query* screen includes, at the upper right, a button labeled *query context*: - -image::manage-indexes/queryContextButton.png[,120,align=left] - -Left-click on the control at the right-hand side of the button, to reveal its pulldown menu. -This menu contains an entry for each bucket defined on the cluster: - -image::manage-indexes/bucketsButton.png[,120,align=left] - -Once a bucket has been selected, a further button (with pulldown-menu control) appears to the right, allowing selection of a scope within the selected bucket: - -image::manage-indexes/scopesButton.png[,240,align=left] - -Once a scope — for example, `inventory` — has been selected, queries can be entered into the *Query Editor* panel without explicit specification of bucket or scope being required: the bucket and scope for the query will be inferred from the pulldown-menu selections that have been made. -For example, the following expression performs a query on the documents in the `airline` collection; which itself resides within `inventory`, within `travel-sample`: - -image::manage-indexes/queryEditorWithShorterSelectQuery.png[,540,align=left] - -Note that buckets and scopes other than those currently selected by means of the pulldown menus can still be explicitly specified within the *Query Editor*, if required. - -==== Explain - -When left-clicked on, this provides an explanation of how query-execution proceeded: - -image::manage-ui/leftClickOnExplainButton.png[,110,align=left] - -The explanation is now displayed in the *Query Results* panel: - -image::manage-ui/queryExplanation.png[,720,align=left] - -This indicates the bucket and primary index scan that have been used in the query; as well as the filter applied, and the number of terms returned. - -==== Index Advisor - -When left-clicked on, this displays advice as to what index or indexes might be created, in order to improve the future performance of the query: - -image::manage-indexes/leftClickOnAdviseButton.png[,110,align=left] - -Advice is duly displayed in the *Query Results* panel: - -image::manage-indexes/queryAdviceDisplay2.png[,440,align=left] - -In this instance, the advice consists of two options; which are, respectively, the creation of a _covering_ index, and the creation of a regular index. -To create a covering index, left-click on the *Create and Build Covering Index* button: - -The following notification is now displayed: - -image::manage-ui/indexCreateWarning.png[,380,align=left] - -Left-click on *Continue*. -When index-creation is completed, the following success-message appears on the *Query* screen: - -image::manage-ui/createIndexSuccessMessage.png[,620,align=left] - -==== Run as TX - -The *Run as TX* button allows the specified query to be run transactionally, across multiple indexes. -For information on transactions, see xref:learn:data/transactions.adoc[Transactions]. - -Left-click on the *Run as TX* button, and the query is run as a transaction. -When the transaction is complete, status is displayed as follows: - -image::manage-indexes/transactionSuccessDisplay.png[,620,align=left] - -=== Index-Definition Support in Community Edition - -Note that in Couchbase Server _Community_ Edition, index-definition support is provided in a slightly different way. -The area immediately below the *Query Editor* appears as follows: - -image::manage-ui/ceIndexAdvisorLink.png[,320,align=left] - -The https://index-advisor.couchbase.com/indexadvisor/#1[External Query Advisor^] link takes the user to an external web-site, where the *Query Advisor* can be accessed and used. +For more information on using the Query Workbench, see xref:tools:query-workbench.adoc[]. [[drop-index]] === Drop the Index diff --git a/modules/manage/pages/manage-ui/manage-ui.adoc b/modules/manage/pages/manage-ui/manage-ui.adoc index 6fbb577b92..d0aa709d81 100644 --- a/modules/manage/pages/manage-ui/manage-ui.adoc +++ b/modules/manage/pages/manage-ui/manage-ui.adoc @@ -1,4 +1,5 @@ = Couchbase Web Console +:imagesdir: ../../assets/images :description: The features of Couchbase Server can be managed by means of Couchbase Web Console. // :page-aliases: c-sdk:ROOT:webui-cli-access.adoc,dotnet-sdk:ROOT:webui-cli-access.adoc,go-sdk:ROOT:webui-cli-access.adoc,java-sdk:ROOT:webui-cli-access.adoc,nodejs-sdk:ROOT:webui-cli-access.adoc,php-sdk:ROOT:webui-cli-access.adoc,python-sdk:ROOT:webui-cli-access.adoc, @@ -420,10 +421,10 @@ This brings up the *Documents* screen: image::manage-ui/documentsScreen.png[,700,align=left] This screen displays the documents contained within installed buckets. -The screen is currently blank, since no buckets have yet been installed. -The *Location* control permits a bucket to be selected from those installed, and for a scope and a collection within the bucket to be selected. +Initially, the screen is blank, since no buckets have yet been installed. +The *Keyspace* control permits a bucket to be selected from those installed, and for a scope and a collection within the bucket to be selected. Other controls allow specific documents to be displayed, according to configured parameters. -(For information on scopes and collections, see xref:learn:data/scopes-and-collections.adoc[Scopes and Collections]). +(For information on scopes and collections, see xref:learn:data/scopes-and-collections.adoc[Scopes and Collections].) The easiest way to install a bucket containing data is described in xref:manage:manage-settings/install-sample-buckets.adoc[Install Sample Buckets]. If the `travel-sample` is installed, the screen appears as follows: @@ -434,22 +435,10 @@ image::manage-ui/documentsScreenWithDocuments.png[,700,align=left] The internal content of documents can now be displayed and edited. The *Documents* screen presents two separate panels, which are accessible from the horizontal navigation bar along the top. -The *Workbench* panel is the default, currently displayed. -A full description of this panel and its contents is provided in xref:getting-started:look-at-the-results.adoc[Explore the Server Configuration], which is part of the the _Getting Started_ sequence. +The *Workbench* panel is displayed by default. +A full description of this panel and its contents is provided in xref:manage:manage-documents/manage-documents.adoc[], which is part of the Developer documentation. For an explanation of the *Import* panel, see xref:manage:import-documents/import-documents.adoc[Import Documents]. -To edit a document, left-click on a document-id that appears in the *id* column of the *Workbench* panel. -This brings up the *Edit Document* dialog, which features an interactive *Data* panel, whereby the document's contents can be edited: - -image::manage-ui/editDocumentData.png[,300,align=left] - -To examine the document's _metadata_, left-click on the *Metadata* button, at the upper right of the *Edit Document* dialog. -This duly brings up the *Metadata* panel (which is _read only_). - -image::manage-ui/editDocumentMetaData.png[,300,align=left] - -For instructions on installing a _sample bucket_, which contains documents that are ready to be inspected and experimented with, see xref:manage:manage-settings/install-sample-buckets.adoc[Install Sample Buckets]. - [#learning-about-documents] === Learn about Documents @@ -531,7 +520,7 @@ This brings up the *Full Text Search* screen: image::manage-ui/searchScreen.png[,700,align=left] The screen contains panels for Search _Indexes_ and _Aliases_. -Both panels are currently blank, since nothing has yet been created. +Initially, both panels are blank, since nothing has yet been created. Creation of both is explained in xref:fts:fts-searching-from-the-ui.adoc[Searching from the UI]. @@ -554,7 +543,7 @@ This brings up the *Analytics* screen: image::manage-ui/analyticsScreen.png[,700,align=left] The screen contains an *Analytics Query Editor*, and a panel for *Analytics Query Results*. -Both panels are currently blank. +Initially, both panels are blank. [#analytics-learn-and-manage] === Analytics: Learn and Manage @@ -574,7 +563,7 @@ This brings up the *Eventing* screen: [#console-eventing-screen] image::manage-ui/eventingScreen.png[,700,align=left] -The screen is currently blank, since no Eventing functions have yet been defined. +Initially, the screen is blank, since no Eventing functions have yet been defined. [#eventing-learn-and-manage] === Eventing: Learn and Manage @@ -592,7 +581,7 @@ This brings up the *Repositories* screen, of the Backup Service: image::manage-ui/backupScreen.png[,700,align=left] -The screen is currently blank, since no Backup-Service repositories have yet been defined. +Initially, the screen is blank, since no Backup-Service repositories have yet been defined. [#backup-learn-and-manage] === Backup: Learn and Manage @@ -614,7 +603,7 @@ This brings up the *Views* screen: [#console-views-screen] image::manage-ui/viewsScreen.png[,700,align=left] -The screen is currently blank, since no Views have yet been defined. +Initially, the screen is blank, since no Views have yet been defined. [#views-define-and-manage] === Views: Define and Manage diff --git a/modules/tools/pages/query-monitoring.adoc b/modules/tools/pages/query-monitoring.adoc index 7148549eb3..8a76f76591 100644 --- a/modules/tools/pages/query-monitoring.adoc +++ b/modules/tools/pages/query-monitoring.adoc @@ -1,28 +1,31 @@ -= Query Monitoring += Monitor Queries in the Couchbase Web Console +:imagesdir: ../assets/images :description: Couchbase Server provides a UI to monitor the current state of Query Service. [abstract] {description} -NOTE: Starting version 6.5, Query Monitoring is available in both Enterprise and Community Editions. +NOTE: Query Monitoring is available in both Enterprise and Community Editions. -From the [.ui]*Couchbase Web Console* > [.ui]*Query* > [.ui]*Query Monitor*, you can view the different types queries that are Active (currently running), Completed (recently run), and Prepared (aggregate statistics for prepared queries). +To display the Query Monitor, in the Couchbase Web Console, choose menu:Query[Query Monitor]. + +In the Query Monitor, you can view the different types queries that are Active (currently running), Completed (recently run), and Prepared (aggregate statistics for prepared queries). Statistics information for the query service is displayed at the bottom of the page. -Different information may be shown depending on the user’s access control role. +Different information may be shown, depending on your access control role. image::query-monitor.png[,820] The information about these queries is automatically updated every 5 seconds. -To freeze the display updates, click [.ui]*pause* located above the query table, next to the table heading. +To freeze the display updates, click btn:[pause] located above the query table, next to the table heading. When paused, a btn:[resume] button becomes available to let you restart automatic updates. You can sort the query information table by clicking on any of the column headers. [#active-queries] == Active Queries -By default, the [.ui]*Active Queries* page is displayed on the Query Monitoring screen. +By default, the [.ui]*Active Queries* page is displayed on the Query Monitor. The currently running queries are displayed, showing the details such as the query syntax, the query node address where the query is running, duration, request identification number, and the current state of the query. -Click the [.ui]*edit* link to edit that particular query in the [.ui]*Query Editor*. +Click the [.ui]*edit* link to edit that particular query in the xref:tools:query-workbench.adoc[Query Workbench]. To cancel a long running query, click the [.ui]*cancel* link located on the right side of the row. image::query-monitor-active.png[,820] @@ -30,7 +33,7 @@ image::query-monitor-active.png[,820] [#completed-queries] == Completed Queries -From the [.ui]*Couchbase Web Console > Query > Query Monitor >* click the btn:[Completed] button to view the table of completed queries whose runtime exceeded a system-specified threshold (default 1 second). +In the Query Monitor, click the btn:[Completed] button to view the table of completed queries whose runtime exceeded a system-specified threshold (default 1 second). Each row shows the query syntax, the query node address where the query was run, duration, the result count, the final state of the query (for example, completed, cancelled), and the timestamp when the query was run. image::query-monitor-completed.png[,820] @@ -38,10 +41,10 @@ image::query-monitor-completed.png[,820] [#prepared-queries] == Prepared Queries -From the [.ui]*Couchbase Web Console > Query > Query Monitor >* click the btn:[Prepared] button to view the prepared queries. +In the Query Monitor, click the btn:[Prepared] button to view the prepared queries. This page displays the aggregate statistics for prepared queries showing details such as query syntax, average elapsed time, number of uses, and the query node address. image::query-monitor-prepared.png[,820] For more information about system keyspaces and API for monitoring the operation of individual queries and query service nodes, see -xref:manage:monitor/monitoring-n1ql-query.adoc[Monitoring Queries]. +xref:manage:monitor/monitoring-n1ql-query.adoc[]. diff --git a/modules/tools/pages/query-workbench.adoc b/modules/tools/pages/query-workbench.adoc index a212b19ec7..f991ee4e77 100644 --- a/modules/tools/pages/query-workbench.adoc +++ b/modules/tools/pages/query-workbench.adoc @@ -35,6 +35,11 @@ endif::[] [abstract] {description} +[.signpost] +image:ROOT:couchbase-logo.svg["Couchbase Server", 25.6] +This page is for Couchbase Server. +For Couchbase Capella, see xref:cloud:clusters:query-service/query-workbench.adoc[]. + Using the [.ui]*Query Workbench*, you can conveniently explore data, create, edit, run, and save {sqlpp} queries, view and save query results, and explore the document structures in a keyspace -- all in a single window. Features of the Query Workbench include: @@ -55,14 +60,14 @@ If the Query service is _not_ running on the current node, it provides a link to The [.ui]*Query Workbench* consists of three working areas as shown in the following figure: * <> -* <> -- for data insights * <> -- for query results and plans +* <> -- for data insights .Query Workbench Areas image::query-workbench-areas.png["The Query Workbench with the Query Editor, Query Results, and Data Insights highlighted"] [#n1ql-editor] -== Using the Query Editor +== Use the Query Editor The Query Editor is where you enter and edit queries. @@ -171,164 +176,8 @@ For example, [.ui]*(151/152)* indicates that query #151 is currently shown, out Use the forward or back arrowhead icons icon:angle-left[] icon:angle-right[] to move to the next or previous query in the history. The forward arrowhead icon icon:angle-right[] can also create a new blank query when you are already at the end of the query history. -[#import-query] -== Import Data - -You can load a query from a file into the Query Editor, or load a set of queries from a file into the query history. - -. Click btn:[Import] to display the [.ui]*Import Query / History* window. -+ -image::query-workbench-import.png["The Import Query / History window",399] - -. Specify the data that you want to import: -+ -Query:: Loads the imported query into the Query Editor. -Query History:: Adds the imported queries to the end of the current query history. - -. Choose btn:[Next] to continue, or btn:[Cancel] to cancel. - -NOTE: The browser's Open File dialog is displayed. -Locate and open a text file or JSON file containing the data you want to import. - -Alternatively, you can drag and drop the file from the Desktop into the [.ui]*Query Editor* to a load a file. -The content of the file is added in the [.ui]*Query Editor* as a new query at the end of the history. - -[#export-query-or-results] -== Export Data - -You can export the query statement, query results, or query history. - -. Click btn:[Export] to display the [.ui]*Export Query / Data / History* window. -+ -image::query-workbench-export.png["The Export Query / Data / History window",399] - -. Specify the data that you want to export: -+ -Current query results (JSON):: Exports the results in the JSON file format. -Current results as tab-separated (text):: Exports the results as tab-separated text. -Query history (JSON):: Exports just the query history in the JSON file format. -Query history including results (JSON):: Exports the query history and results in the JSON format. -Current Query Statement:: Exports the current query statement in the .txt format. - -. In the [.ui]*Filename* box, specify the name of the file where data is to be saved. -The file extension is added automatically. -By default, the query is saved in the Downloads directory when using Firefox and Chrome browsers. - -. Choose btn:[Save] to export the data, or btn:[Cancel] to cancel. - -NOTE: When using Safari, clicking btn:[Save] loads the data into a new window. -You have to save the file manually using the menu:File[Save As] menu. - -[#query-preferences] -== Query Preferences - -To specify the query settings: - -. Click the cog icon icon:cog[] near the top right of the Query Workbench. -The [.ui]*Run-Time Preferences* window is displayed. -+ -image::query-workbench-preferences.png["The Run-Time Preferences window",399] - -. Define the following options: -+ -Collect query timings:: -The server records the timing for most operations in the query plan, showing the updated query plan with the query result. -Both graphical and textual query plans are updated with the timing information when the query is complete. - -Automatically infer bucket schemas:: -The query workbench automatically infers keyspace schemas to make field names available for autocompletion. -In some cases this may impact server performance. - -Automatically format queries before executing:: -The query workbench automatically formats queries with line breaks and indentation before executing. - -Use Cost-Based Optimizer:: -Specifies whether the {cost-based-optimizer}[cost-based optimizer] is enabled. - -Don't save query history:: -Disables auto-saving query history to local storage in your browser. -This is a consideration for shared machines. -When selected, any query history will be lost when you leave or refresh the query workbench. - -Max Parallelism:: -Specifies the maximum parallelism for the query. -If you do not specify, the cbq-engine uses its default value. -For more information, refer to the {max_parallelism}[max_parallelism] parameter. - -Scan Consistency:: -Specifies the consistency guarantee for index scanning. -Select one of the following options: -+ -* not_bounded -* request_plus -* statement_plus - -+ -+ -For more information, refer to the {scan_consistency}[scan_consistency] parameter. - -Positional Parameters:: -For prepared queries, this option allows you to specify values for any number of positional parameters. -Click the btn:[+] button to add new positional parameters, and the btn:[-] button to remove the parameters. -The parameters are automatically labelled as [.ui]*$1*, [.ui]*$2*, and so on. - -Named Parameters:: -For prepared queries, this option allows you to specify any number of named parameters. -Named parameters must start with the dollar sign ($) for use in prepared queries. -Otherwise, they are interpreted as parameters to the Query REST API. - -Query Timeout:: -Specifies the maximum time to spend on a query before timing out. -For more information, refer to the {timeout_req}[timeout] parameter. - -Transaction Timeout:: -Specifies the maximum time to spend on a transaction before timing out. -Only applies to {begin-transaction}[BEGIN TRANSACTION] statements, or statements executed with the btn:[Run as TX] button. -For more information, refer to the {txtimeout_req}[txtimeout] parameter. - -. Choose btn:[Save Preferences] to save the preferences, or btn:[Cancel] to cancel. - -[#bucket-analyzer] -== Viewing the Data Insights - -The *Explore Your Data* area displays all installed keyspaces in the cluster. -By default, when the Query Workbench is first loaded, it retrieves a list of available keyspaces from the cluster. -The [.ui]*Explore Your Data* area is automatically refreshed when keyspaces or indexes are added or removed. - -Click the double-headed arrow icon icon:expand-alt[] to enlarge the [.ui]*Explore Your Data* area -- the [.ui]*Query Editor* and [.ui]*Results* areas are resized accordingly. - -Within the [.ui]*Explore Your Data* area, buckets, scopes, and collections are displayed in a hierarchy, which you can expand or collapse. - -* To expand a heading within the hierarchy, click the heading, or click the rightward-pointing arrowhead icon:caret-right[] before the heading. - -* To collapse a heading within the hierarchy, click the heading again, or click the downward-pointing arrowhead icon:caret-down[] before the heading. - -Buckets are displayed at the top level of the hierarchy. -When you expand a bucket, the scopes within that bucket are displayed below it. -Similarly, when you expand a scope, the collections within that scope are displayed below it. - -The number of collections within the bucket is displayed to the right of the bucket heading. -Similarly, the number of documents within a collection is displayed to the right of the collection heading. -You may need to refresh the [.ui]*Explore Your Data* area to see these figures. footnote:[{doc-count}] - -image::query-workbench-insights-keyspaces.png["Hierarchy of bucket, scopes, and collections in the Data Insights area"] - -When you expand a collection, one or more headings are displayed showing the flavors (types) of document stored within that collection. -The percentage of documents of each flavor is shown to the right. -If there are any indexes within that collection, an [.ui]*Indexes* heading is also displayed, showing the indexes within the collection. - -You can expand any document flavor to view the schema for those documents: field names, types, and if you hover the mouse pointer over a field name, you can see example values for that field. -Keyspace analysis is based on the {sqlpp} {infer}[INFER] statement, which you can run manually to get more detailed results. - -You can expand the [.ui]*Indexes* heading to view the names and definitions of the indexes within the collection. - -image::query-workbench-insights-infer.png["Schema and indexes for a collection in the Data Insights area"] - -The information in the [.ui]*Explore Your Data* area is updated regularly, but it may take a short time to reflect recent changes. -To force the [.ui]*Explore Your Data* area to update, click btn:[Refresh]. - [#results] -== Viewing the Query Results +== View Query Results When you execute a query, the results are displayed in the [.ui]*Results* area. Since large result sets can take a long time to display, we recommend using the {limit}[LIMIT] clause as part of your query when appropriate. @@ -508,3 +357,171 @@ If there is no index advice for this query, the results area may display the one * `Click 'Advise' to generate query index advice` -- the Index Advisor has not yet been run. Refer to {recommendation-rules}[Recommendation Rules] for details of the rules that the index advisor uses to recommend an index. + +=== Index Advice in Community Edition + +[.labels] +[.edition]#{community}# + +Note that in Couchbase Server Community Edition, index advice is provided in a different way. +The area immediately below the *Query Editor* appears as follows: + +image::manage:manage-ui/ceIndexAdvisorLink.png["Execute button, Explain button, and External Query Advisor link",320] + +To get index advice, click the https://index-advisor.couchbase.com/indexadvisor/#1[External Query Advisor^] link to access the Couchbase *Index Advisor* web site. + +[#bucket-analyzer] +== View Data Insights + +The *Explore Your Data* area displays all installed keyspaces in the cluster. +By default, when the Query Workbench is first loaded, it retrieves a list of available keyspaces from the cluster. +The [.ui]*Explore Your Data* area is automatically refreshed when keyspaces or indexes are added or removed. + +Click the double-headed arrow icon icon:expand-alt[] to enlarge the [.ui]*Explore Your Data* area -- the [.ui]*Query Editor* and [.ui]*Results* areas are resized accordingly. + +Within the [.ui]*Explore Your Data* area, buckets, scopes, and collections are displayed in a hierarchy, which you can expand or collapse. + +* To expand a heading within the hierarchy, click the heading, or click the rightward-pointing arrowhead icon:caret-right[] before the heading. + +* To collapse a heading within the hierarchy, click the heading again, or click the downward-pointing arrowhead icon:caret-down[] before the heading. + +Buckets are displayed at the top level of the hierarchy. +When you expand a bucket, the scopes within that bucket are displayed below it. +Similarly, when you expand a scope, the collections within that scope are displayed below it. + +The number of collections within the bucket is displayed to the right of the bucket heading. +Similarly, the number of documents within a collection is displayed to the right of the collection heading. +You may need to refresh the [.ui]*Explore Your Data* area to see these figures. footnote:[{doc-count}] + +image::query-workbench-insights-keyspaces.png["Hierarchy of bucket, scopes, and collections in the Data Insights area"] + +When you expand a collection, one or more headings are displayed showing the flavors (types) of document stored within that collection. +The percentage of documents of each flavor is shown to the right. +If there are any indexes within that collection, an [.ui]*Indexes* heading is also displayed, showing the indexes within the collection. + +You can expand any document flavor to view the schema for those documents: field names, types, and if you hover the mouse pointer over a field name, you can see example values for that field. +Keyspace analysis is based on the {sqlpp} {infer}[INFER] statement, which you can run manually to get more detailed results. + +You can expand the [.ui]*Indexes* heading to view the names and definitions of the indexes within the collection. + +image::query-workbench-insights-infer.png["Schema and indexes for a collection in the Data Insights area"] + +The information in the [.ui]*Explore Your Data* area is updated regularly, but it may take a short time to reflect recent changes. +To force the [.ui]*Explore Your Data* area to update, click btn:[Refresh]. + +[#import-query] +== Import Data + +You can load a query from a file into the Query Editor, or load a set of queries from a file into the query history. + +. Click btn:[Import] to display the [.ui]*Import Query / History* window. ++ +image::query-workbench-import.png["The Import Query / History window",399] + +. Specify the data that you want to import: ++ +Query:: Loads the imported query into the Query Editor. +Query History:: Adds the imported queries to the end of the current query history. + +. Choose btn:[Next] to continue, or btn:[Cancel] to cancel. + +NOTE: The browser's Open File dialog is displayed. +Locate and open a text file or JSON file containing the data you want to import. + +Alternatively, you can drag and drop the file from the Desktop into the [.ui]*Query Editor* to a load a file. +The content of the file is added in the [.ui]*Query Editor* as a new query at the end of the history. + +[#export-query-or-results] +== Export Data + +You can export the query statement, query results, or query history. + +. Click btn:[Export] to display the [.ui]*Export Query / Data / History* window. ++ +image::query-workbench-export.png["The Export Query / Data / History window",399] + +. Specify the data that you want to export: ++ +Current query results (JSON):: Exports the results in the JSON file format. +Current results as tab-separated (text):: Exports the results as tab-separated text. +Query history (JSON):: Exports just the query history in the JSON file format. +Query history including results (JSON):: Exports the query history and results in the JSON format. +Current Query Statement:: Exports the current query statement in the .txt format. + +. In the [.ui]*Filename* box, specify the name of the file where data is to be saved. +The file extension is added automatically. +By default, the query is saved in the Downloads directory when using Firefox and Chrome browsers. + +. Choose btn:[Save] to export the data, or btn:[Cancel] to cancel. + +NOTE: When using Safari, clicking btn:[Save] loads the data into a new window. +You have to save the file manually using the menu:File[Save As] menu. + +[#query-preferences] +== Query Preferences + +To specify the query settings: + +. Click the cog icon icon:cog[] near the top right of the Query Workbench. +The [.ui]*Run-Time Preferences* window is displayed. ++ +image::query-workbench-preferences.png["The Run-Time Preferences window",399] + +. Define the following options: ++ +Collect query timings:: +The server records the timing for most operations in the query plan, showing the updated query plan with the query result. +Both graphical and textual query plans are updated with the timing information when the query is complete. + +Automatically infer bucket schemas:: +The query workbench automatically infers keyspace schemas to make field names available for autocompletion. +In some cases this may impact server performance. + +Automatically format queries before executing:: +The query workbench automatically formats queries with line breaks and indentation before executing. + +Use Cost-Based Optimizer:: +Specifies whether the {cost-based-optimizer}[cost-based optimizer] is enabled. + +Don't save query history:: +Disables auto-saving query history to local storage in your browser. +This is a consideration for shared machines. +When selected, any query history will be lost when you leave or refresh the query workbench. + +Max Parallelism:: +Specifies the maximum parallelism for the query. +If you do not specify, the cbq-engine uses its default value. +For more information, refer to the {max_parallelism}[max_parallelism] parameter. + +Scan Consistency:: +Specifies the consistency guarantee for index scanning. +Select one of the following options: ++ +* not_bounded +* request_plus +* statement_plus + ++ ++ +For more information, refer to the {scan_consistency}[scan_consistency] parameter. + +Positional Parameters:: +For prepared queries, this option allows you to specify values for any number of positional parameters. +Click the btn:[+] button to add new positional parameters, and the btn:[-] button to remove the parameters. +The parameters are automatically labelled as [.ui]*$1*, [.ui]*$2*, and so on. + +Named Parameters:: +For prepared queries, this option allows you to specify any number of named parameters. +Named parameters must start with the dollar sign ($) for use in prepared queries. +Otherwise, they are interpreted as parameters to the Query REST API. + +Query Timeout:: +Specifies the maximum time to spend on a query before timing out. +For more information, refer to the {timeout_req}[timeout] parameter. + +Transaction Timeout:: +Specifies the maximum time to spend on a transaction before timing out. +Only applies to {begin-transaction}[BEGIN TRANSACTION] statements, or statements executed with the btn:[Run as TX] button. +For more information, refer to the {txtimeout_req}[txtimeout] parameter. + +. Choose btn:[Save Preferences] to save the preferences, or btn:[Cancel] to cancel.