From 7a76399e9d7de7f69930431d2ca8ea06c7da5417 Mon Sep 17 00:00:00 2001 From: bugaosuni59 <598586484@qq.com> Date: Fri, 23 Apr 2021 00:15:50 +0800 Subject: [PATCH] update the JSON-RPC API document: (#1194) 1.add some connection and query API 2.add some use case for some useful API Co-authored-by: Xianlong Wang --- docs/guide/jsonrpc_protocol.md | 1032 ++++++++++++++++++++++++++------ 1 file changed, 855 insertions(+), 177 deletions(-) diff --git a/docs/guide/jsonrpc_protocol.md b/docs/guide/jsonrpc_protocol.md index 89722305..423f8c0a 100644 --- a/docs/guide/jsonrpc_protocol.md +++ b/docs/guide/jsonrpc_protocol.md @@ -5,7 +5,7 @@ The API provides easily consumable operations that allow simple integration into ## Launching the Host Process -From your host process, launch `Microsoft.SqlTools.ServiceLayer(.exe)` using an host-native process +From your host process, launch `Microsoft.SqlTools.ServiceLayer(.exe)` using an host-native process API that allows you to read and write this process' standard in/out streams. All communication with the host process occurs via this channel. @@ -19,52 +19,70 @@ which contains all of the user's SQL script files for a given project. ## Messages Overview -The SQL Tools Service implements portions of the +The SQL Tools Service implements portions of the [language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md) -defined by VS Code. Some portions of this protocol reference have been duplicated here for -convenience. +defined by VS Code. Some portions of this protocol reference have been duplicated here for +convenience. It additionally implements several other API to provide database management services such as connection management or query execution. -This document provides the protocol specification for all the service's JSON-RPC APIs. +This document provides the protocol specification for all the service's JSON-RPC APIs and some useful events. + ### Connection Management -* :leftwards_arrow_with_hook: [connection/connect](#connect_connect) +* :leftwards_arrow_with_hook: [connection/connect](#connection_connect) * :leftwards_arrow_with_hook: [connection/cancelconnect](#connect_cancelconnect) -* :arrow_right: [connection/connectionchanged](#connection_connectionchanged) -* :arrow_right: [connection/complete](#connection_complete) * :arrow_right: [connection/disconnect](#connection_disconnect) +* :arrow_right: [connection/listdatabases](#connection_listdatabases) +* :arrow_right: [connection/changedatabase](#connection_changedatabase) +* :arrow_right: [connection/getconnectionstring](#connection_getconnectionstring) +* :arrow_right: [connection/buildconnectioninfo](#connection_buildconnectioninfo) +* :arrow_left: [connection/connectionchanged](#connection_connectionchanged) +* :arrow_left: [connection/complete](#connection_complete) + ### Query Execution -* :leftwards_arrow_with_hook: [query/execute](#query_execute) +* :leftwards_arrow_with_hook: [query/executeString](#query_executeString) +* :leftwards_arrow_with_hook: [query/executeDocumentSelection](#query_executeDocumentSelection) +* :leftwards_arrow_with_hook: [query/executedocumentstatement](#query_executedocumentstatement) * :leftwards_arrow_with_hook: [query/subset](#query_subset) +* :leftwards_arrow_with_hook: [query/dispose](#query_dispose) +* :leftwards_arrow_with_hook: [query/cancel](#query_cancel) * :leftwards_arrow_with_hook: [query/saveCsv](#query_saveCsv) +* :leftwards_arrow_with_hook: [query/saveExcel](#query_saveExcel) * :leftwards_arrow_with_hook: [query/saveJson](#query_saveJson) +* :leftwards_arrow_with_hook: [query/saveXml](#query_saveXml) +* :leftwards_arrow_with_hook: [query/executionPlan](#query_executionPlan) +* :leftwards_arrow_with_hook: [query/simpleexecute](#query_simpleexecute) +* :leftwards_arrow_with_hook: [query/setexecutionoptions](#query_setexecutionoptions) +* :arrow_left: [query/message](#query_message) +* :arrow_left: [query/complete](#query_complete) + ### Language Service Protocol -Documentation for the Language Service Protocol is available at +Documentation for the Language Service Protocol is available at [language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md). The SQL Tools Service implements the following portion Language Service Protocol. -* :leftwards_arrow_with_hook: [initialize](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#initialize) -* :leftwards_arrow_with_hook: [shutdown](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#shutdown) -* :arrow_right: [exit](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#exit) -* :arrow_right: [workspace/didChangeConfiguration](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#workspace_didChangeConfiguration) -* :arrow_right: [workspace/didChangeWatchedFiles](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#workspace_didChangeWatchedFiles) -* :arrow_left: [textDocument/publishDiagnostics](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_publishDiagnostics) -* :arrow_right: [textDocument/didChange](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didChange) -* :arrow_right: [textDocument/didClose](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didClose) -* :arrow_right: [textDocument/didOpen](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didOpen) -* :arrow_right: [textDocument/didSave](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didSave) -* :leftwards_arrow_with_hook: [textDocument/completion](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_completion) -* :leftwards_arrow_with_hook: [completionItem/resolve](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#completionItem_resolve) -* :leftwards_arrow_with_hook: [textDocument/hover](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_hover) -* :leftwards_arrow_with_hook: [textDocument/signatureHelp](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_signatureHelp) -* :leftwards_arrow_with_hook: [textDocument/references](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_references) -* :leftwards_arrow_with_hook: [textDocument/definition](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_definition) +* :leftwards_arrow_with_hook: [initialize](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#initialize) +* :leftwards_arrow_with_hook: [shutdown](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#shutdown) +* :arrow_right: [exit](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#exit) +* :arrow_right: [workspace/didChangeConfiguration](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#workspace_didChangeConfiguration) +* :arrow_right: [workspace/didChangeWatchedFiles](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#workspace_didChangeWatchedFiles) +* :arrow_left: [textDocument/publishDiagnostics](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_publishDiagnostics) +* :arrow_right: [textDocument/didChange](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didChange) +* :arrow_right: [textDocument/didClose](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didClose) +* :arrow_right: [textDocument/didOpen](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didOpen) +* :arrow_right: [textDocument/didSave](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_didSave) +* :leftwards_arrow_with_hook: [textDocument/completion](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_completion) +* :leftwards_arrow_with_hook: [completionItem/resolve](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#completionItem_resolve) +* :leftwards_arrow_with_hook: [textDocument/hover](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_hover) +* :leftwards_arrow_with_hook: [textDocument/signatureHelp](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_signatureHelp) +* :leftwards_arrow_with_hook: [textDocument/references](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_references) +* :leftwards_arrow_with_hook: [textDocument/definition](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#textDocument_definition) ### Language Service Protocol Extensions @@ -131,9 +149,9 @@ separated by a '\r\n'. The header part consists of header fields. Each header field is comprised of a name and a value, separated by ': ' (a colon and a space). -Each header field is terminated by '\r\n'. +Each header field is terminated by '\r\n'. Considering the last header field and the overall header itself are each terminated with '\r\n', -and that at least one header is mandatory, this means that two '\r\n' sequences always +and that at least one header is mandatory, this means that two '\r\n' sequences always immediately precede the content part of a message. Currently the following header fields are supported: @@ -147,7 +165,7 @@ The header part is encoded using the 'ascii' encoding. This includes the '\r\n' ### Content Part -Contains the actual content of the message. The content part of a message uses [JSON-RPC](http://www.jsonrpc.org/) to describe requests, responses and notifications. The content part is encoded using the charset provided in the Content-Type field. It defaults to 'utf8', which is the only encoding supported right now. +Contains the actual content of the message. The content part of a message uses [JSON-RPC](http://www.jsonrpc.org/) to describe requests, responses and notifications. The content part is encoded using the charset provided in the Content-Type field. It defaults to 'utf8', which is the only encoding supported right now. ### Example: @@ -157,7 +175,7 @@ Content-Length: ...\r\n { "jsonrpc": "2.0", "id": 1, - "method": "textDocument/didOpen", + "method": "textDocument/didOpen", "params": { ... } @@ -176,7 +194,7 @@ interface Message { jsonrpc: string; } ``` -#### RequestMessage +#### RequestMessage A request message to describe a request between the client and the server. Every processed request must send a response back to the sender of the request. @@ -272,7 +290,7 @@ interface NotificationMessage extends Message { ## Example JSON-RPC Message Format -See the [language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md) +See the [language service protocol](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md) for more details on the protocol formats for these Language Service events. Below is an example of the JSON-RPC message format for the `textDocument/didChange` message. @@ -315,78 +333,240 @@ No response is needed for this command. # Database Management Protocol -The follow section describes the message protocol format for the common database management -functionality provided by the SQL Tools Service. The message formats are described as +The follow section describes the message protocol format for the common database management +functionality provided by the SQL Tools Service. The message formats are described as C# classes. These classes are packaged inside the common message structures documented above and serialized to JSON using JSON.Net. ## Connection Management + ### `connection/connect` Establish a connection to a database server. #### Request -```typescript +```csharp public class ConnectParams { /// /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace - /// or a virtual file representing an object in a database. + /// or a virtual file representing an object in a database. /// - public string OwnerUri { get; set; } + public string OwnerUri { get; set; } + /// /// Contains the required parameters to initialize a connection to a database. /// A connection will identified by its server name, database name and user name. - /// This may be changed in the future to support multiple connections with different + /// This may be changed in the future to support multiple connections with different /// connection properties to the same database. /// public ConnectionDetails Connection { get; set; } + + /// + /// The type of this connection. By default, this is set to ConnectionType.Default. + /// + public string Type { get; set; } = ConnectionType.Default; + + /// + /// The porpose of the connection to keep track of open connections + /// + public string Purpose { get; set; } = ConnectionType.GeneralConnection; } ``` +#### Request Case +```json +Content-length: {the length of the JSON below} + +{ + "jsonrpc": "2.0", + "id": 1, + "method": "connection/connect", + "params": { + "ownerUri": "{An id or a filename, which is binding with this connection}", + "connection": { + "serverName": "{your server name}", + "userName": "{your user name}", + "password": "{your password}", + "databaseName": "{your database name}" + } + } +} +``` + #### Response -```typescript +```csharp bool ``` + ### `connect/cancelconnect` Cancel an active connection request. #### Request -```typescript +```csharp public class CancelConnectParams { /// /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace - /// or a virtual file representing an object in a database. + /// or a virtual file representing an object in a database. /// - public string OwnerUri { get; set; } + public string OwnerUri { get; set; } + + /// + /// The type of connection we are trying to cancel + /// + public string Type { get; set; } = ConnectionType.Default; } ``` #### Response -```typescript +```csharp bool ``` + +### `connection/disconnect` + +Disconnect the connection specified in the request. + +#### Request + +```csharp + public class DisconnectParams + { + /// + /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace + /// or a virtual file representing an object in a database. + /// + public string OwnerUri { get; set; } + + /// + /// The type of connection we are disconnecting. If null, we will disconnect all connections. + /// connections. + /// + public string Type { get; set; } + } +``` + +#### Response + +```csharp + bool +``` + +### `connection/listdatabases` + +Return a list of databases on the server associated with the active connection. + +#### Request + +```csharp + public class ListDatabasesParams + { + /// + /// URI of the owner of the connection requesting the list of databases. + /// + public string OwnerUri { get; set; } + + /// + /// whether to include the details of the databases. + /// + public bool? IncludeDetails { get; set; } + } +``` + +#### Response + +```csharp + public class ListDatabasesResponse + { + /// + /// Gets or sets the list of database names. + /// + public string[] DatabaseNames { get; set; } + } +``` + +### `connection/changedatabase` + +Change the database for a connection. + +#### Request +```csharp + public class ChangeDatabaseParams + { + /// + /// URI of the owner of the connection requesting the list of databases. + /// + public string OwnerUri { get; set; } + + /// + /// The database to change to + /// + public string NewDatabase { get; set; } + } +``` +#### Response +```csharp + bool +``` + +### `connection/getconnectionstring` + +Get a connection string for the provided connection. + +#### Request +```csharp + public class GetConnectionStringParams + { + /// + /// URI of the owner of the connection + /// + public string OwnerUri { get; set; } + + /// + /// Indicates whether the password should be return in the connection string + /// + public bool IncludePassword { get; set; } + } +``` +#### Response +```csharp + string +``` + +### `connection/buildconnectioninfo` + +Serialize a connection string. + +#### Request +```csharp + string +``` +#### Response +```csharp + ConnectionDetails +``` + ### `connection/connectionchanged` -Connection changed notification +Connection changed notification. #### Request -```typescript +```csharp public class ConnectionChangedParams { /// /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace - /// or a virtual file representing an object in a database. + /// or a virtual file representing an object in a database. /// public string OwnerUri { get; set; } /// @@ -402,12 +582,12 @@ Connection complete event. #### Request -```typescript +```csharp public class ConnectionCompleteParams { /// /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace - /// or a virtual file representing an object in a database. + /// or a virtual file representing an object in a database. /// public string OwnerUri { get; set; } @@ -440,103 +620,122 @@ Connection complete event. /// Gets or sets the actual Connection established, including Database Name /// public ConnectionSummary ConnectionSummary { get; set; } - } -``` -### `connection/disconnect` - -Disconnect the connection specified in the request. - -#### Request - -```typescript - public class DisconnectParams - { /// - /// A URI identifying the owner of the connection. This will most commonly be a file in the workspace - /// or a virtual file representing an object in a database. + /// The type of connection that this notification is for /// - public string OwnerUri { get; set; } + public string Type { get; set; } = ConnectionType.Default; } ``` -#### Response - -```typescript - bool -``` - -### `connection/listdatabases` - -Return a list of databases on the server associated with the active connection. - -#### Request - -```typescript - public class ListDatabasesParams - { - /// - /// URI of the owner of the connection requesting the list of databases. - /// - public string OwnerUri { get; set; } - } -``` - -#### Response - -```typescript - public class ListDatabasesResponse - { - /// - /// Gets or sets the list of database names. - /// - public string[] DatabaseNames { get; set; } - } -``` ## Query Execution -### `query/execute` +### `query/executeString` Execute a SQL script. #### Request +```csharp + public class ExecuteStringParams : ExecuteRequestParamsBase + { + /// + /// The query to execute + /// + public string Query { get; set; } + } + public abstract class ExecuteRequestParamsBase + { + /// + /// URI for the editor that is asking for the query execute + /// + public string OwnerUri { get; set; } -```typescript - public class QueryExecuteParams + /// + /// Execution plan options + /// + public ExecutionPlanOptions ExecutionPlanOptions { get; set; } + + /// + /// Flag to get full column schema via additional queries. + /// + public bool GetFullColumnSchema { get; set; } + } +``` + +#### Response + +This response has no message but only the JSON-RPC version and the request-id. + +```csharp + public class ExecuteRequestResult + { + } +``` + +### `query/executeDocumentSelection` + +Execute a selection of a document in the workspace service. + +#### Request +```csharp + public class ExecuteDocumentSelectionParams : ExecuteRequestParamsBase { /// /// The selection from the document /// public SelectionData QuerySelection { get; set; } - - /// - /// URI for the editor that is asking for the query execute - /// - public string OwnerUri { get; set; } } ``` - #### Response -```typescript - public class QueryExecuteResult +This response has no message but only the JSON-RPC version and the request-id. + +```csharp + public class ExecuteRequestResult { - /// - /// Informational messages from the query runner. Optional, can be set to null. - /// - public string Messages { get; set; } } ``` + +### `query/executedocumentstatement` + +Execute a selection of a document in the workspace service. + +#### Request +```csharp + public class ExecuteDocumentStatementParams : ExecuteRequestParamsBase + { + /// + /// Line in the document for the location of the SQL statement + /// + public int Line { get; set; } + + /// + /// Column in the document for the location of the SQL statement + /// + public int Column { get; set; } + } +``` +#### Response + +This response has no message but only the JSON-RPC version and the request-id. + +```csharp + public class ExecuteRequestResult + { + } +``` + + ### `query/subset` Retrieve a subset of a query results. #### Request -```typescript - public class QueryExecuteSubsetParams +```csharp + public class SubsetParams { /// /// URI for the file that owns the query to look up the results for @@ -557,10 +756,10 @@ Retrieve a subset of a query results. /// Beginning index of the rows to return from the selected resultset. This index will be /// included in the results. /// - public int RowsStartIndex { get; set; } + public long RowsStartIndex { get; set; } /// - /// Number of rows to include in the result of this request. If the number of the rows + /// Number of rows to include in the result of this request. If the number of the rows /// exceeds the number of rows available after the start index, all available rows after /// the start index will be returned. /// @@ -568,21 +767,127 @@ Retrieve a subset of a query results. } ``` +#### Request Case + +```json +Content-length: {the length of the JSON below} + +{ + "jsonrpc": "2.0", + "id": "1", + "method": "query/subset", + "params": { + "ownerUri": "{the owner uri}", + "batchIndex": 0, + "resultSetIndex": 0, + "rowsStartIndex": 0, + "rowsCount": 1 + } +} +``` + #### Response -```typescript - public class QueryExecuteSubsetResult +```csharp + public class SubsetResult { - /// - /// Subset request error messages. Optional, can be set to null to indicate no errors - /// - public string Message { get; set; } - /// /// The requested subset of results. Optional, can be set to null to indicate an error /// public ResultSetSubset ResultSubset { get; set; } } + + public class ResultSetSubset + { + /// + /// The number of rows returned from result set, useful for determining if less rows were + /// returned than requested. + /// + public int RowCount { get; set; } + + /// + /// 2D array of the cell values requested from result set + /// + public DbCellValue[][] Rows { get; set; } + } +``` + + +#### Response Case + +```json +Content-length: {the length of the JSON below} + +{ + "jsonrpc": "2.0", + "id": "1", + "result": { + "resultSubset": { + "rowCount": 1, + "rows": [ + [ + { + "displayValue": "Alice", + "isNull": false, + "invariantCultureDisplayValue": null, + "rowId": 0 + }, + { + "displayValue": "Bob", + "isNull": false, + "invariantCultureDisplayValue": null, + "rowId": 0 + } + ] + ] + } + } +} +``` + + +### `query/dispose` + +Dispose the query for the owner uri. + +#### Request +```csharp + public class QueryDisposeParams + { + public string OwnerUri { get; set; } + } +``` +#### Response + +This response has no message but only the JSON-RPC version and the request-id. + +```csharp + public class QueryDisposeResult + { + } +``` + +### `query/cancel` + +Cancel the query in progress for the owner uri. + +#### Request +```csharp + public class QueryCancelParams + { + public string OwnerUri { get; set; } + } +``` +#### Response +```csharp + public class QueryCancelResult + { + /// + /// Any error messages that occurred during disposing the result set. Optional, can be set + /// to null if there were no errors. + /// + public string Messages { get; set; } + } ``` ### `query/saveCsv` @@ -591,7 +896,35 @@ Save a resultset as CSV to a file. #### Request -```typescript +```csharp + public class SaveResultsAsCsvRequestParams: SaveResultsRequestParams + { + /// + /// Include headers of columns in CSV + /// + public bool IncludeHeaders { get; set; } + + /// + /// Delimiter for separating data items in CSV + /// + public string Delimiter { get; set; } + + /// + /// either CR, CRLF or LF to seperate rows in CSV + /// + public string LineSeperator { get; set; } + + /// + /// Text identifier for alphanumeric columns in CSV + /// + public string TextIdentifier { get; set; } + + /// + /// Encoding of the CSV file + /// + public string Encoding { get; set; } + } + public class SaveResultsRequestParams { /// @@ -649,19 +982,11 @@ Save a resultset as CSV to a file. } } } - - public class SaveResultsAsCsvRequestParams: SaveResultsRequestParams - { - /// - /// Include headers of columns in CSV - /// - public bool IncludeHeaders { get; set; } - } ``` #### Response -```typescript +```csharp public class SaveResultRequestResult { /// @@ -671,19 +996,102 @@ Save a resultset as CSV to a file. } ``` +### `query/saveExcel` + +Save a resultset to a file in Excel format. + +#### Request + +```csharp + public class SaveResultsAsExcelRequestParams : SaveResultsRequestParams + { + /// + /// Include headers of columns in Excel + /// + public bool IncludeHeaders { get; set; } + } +``` +#### Response + +```csharp + public class SaveResultRequestResult + { + /// + /// Error messages for saving to file. + /// + public string Messages { get; set; } + } +``` + + + + ### `query/saveJson` Save a resultset as JSON to a file. #### Request -```typescript - public class SaveResultsRequestParams +```csharp + public class SaveResultsAsJsonRequestParams: SaveResultsRequestParams + { + } +``` + +#### Response + +```csharp + public class SaveResultRequestResult { /// - /// The path of the file to save results in + /// Error messages for saving to file. /// - public string FilePath { get; set; } + public string Messages { get; set; } + } +``` + +### `query/saveXml` + +Save a resultset to a file in XML format. + +#### Request +```csharp + public class SaveResultsAsXmlRequestParams: SaveResultsRequestParams + { + /// + /// Formatting of the XML file + /// + public bool Formatted { get; set; } + + /// + /// Encoding of the XML file + /// + public string Encoding { get; set; } + } +``` +#### Response +```csharp + public class SaveResultRequestResult + { + /// + /// Error messages for saving to file. + /// + public string Messages { get; set; } + } +``` + +### `query/executionPlan` + +Get an execution plan + +#### Request +```csharp + public class QueryExecutionPlanParams + { + /// + /// URI for the file that owns the query to look up the results for + /// + public string OwnerUri { get; set; } /// /// Index of the batch to get the results from @@ -695,58 +1103,328 @@ Save a resultset as JSON to a file. /// public int ResultSetIndex { get; set; } + } +``` +#### Response +```csharp + public class QueryExecutionPlanResult + { /// - /// URI for the editor that called save results + /// The requested execution plan. Optional, can be set to null to indicate an error + /// + public ExecutionPlan ExecutionPlan { get; set; } + } + public class ExecutionPlan + { + /// + /// The format of the execution plan + /// + public string Format { get; set; } + + /// + /// The execution plan content + /// + public string Content { get; set; } + } +``` + + +### `query/simpleexecute` + +Execute a string. + +#### Request +```csharp + public class SimpleExecuteParams + { + /// + /// The string to execute + /// + public string QueryString { get; set; } + + /// + /// The owneruri to get connection from /// public string OwnerUri { get; set; } - - /// - /// Start index of the selected rows (inclusive) - /// - public int? RowStartIndex { get; set; } - - /// - /// End index of the selected rows (inclusive) - /// - public int? RowEndIndex { get; set; } - - /// - /// Start index of the selected columns (inclusive) - /// - /// - public int? ColumnStartIndex { get; set; } - - /// - /// End index of the selected columns (inclusive) - /// - /// - public int? ColumnEndIndex { get; set; } - - /// - /// Check if request is a subset of result set or whole result set - /// - /// - internal bool IsSaveSelection - { - get - { - return ColumnStartIndex.HasValue && ColumnEndIndex.HasValue - && RowStartIndex.HasValue && RowEndIndex.HasValue; - } - } } ``` #### Response +```csharp + public class SimpleExecuteResult + { -```typescript - public class SaveResultRequestResult + /// + /// The number of rows that was returned with the resultset + /// + public long RowCount { get; set; } + + /// + /// Details about the columns that are provided as solutions + /// + public DbColumnWrapper[] ColumnInfo { get; set; } + + /// + /// 2D array of the cell values requested from result set + /// + public DbCellValue[][] Rows { get; set; } + } +``` + +### `query/setexecutionoptions` + +Set query execution options. + +#### Request +```csharp + public class QueryExecutionOptionsParams + { + public string OwnerUri { get; set; } + + public QueryExecutionSettings Options { get; set; } + } +``` +#### Response +```csharp + bool +``` + + +### `query/message` + +Send the query message. + +#### Request +```csharp + public class MessageParams { /// - /// Error messages for saving to file. + /// URI for the editor that owns the query /// - public string Messages { get; set; } + public string OwnerUri { get; set; } + + /// + /// The message that is being returned + /// + public ResultMessage Message { get; set; } } + public class ResultMessage + { + /// + /// ID of the batch that generated this message. If null, this message + /// was not generated as part of a batch + /// + public int? BatchId { get; set; } + + /// + /// Whether or not this message is an error + /// + public bool IsError { get; set; } + + /// + /// Timestamp of the message + /// Stored in UTC ISO 8601 format; should be localized before displaying to any user + /// + public string Time { get; set; } + + /// + /// Message contents + /// + public string Message { get; set; } + + /// + /// Constructor with default "Now" time + /// + public ResultMessage(string message, bool isError, int? batchId) + { + BatchId = batchId; + IsError = isError; + Time = DateTime.Now.ToString("o"); + Message = message; + } + + /// + /// Default constructor, used for deserializing JSON RPC only + /// + public ResultMessage() + { + } + public override string ToString() => $"Message on Batch Id:'{BatchId}', IsError:'{IsError}', Message:'{Message}'"; + } +``` + +#### Request Case + +```json +Content-length: {the length of the JSON below} + +{ + "jsonrpc": "2.0", + "method": "query/message", + "params": { + "ownerUri": "{the owner uri}", + "message": { + "batchId": 0, + "isError": false, + "time": "{timestamp}", + "message": "(1 rows affected)" + } + } +} +``` + +### `query/complete` + +Send the query summaries including the batch summaries and the result set summaries. + +#### Request +```csharp + public class QueryCompleteParams + { + /// + /// URI for the editor that owns the query + /// + public string OwnerUri { get; set; } + + /// + /// Summaries of the result sets that were returned with the query + /// + public BatchSummary[] BatchSummaries { get; set; } + } + + public class BatchSummary + { + /// + /// Localized timestamp for how long it took for the execution to complete + /// + public string ExecutionElapsed { get; set; } + + /// + /// Localized timestamp for when the execution completed. + /// + public string ExecutionEnd { get; set; } + + /// + /// Localized timestamp for when the execution started. + /// + public string ExecutionStart { get; set; } + + /// + /// Whether or not the batch encountered an error that halted execution + /// + public bool HasError { get; set; } + + /// + /// The ID of the result set within the query results + /// + public int Id { get; set; } + + /// + /// The selection from the file for this batch + /// + public SelectionData Selection { get; set; } + + /// + /// The summaries of the result sets inside the batch + /// + public ResultSetSummary[] ResultSetSummaries { get; set; } + + /// + /// The special action of the batch + /// + public SpecialAction SpecialAction { get; set; } + + public override string ToString() => $"Batch Id:'{Id}', Elapsed:'{ExecutionElapsed}', HasError:'{HasError}'"; + } + + public class ResultSetSummary + { + /// + /// The ID of the result set within the batch results + /// + public int Id { get; set; } + + /// + /// The ID of the batch set within the query + /// + public int BatchId { get; set; } + + /// + /// The number of rows that are available for the resultset thus far + /// + public long RowCount { get; set; } + + /// + /// If true it indicates that all rows have been fetched and the RowCount being sent across is final for this ResultSet + /// + public bool Complete { get; set; } + + /// + /// Details about the columns that are provided as solutions + /// + public DbColumnWrapper[] ColumnInfo { get; set; } + + /// + /// The special action definition of the result set + /// + public SpecialAction SpecialAction { get; set; } + + /// + /// The visualization options for the client to render charts. + /// + public VisualizationOptions Visualization { get; set; } + + /// + /// Returns a string represents the current object. + /// + public override string ToString() => $"Result Summary Id:{Id}, Batch Id:'{BatchId}', RowCount:'{RowCount}', Complete:'{Complete}', SpecialAction:'{SpecialAction}', Visualization:'{Visualization}'"; + } +``` + + +#### Request Case + +This case only shows some important attributes in JSON. + +```json +Content-length: {the length of the JSON below} + +{ + "jsonrpc": "2.0", + "method": "query/complete", + "params": { + "ownerUri": "{the owner uri}", + "batchSummaries": [ + { + "executionElapsed": "{time}", + "executionEnd": "{time stamp}", + "executionStart": "{time stamp}", + "hasError": false, + "id": 0, + "resultSetSummaries": [ + { + "id": 0, + "batchId": 0, + "rowCount": 2, + "complete": true, + "columnInfo": [ + { + "columnName": "id", + "columnSize": 100, + "dataTypeName": "varchar" + }, + { + "columnName": "name", + "columnSize": 100, + "dataTypeName": "varchar" + } + ], + } + ], + } + ] + } +} ``` ## Language Service Protocol Extensions @@ -757,7 +1435,7 @@ Load a completion extension. #### Request -```typescript +```csharp public class CompletionExtensionParams { /// @@ -779,6 +1457,6 @@ Load a completion extension. #### Response -```typescript +```csharp bool ``` \ No newline at end of file