DOC-12705: Natural language requests to Query Service API (#180)

* DOC-12705: Natural language requests to Query Service API
* DOC-12770: add documentation for natural_output parameter
* Minor fixes

Author: simon-dew

docs/modules/n1ql-rest-query/attachments/_query-service.yaml

@@ -48,27 +48,6 @@ paths:
           application/x-www-form-urlencoded:
             schema:
               $ref: "#/components/schemas/Request"
-      x-codeSamples:
-        - lang: Shell
-          label: JSON
-          source:
-            $ref: '../../../docs/modules/n1ql-rest-query/examples/exsuccessful.sh'
-        - lang: Shell
-          label: Form Data
-          source:
-            $ref: '../../../docs/modules/n1ql-rest-query/examples/exformdata.sh'
-        - lang: Shell
-          label: Named Parameters
-          source:
-            $ref: '../../../docs/modules/n1ql-rest-query/examples/exnamed.sh'
-        - lang: Shell
-          label: Numbered Parameters
-          source:
-            $ref: '../../../docs/modules/n1ql-rest-query/examples/exnumbered.sh'
-        - lang: Shell
-          label: Unnumbered Parameters
-          source:
-            $ref: '../../../docs/modules/n1ql-rest-query/examples/expositional.sh'
       security:
         - Header: []
 #       - Parameter: []
@@ -114,11 +93,6 @@ paths:
             The format for URL-encoded parameters is consistent with the syntax for variables according to RFC 6570.
           schema:
             $ref: "#/components/schemas/Request"
-      x-codeSamples:
-        - lang: Shell
-          label: Read-Only
-          source:
-            $ref: '../../../docs/modules/n1ql-rest-query/examples/exreadonly.sh'
       security:
         - Header: []
 #       - Parameter: []
@@ -163,7 +137,7 @@ components:
         schema:
           $ref: "#/components/schemas/Response"
         example:
-          $ref: '../../../docs/modules/n1ql-rest-query/examples/exsuccessful.json'
+          $ref: '../examples/exsuccessful.json'
 
   BadRequest:
     description: |-
@@ -180,11 +154,11 @@ components:
           n1qlerror:
             summary: SQL++ Error
             value:
-              $ref: '../../../docs/modules/n1ql-rest-query/examples/exn1qlerror.json'
+              $ref: '../examples/exn1qlerror.json'
           requesterror:
             summary: Request Error
             value:
-              $ref: '../../../docs/modules/n1ql-rest-query/examples/exrequesterror.json'
+              $ref: '../examples/exrequesterror.json'
 
   Unauthorized:
     description: |-
@@ -206,7 +180,7 @@ components:
         schema:
           $ref: "#/components/schemas/Response"
         example:
-          $ref: '../../../docs/modules/n1ql-rest-query/examples/exnotfound.json'
+          $ref: '../examples/exnotfound.json'
 
   MethodNotAllowed:
     description: |-
@@ -243,7 +217,7 @@ components:
         schema:
           $ref: "#/components/schemas/Response"
         example:
-          $ref: '../../../docs/modules/n1ql-rest-query/examples/exserviceerror.json'
+          $ref: '../examples/exserviceerror.json'
 
  schemas:
   Request:
@@ -389,8 +363,8 @@ components:
         type: string
         x-desc-name: encoded_plan
         description: |-
-          In Couchbase Server 6.5 and later, this parameter is ignored and has no effect.
-          It is included for compatibility with previous versions of Couchbase Server.
+          In clusters running Couchbase Server 6.5 and later, this parameter is ignored and has no effect.
+          It is included for compatibility with previous versions.
       encoding:
         type: string
         x-desc-name: encoding
@@ -513,6 +487,112 @@ components:
           Currently, only the `default` namespace is available.
         x-has-example: true
         example: default
+      natural:
+        type: string
+        x-desc-name: natural
+        x-desc-status: Couchbase Server 8.0
+        description: |-
+          The prompt for a natural language request.
+          The Query Service uses the prompt to generate a SQL++ statement.
+
+          If the generated statement is a SELECT statement, the generated statement is returned and executed automatically.
+
+          If the generated statement is not a SELECT statement, the generated statement is returned, but not executed.
+          In this case, you must verify the statement and execute it in a separate request.
+
+          Natural language requests use the Couchbase Capella iQ service as a backend.
+          You must have a Couchbase Capella account to make a natural language request.
+
+          This parameter is available in clusters running Couchbase Server 8.0 and later.
+
+          To use this parameter, you must also specify the `natural_cred`, `natural_orgid`, and `natural_context` parameters.
+          If you don't specify all four parameters, the Query Service returns an error.
+        x-has-example: true
+        example: Show me count of airlines per country
+      natural_cred:
+        type: string
+        format: password
+        x-desc-name: natural_cred
+        x-desc-status: Couchbase Server 8.0
+        description: |-
+          The Couchbase Capella credentials for a natural language request, in the form `username:password`.
+          Be careful not to expose the credentials in log files or other output.
+
+          Natural language requests use the Couchbase Capella iQ service as a backend.
+          You must have a Couchbase Capella account to make a natural language request.
+
+          This parameter is available in clusters running Couchbase Server 8.0 and later.
+
+          To use this parameter, you must also specify the `natural`, `natural_orgid`, and `natural_context` parameters.
+          If you don't specify all four parameters, the Query Service returns an error.
+        x-has-example: true
+        example: <username>:<password>
+      natural_orgid:
+        type: string
+        format: uuid
+        x-desc-name: natural_orgid
+        x-desc-status: Couchbase Server 8.0
+        description: |-
+          The Couchbase Capella organization ID for a natural language request.
+
+          Natural language requests use the Couchbase Capella iQ service as a backend.
+          You must have a Couchbase Capella account to make a natural language request.
+
+          This parameter is available in clusters running Couchbase Server 8.0 and later.
+
+          To use this parameter, you must also specify the `natural`, `natural_cred`, and `natural_context` parameters.
+          If you don't specify all four parameters, the Query Service returns an error.
+      natural_context:
+        type: string
+        x-desc-name: natural_context
+        x-desc-status: Couchbase Server 8.0
+        description: |-
+          A list of paths specifying keyspaces for a natural language request.
+          The Query Service infers the schema of each keyspace, in order to give more precise responses from the natural language request.
+
+          The parameter may contain up to four paths, separated by commas.
+          Spaces are allowed.
+          Each path may be:
+          
+          * A full path, in the form `bucket.scope.collection` or `namespace:bucket.scope.collection`.
+
+          * A path prefix, in the form `namespace:bucket` or `bucket`, to specify the default collection in the default scope.
+
+          * A partial path, in the form `collection`.
+            In this case, you must specify the `query_context` parameter to provide the bucket and scope.
+
+          Natural language requests use the Couchbase Capella iQ service as a backend.
+          You must have a Couchbase Capella account to make a natural language request.
+
+          This parameter is available in clusters running Couchbase Server 8.0 and later.
+
+          To use this parameter, you must also specify the `natural`, `natural_cred`, and `natural_orgid` parameters.
+          If you don't specify all four parameters, the Query Service returns an error.
+        x-has-example: true
+        example: travel-sample, travel-sample.inventory.airline, airline
+      natural_output:
+        type: string
+        x-desc-name: natural_output
+        x-desc-status: Couchbase Server 8.0
+        description: |-
+          Specifies the required output for a natural language request.
+
+          * `sql` &mdash;
+            The output is a SQL++ statement.
+
+          * `jsudf` &mdash;
+            The output is a `CREATE FUNCTION` statement which you can use to generate a SQL++ managed JavaScript user-defined function.
+
+          * `ftssql` &mdash;
+            The output is a SQL++ statement which can use a Flex index, if available.
+
+          Natural language requests use the Couchbase Capella iQ service as a backend.
+          You must have a Couchbase Capella account to make a natural language request.
+
+          This parameter is available in clusters running Couchbase Server 8.0 and later.
+        x-has-default: true
+        default: sql
+        enum: ["sql", "jsudf", "ftssql"]
       numatrs:
         type: integer
         format: int32
@@ -582,7 +662,7 @@ components:
         type: string
         x-desc-name: prepared
         description: |-
-          _Required_ if `statement` not provided.
+          _Required_ if `statement` or `natural` not provided.
 
           The name of the prepared SQL++ statement to be executed.
           Refer to [EXECUTE][execute] for examples.
@@ -840,7 +920,7 @@ components:
         type: string
         x-desc-name: statement
         description: |-
-          _Required_ if `prepared` not provided.
+          _Required_ if `prepared` or `natural` not provided.
 
           Any valid SQL++ statement for a POST request, or a read-only SQL++ statement (SELECT, EXPLAIN) for a GET request.
 
@@ -1105,6 +1185,12 @@ components:
       clientContextID:
         type: string
         description: The client context ID of the request, if one was supplied &mdash; see `client_context_id` in [Request Parameters](#Request).
+      generated_statement:
+        type: string
+        description: |-
+          The generated statement, if the request was a natural language prompt.
+        x-has-example: true
+        example: SELECT country, COUNT(*) AS `airline_count` FROM `travel-sample`.`inventory`.`airline` AS `a` GROUP BY country
       signature:
         type: object
         description: |-
@@ -1208,9 +1294,11 @@ components:
     properties:
       elapsedTime:
         type: string
+        format: duration
         description: The total time taken for the request, that is the time from when the request was received until the results were returned.
       executionTime:
         type: string
+        format: duration
         description: The time taken for the execution of the request, that is the time from when query execution started until the results were returned.
       resultCount:
         type: integer
@@ -1220,6 +1308,12 @@ components:
         type: integer
         format: unsigned
         description: The total number of bytes in the results.
+      naturalLanguageProcessingTime:
+        type: string
+        format: duration
+        description: |-
+          The total time spent processing a natural language request.
+          The cumulation of authentication, collecting schema, and time waiting for the response from the LLM, or wait time for the natural language request to be serviced.
       mutationCount:
         type: integer
         description: The number of mutations that were made during the request.