From 0ae4a3cb0d06ae493052033b2d5f3d02a73b7198 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 9 Sep 2025 17:02:16 +0530 Subject: [PATCH 01/11] Add a new Usage section --- .../n1ql-language-reference/using-ai.adoc | 105 ++++++++++++------ 1 file changed, 71 insertions(+), 34 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index 4c821141a..42cca9306 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -9,25 +9,20 @@ == Purpose -You can use the USING AI statement to input natural language queries through {sqlpp} interfaces such as the CBQ shell, REST APIs, and SDKs. +You can use the USING AI statement to convert a natural language prompt into a {sqlpp} query. When executed, the statement passes the input to Large Language Models (LLMs), which interpret the request and return the equivalent {sqlpp} query. -For example, you can input prompts such as `How many airlines are based in Europe` or `List the names of all hotels in the same city as an airport`, and the statement will generate the corresponding SQL++ queries. +For example, you can input prompts such as `How many airlines are based in Europe` or `List the names of all hotels in the same city as an airport`, and the statement will generate the corresponding SQL++ query. -If USING AI generates a SELECT query, it automatically executes it and returns the results. -For all other query types, it returns the generated query as a string without executing it. +If the generated statement is a SELECT query, the Query Service automatically executes it and returns the results. +For all other query types, it returns the generated statement as a string without executing it. +You can control this behavior by using the <> option. -[IMPORTANT] -==== -* With the introduction of the USING AI statement, you might notice that AI is now recognized as a keyword. +IMPORTANT: With the introduction of the USING AI statement, you might notice that AI is now recognized as a keyword. However, this change has been implemented in a way that does not break existing queries or applications where "ai" is used as a field name or identifier. For example, queries like `SELECT ai FROM XYZ` will continue to work without any issues. AI is treated as a keyword only when used in conjunction with the USING AI statement. -* Currently, the Couchbase Server Web Console does not support the USING AI statement. -You can execute it only through the CBQ shell, REST APIs, or SDKs. -==== - == Prerequisites Before using the USING AI statement, make sure you have: @@ -37,6 +32,7 @@ Before using the USING AI statement, make sure you have: NOTE: Although the USING AI statement requires a Capella account, you can use it with any Couchbase Server 8.0 instances. +[[syntax]] == Syntax [source,ebnf] @@ -50,19 +46,13 @@ prompt:: [Required] A natural language request that you want to convert into a SQL++ query. options:: -[Optional] A JSON object specifying additional <> to guide the statement execution. -+ -By default, the statement uses the `natural_orgid`, `natural_cred`, and `natural_context` parameters. -These parameters determine the organization ID, credentials, and keyspaces for the request. -You can override them by using the <> object. - -//TODO: Add links to `natural_orgid`, `natural_cred` and `natural_context` when available in the 8.0 documentation. +[Optional] A JSON object specifying additional <> for the statement. === FLEXINDEX / FTS Use the optional `FLEXINDEX` or `FTS` keyword to generate a query that uses an FTS or flex index. This hint appends a `USE INDEX (USING FTS)` clause to all `FROM` keyspaces in the generated query. -Refer to <>. +See <>. [[optional-parameters]] === Options @@ -77,11 +67,11 @@ __optional__ Can be one of the following: -* A string in the username:password format, which matches the `natural_cred` specification. +* A string in the username:password format. //TODO: Add link to `natural_cred` when available in the 8.0 documentation. * An object with the fields `user` and `pass`, similar to the xref:n1ql:n1ql-manage/query-settings.adoc#Credentials[`creds`] parameter. -If specified, this value overrides the `natural_cred` parameter, which by default contains your Capella credentials. +If specified, this value overrides the `natural_cred` parameter. | String or object @@ -113,13 +103,13 @@ If specified, this value overrides the `natural_orgid` parameter, which by defau | **execute** + __optional__ -| Indicates if the generated statement should be executed immediately. +| Indicates if the generated statement should be executed automatically. If `TRUE`, the Query Service executes the generated statement and returns the results. This applies only if the statement is a SELECT query. For other statement types, such as INSERT, UPDATE, DELETE, UPSERT, or CREATE FUNCTION, the Query Service returns the statement without executing it, even if `execute` is `TRUE`. -Refer to <>. +See <>. If `FALSE`, the Query Service returns the generated statement as a string without executing it. @@ -154,7 +144,37 @@ The Query Service returns an error if you specify a value not included in this l |=== TIP: You can prefix a USING AI statement with EXPLAIN or ADVISE to get the query plan or index recommendations for your generated query. -Refer to <>. +See <>. + +[[usage]] +== Usage + +To use a USING AI statement, you must provide the following parameters: + +* `natural_cred` - Your Capella account credentials. +* `natural_orgid` - Your Capella organization ID. +* `natural_context` - One or more keyspaces to use for the request. + +You can set these parameters in two ways: by setting them as request-level parameters, or by including them directly in the statement. + +=== Setting Parameters at the Request Level + +You can set `natural_cred`, `natural_orgid`, and `natural_context` as request-level parameters, outside the USING AI statement. +When set, these parameters apply to all subsequent USING AI statements in that session. + +For example: + +* In cbq shell, you can set these parameters using the `\set` command. See <>. +* In the Query Workbench, you can set these parameters in the xref:server:tools/query-workbench.adoc#query-preferences[Run-Time Preferences] window as named parameters (without the $ prefix). + +Once configured, you do not need to specify `creds`, `orgId`, or `keyspaces` in the WITH clause. + +For more information on how to set request-level parameters, see xref:n1ql:n1ql-manage/query-settings.adoc#section_nnj_sjk_k1b[Configure Queries]. + +=== Setting Parameters Within the Statement + +You can override the default `natural_cred`, `natural_orgid`, and `natural_context` parameters by specifying the `creds`, `orgId`, and `keyspaces` options in the `WITH` clause of the USING AI statement. +See <>. == Result @@ -162,6 +182,10 @@ A JSON object containing the generated statement, execution status, and metrics. If the generated statement is a SELECT query and the `execute` option is `TRUE` (default), the output includes the query results as well. +IMPORTANT: Currently, when you run a USING AI statement from the Query Workbench, it does not show you the generated SQL++ statement. +Instead, it returns only the executed results of the generated statement. + +[[handling-passwords]] == Handling Passwords Securely Use `creds` and `natural_cred` parameters with caution to avoid exposing password information through history files or logs. @@ -172,7 +196,7 @@ This ensures that the password is not recorded in the shell history. Similarly, if you are sending requests directly to a REST endpoint from a shell, be mindful of how you provide the password and whether it will be recorded in the shell history. Consider using a method like the following to prompt for the password: -[source,sh] +[source,console] ---- echo -n "Enter your password: " read -s p @@ -193,7 +217,7 @@ In the following examples, replace `natural_cred` and `natural_orgid` with your {example-note} .Request -[source, console] +[source, sh] ---- \set -natural_context travel-sample.inventory.hotel; \set -natural_cred username@example.com:P@ssw0rd; @@ -235,7 +259,7 @@ USING AI How many hotels provide free parking?; {example-note} .Request -[source, console] +[source,sh] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; @@ -270,7 +294,7 @@ How many airlines are based in United Kingdom?; {example-note} .Request -[source, console] +[source, sh] ---- USING AI WITH { @@ -314,7 +338,7 @@ List the names of all hotels in the same city as an airport; .Natural language prompt submitted directly to the Query REST API ==== .Request -[source, sh] +[source, console] ---- echo -n "Enter your password: " read -s p @@ -359,7 +383,7 @@ curl -s -d "natural_cred=username@example.com:${p}" \ {example-note} .Request -[source, console] +[source, sh] ---- \set -natural_cred rakhi.prathap@couchbase.com:Couchbase123#; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; @@ -400,7 +424,7 @@ This is because the Query Service executes the generated statement only if it is {example-note} .Request -[source, console] +[source, sh] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 5c670d3e-12a3-456b-7c89-123456789ab; @@ -444,7 +468,7 @@ How many hotels are located in California?; This example uses the same prompt as <> but specifies the `output` option instead of the `FLEXINDEX` keyword. .Request -[source, console] +[source, sh] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 5c670d3e-12a3-456b-7c89-123456789ab; @@ -487,7 +511,7 @@ How many hotels are located in California?; {example-note} .Request -[source, console] +[source, sh] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 5c670d3e-12a3-456b-7c89-123456789ab; @@ -539,7 +563,7 @@ Create a function to list all hotels in California; {example-note} .Request -[source, console] +[source, sh] ---- \set -natural_cred rakhi.prathap@couchbase.com:Couchbase123#; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; @@ -645,4 +669,17 @@ List the names and cities of hotels with a rating greater than 4; } } ---- +==== + +[[example-10]] +.Running USING AI in Query Workbench with pre-set parameters +==== +Before executing the USING AI statement from the Query Workbench, you must set the required parameters in the xref:server:tools/query-workbench.adoc#query-preferences[Run-Time Preferences] window. +For more information, see the <> section. + +.Request +[source, sqlpp] +---- +USING AI How many hotels provide free parking?; +---- ==== \ No newline at end of file From a324ea43335a76bd555941381043d8d7f6f64864 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Wed, 10 Sep 2025 15:22:47 +0530 Subject: [PATCH 02/11] More improvements --- .../n1ql-language-reference/using-ai.adoc | 127 +++++++++++------- 1 file changed, 82 insertions(+), 45 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index 42cca9306..d37ccd225 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -12,11 +12,11 @@ You can use the USING AI statement to convert a natural language prompt into a {sqlpp} query. When executed, the statement passes the input to Large Language Models (LLMs), which interpret the request and return the equivalent {sqlpp} query. -For example, you can input prompts such as `How many airlines are based in Europe` or `List the names of all hotels in the same city as an airport`, and the statement will generate the corresponding SQL++ query. +For example, you can input prompts such as `How many airlines are based in Europe` or `List the names of all hotels in the same city as an airport`, and the statement generates the corresponding SQL++ query. If the generated statement is a SELECT query, the Query Service automatically executes it and returns the results. For all other query types, it returns the generated statement as a string without executing it. -You can control this behavior by using the <> option. +However, you can modify this behavior by using the <> option. IMPORTANT: With the introduction of the USING AI statement, you might notice that AI is now recognized as a keyword. However, this change has been implemented in a way that does not break existing queries or applications where "ai" is used as a field name or identifier. @@ -47,6 +47,10 @@ prompt:: options:: [Optional] A JSON object specifying additional <> for the statement. ++ +By default, the statement uses the `natural_orgid`, `natural_cred`, and `natural_context` parameters. +These parameters determine the organization ID, credentials, and keyspaces for the request. +You can override them by specifying the relevant parameters in the <> object. === FLEXINDEX / FTS @@ -63,15 +67,14 @@ See <>. | **creds** + __optional__ -| Credentials to authenticate the request. +| Couchbase Capella credentials to authenticate the request. Can be one of the following: * A string in the username:password format. -//TODO: Add link to `natural_cred` when available in the 8.0 documentation. -* An object with the fields `user` and `pass`, similar to the xref:n1ql:n1ql-manage/query-settings.adoc#Credentials[`creds`] parameter. +* An object with the fields `user` and `pass`, similar to the xref:n1ql:n1ql-manage/query-settings.adoc#Credentials[creds] parameter. -If specified, this value overrides the `natural_cred` parameter. +If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_cred] parameter. | String or object @@ -82,21 +85,19 @@ __optional__ Can be one of the following: -* A string matching the `natural_keyspaces` specification. -//TODO: Add link to `natural_context` when available in the 8.0 documentation. -* An array of comma-separated strings, which when joined, form the value. +* A string matching the xref:n1ql-rest-query:index.adoc#Request[natural_context] specification. +* An array of comma-separated strings. -If specified, this value overrides the default `natural_context` parameter. +If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_context] parameter. | String or an array of strings | **orgId** + __optional__ -| Organization ID for the request. +| Couchbase Capella organization ID for the request. -If specified, this value overrides the `natural_orgid` parameter, which by default contains your Capella organization ID. -//TODO: Add link to `natural_orgid` when available in the 8.0 documentation. +If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_orgid] parameter. | String @@ -108,10 +109,10 @@ __optional__ If `TRUE`, the Query Service executes the generated statement and returns the results. This applies only if the statement is a SELECT query. -For other statement types, such as INSERT, UPDATE, DELETE, UPSERT, or CREATE FUNCTION, the Query Service returns the statement without executing it, even if `execute` is `TRUE`. +For other statement types, such as INSERT, UPDATE, DELETE, UPSERT, or CREATE FUNCTION, the statement is not executed, even if `execute` is `TRUE`. See <>. -If `FALSE`, the Query Service returns the generated statement as a string without executing it. +If `FALSE`, generated statement is returned, but not executed. *Default:* `TRUE` @@ -123,20 +124,22 @@ __optional__ Possible values are: -- -* `sql` - Generates a standard SQL++ query. +* `sql` — +Generates a standard SQL++ query. -* `jsudf` - Generates a CREATE FUNCTION statement. +* `jsudf` — +Generates a CREATE FUNCTION statement. You can use this to create a SQL++ managed JavaScript user-defined function. -+ The Query Service does not execute the CREATE FUNCTION, even if `execute` is `TRUE`. You must run the generated statement separately to create the function. -* `ftssql` - Generates a SQL++ query optimized for FTS or flex indexes. +* `ftssql` — +Generates a SQL++ query optimized for FTS or flex indexes. The Query Service appends a `USE INDEX (USING FTS)` clause to all `FROM` keyspaces in the generated query. This enables the query to use a flex index if it's available. -- -The Query Service returns an error if you specify a value not included in this list. +The statement returns an error if you specify a value not included in this list. *Default:* `sql` | String @@ -149,13 +152,12 @@ See <>. [[usage]] == Usage -To use a USING AI statement, you must provide the following parameters: +To use a USING AI statement, you must provide the following details: your Capella credentials, Capella organization ID, and one or more keyspaces. -* `natural_cred` - Your Capella account credentials. -* `natural_orgid` - Your Capella organization ID. -* `natural_context` - One or more keyspaces to use for the request. +You can provide these details in two ways: -You can set these parameters in two ways: by setting them as request-level parameters, or by including them directly in the statement. +* By setting them as request-level parameters using the `natural_cred`, `natural_orgid`, and `natural_context` parameters. +* By including them directly in the statement using the `creds`, `orgId`, and `keyspaces` parameters. === Setting Parameters at the Request Level @@ -164,16 +166,18 @@ When set, these parameters apply to all subsequent USING AI statements in that s For example: -* In cbq shell, you can set these parameters using the `\set` command. See <>. -* In the Query Workbench, you can set these parameters in the xref:server:tools/query-workbench.adoc#query-preferences[Run-Time Preferences] window as named parameters (without the $ prefix). +* In cbq shell, you can set these parameters using the `\set` command. +See <>. +* In the Query Workbench, you can set these parameters in the xref:tools:query-workbench.adoc#query-preferences[Run-Time Preferences] window as named parameters (without the $ prefix). -Once configured, you do not need to specify `creds`, `orgId`, or `keyspaces` in the WITH clause. +For more information about how to set request-level parameters, see xref:n1ql:n1ql-manage/query-settings.adoc#section_nnj_sjk_k1b[Configure Queries]. -For more information on how to set request-level parameters, see xref:n1ql:n1ql-manage/query-settings.adoc#section_nnj_sjk_k1b[Configure Queries]. +Once configured, you need not specify `creds`, `orgId`, or `keyspaces` in the WITH clause. -=== Setting Parameters Within the Statement +=== Setting Parameters Inline -You can override the default `natural_cred`, `natural_orgid`, and `natural_context` parameters by specifying the `creds`, `orgId`, and `keyspaces` options in the `WITH` clause of the USING AI statement. +You can specify the `creds`, `orgId`, and `keyspaces` options directly in the `WITH` clause of the USING AI statement. +If specified, these values override the `natural_cred`, `natural_orgid`, and `natural_context` parameters. See <>. == Result @@ -182,7 +186,7 @@ A JSON object containing the generated statement, execution status, and metrics. If the generated statement is a SELECT query and the `execute` option is `TRUE` (default), the output includes the query results as well. -IMPORTANT: Currently, when you run a USING AI statement from the Query Workbench, it does not show you the generated SQL++ statement. +IMPORTANT: Currently, when you run a USING AI statement from the Query Workbench, it does not return the generated SQL++ statement. Instead, it returns only the executed results of the generated statement. [[handling-passwords]] @@ -193,7 +197,7 @@ When working with the cbq shell, avoid passing passwords directly on the command Instead, use the `\set` command to specify only the username, and then enter the password at the terminal prompt. This ensures that the password is not recorded in the shell history. -Similarly, if you are sending requests directly to a REST endpoint from a shell, be mindful of how you provide the password and whether it will be recorded in the shell history. +Similarly, if you're sending requests directly to a REST endpoint from a shell, be mindful of how you provide the password and whether it will be recorded in the shell history. Consider using a method like the following to prompt for the password: [source,console] @@ -209,10 +213,10 @@ If security is a concern, consider using an HTTPS connection. == Examples -In the following examples, replace `natural_cred` and `natural_orgid` with your Capella credentials and organization ID, respectively. +In the following examples, replace `natural_cred`/`creds` and `natural_orgid`/`orgId` with your Couchbase Capella credentials and organization ID, respectively. [[example-1]] -.Natural language prompt with default request parameters +.USING AI with default request parameters ==== {example-note} @@ -254,7 +258,7 @@ USING AI How many hotels provide free parking?; ==== [[example-2]] -.Natural language prompt with a custom keyspace +.USING AI with execution disabled and keyspace specified within the statement ==== {example-note} @@ -289,7 +293,7 @@ How many airlines are based in United Kingdom?; ==== [[example-3]] -.Natural language prompt with all parameters directly in the statement, overriding the default ones +.USING AI with all parameters directly in the statement ==== {example-note} @@ -335,7 +339,7 @@ List the names of all hotels in the same city as an airport; ==== [[example-4]] -.Natural language prompt submitted directly to the Query REST API +.USING AI with the Query REST API ==== .Request [source, console] @@ -385,7 +389,7 @@ curl -s -d "natural_cred=username@example.com:${p}" \ .Request [source, sh] ---- -\set -natural_cred rakhi.prathap@couchbase.com:Couchbase123#; +\set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; USING AI WITH {"keyspaces":["travel-sample.inventory.hotel"], "execute": true} \ Insert a new hotel named "Sunset Inn" in "Miami, Florida" with a rating of 4; @@ -414,8 +418,8 @@ Insert a new hotel named "Sunset Inn" in "Miami, Florida" with a rating of 4; } } ---- -If you examine the `hotel` keyspace, you will see that this document is not inserted, even though `execute` was set to `TRUE`. -This is because the Query Service executes the generated statement only if it is a SELECT statement. +If you examine the `hotel` keyspace, you'll see that this document is not inserted, even though `execute` was set to `TRUE`. +This is because the Query Service executes the generated statement only if it's a SELECT statement. ==== [[example-6]] @@ -558,14 +562,14 @@ Create a function to list all hotels in California; ==== [[example-9]] -.Using EXPLAIN with USING AI +.Prefixing USING AI with EXPLAIN ==== {example-note} .Request [source, sh] ---- -\set -natural_cred rakhi.prathap@couchbase.com:Couchbase123#; +\set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; EXPLAIN USING AI WITH {"keyspaces":["travel-sample.inventory.hotel"]} \ List the names and cities of hotels with a rating greater than 4; @@ -672,9 +676,9 @@ List the names and cities of hotels with a rating greater than 4; ==== [[example-10]] -.Running USING AI in Query Workbench with pre-set parameters +.Running USING AI from the Query Workbench using request-level parameters ==== -Before executing the USING AI statement from the Query Workbench, you must set the required parameters in the xref:server:tools/query-workbench.adoc#query-preferences[Run-Time Preferences] window. +Before executing this statement, you must set the required parameters in the xref:server:tools/query-workbench.adoc#query-preferences[Run-Time Preferences] window. For more information, see the <> section. .Request @@ -682,4 +686,37 @@ For more information, see the <> section. ---- USING AI How many hotels provide free parking?; ---- +.Response +[source,json] +---- +[{ + "$1": 253 +}] +---- +When you execute a USING AI statement from the Query Workbench, it returns only the results of the executed query and not the generated SQL++ statement itself. +==== + +[[example-11]] +.Running USING AI from the Query Workbench with all parameters inline +==== +This is the same as <>, but it specifies all parameters directly in the USING AI statement. + +.Request +[source, sqlpp] +---- +USING AI WITH { +"creds":"username@example.com:P@ssw0rd", +"orgId":"5c670d3e-12a3-456b-7c89-123456789ab", +"keyspaces":"travel-sample.inventory.hotel" +} How many hotels provide free parking?; +---- + +.Response +[source,json] +---- +[{ + "$1": 253 +}] +---- +When you execute a USING AI statement from the Query Workbench, it returns only the results of the executed query and not the generated SQL++ statement itself. ==== \ No newline at end of file From 8148bd321ec58d478838ad2cebbb23601d96cb6e Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 11 Sep 2025 11:00:09 +0530 Subject: [PATCH 03/11] More improvements --- .../n1ql-language-reference/using-ai.adoc | 59 +++++++++++-------- 1 file changed, 33 insertions(+), 26 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index d37ccd225..3c63a13f5 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -76,6 +76,8 @@ Can be one of the following: If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_cred] parameter. +To ensure your credentials are passed securely, see <>. + | String or object | **keyspaces** + @@ -107,12 +109,11 @@ __optional__ | Indicates if the generated statement should be executed automatically. If `TRUE`, the Query Service executes the generated statement and returns the results. - This applies only if the statement is a SELECT query. For other statement types, such as INSERT, UPDATE, DELETE, UPSERT, or CREATE FUNCTION, the statement is not executed, even if `execute` is `TRUE`. See <>. -If `FALSE`, generated statement is returned, but not executed. +If `FALSE`, the generated statement is returned, but not executed. *Default:* `TRUE` @@ -130,7 +131,7 @@ Generates a standard SQL++ query. * `jsudf` — Generates a CREATE FUNCTION statement. You can use this to create a SQL++ managed JavaScript user-defined function. -The Query Service does not execute the CREATE FUNCTION, even if `execute` is `TRUE`. +Note that the Query Service does not execute the CREATE FUNCTION, even if `execute` is `TRUE`. You must run the generated statement separately to create the function. * `ftssql` — @@ -152,31 +153,32 @@ See <>. [[usage]] == Usage -To use a USING AI statement, you must provide the following details: your Capella credentials, Capella organization ID, and one or more keyspaces. - +To use a USING AI statement, you must provide your Capella credentials, Capella organization ID, and one or more keyspaces. You can provide these details in two ways: -* By setting them as request-level parameters using the `natural_cred`, `natural_orgid`, and `natural_context` parameters. -* By including them directly in the statement using the `creds`, `orgId`, and `keyspaces` parameters. +* <> +* <> -=== Setting Parameters at the Request Level +[[request-level-parameters]] +=== Set Parameters at the Request Level You can set `natural_cred`, `natural_orgid`, and `natural_context` as request-level parameters, outside the USING AI statement. When set, these parameters apply to all subsequent USING AI statements in that session. For example: -* In cbq shell, you can set these parameters using the `\set` command. +* In the cbq shell, you can set these parameters using the `\set` command. See <>. -* In the Query Workbench, you can set these parameters in the xref:tools:query-workbench.adoc#query-preferences[Run-Time Preferences] window as named parameters (without the $ prefix). +* In the Query Workbench, you can set these parameters in the xref:tools:query-workbench.adoc#query-preferences[Run-Time Preferences] window as named parameters, without the $ prefix. For more information about how to set request-level parameters, see xref:n1ql:n1ql-manage/query-settings.adoc#section_nnj_sjk_k1b[Configure Queries]. -Once configured, you need not specify `creds`, `orgId`, or `keyspaces` in the WITH clause. +Once configured, you do not need to specify `creds`, `orgId`, or `keyspaces` in the WITH clause. -=== Setting Parameters Inline +[[inline-parameters]] +=== Set Parameters Inline -You can specify the `creds`, `orgId`, and `keyspaces` options directly in the `WITH` clause of the USING AI statement. +You can set the `creds`, `orgId`, and `keyspaces` options directly in the `WITH` clause of the USING AI statement. If specified, these values override the `natural_cred`, `natural_orgid`, and `natural_context` parameters. See <>. @@ -208,7 +210,7 @@ echo curl -s -d "natural_cred=:${p}" ... ---- -If you choose to reuse the password by setting an evironment variable, note that it might be visible to other users on the system with sufficient privileges for process inspection (for example, through `/proc`). +If you choose to reuse the password by setting an environment variable, note that it might be visible to other users on the system with sufficient privileges for process inspection (for example, through `/proc`). If security is a concern, consider using an HTTPS connection. == Examples @@ -233,7 +235,8 @@ USING AI How many hotels provide free parking?; ---- { "requestID": "097f9cbf-57f2-4832-986d-4f85041c91dc", - "generated_statement": "SELECT COUNT(*) FROM `travel-sample`.`inventory`.`hotel` + "generated_statement": "SELECT COUNT(*) + FROM `travel-sample`.`inventory`.`hotel` AS `h` WHERE `h`.`free_parking` = TRUE", "signature": { "$1": "number" @@ -258,7 +261,7 @@ USING AI How many hotels provide free parking?; ==== [[example-2]] -.USING AI with execution disabled and keyspace specified within the statement +.USING AI with keyspace specified within the statement and execute set to FALSE ==== {example-note} @@ -358,7 +361,8 @@ curl -s -d "natural_cred=username@example.com:${p}" \ ---- { "requestID": "325457b8-9cf4-477b-aaf5-7609f2ae79bf", - "generated_statement": "SELECT COUNT(*) FROM `travel-sample`.`inventory`.`landmark` + "generated_statement": "SELECT COUNT(*) + FROM `travel-sample`.`inventory`.`landmark` AS `l` WHERE `l`.`geo`.`lon` \u003c 0", "signature": { "$1": "number" @@ -418,12 +422,12 @@ Insert a new hotel named "Sunset Inn" in "Miami, Florida" with a rating of 4; } } ---- -If you examine the `hotel` keyspace, you'll see that this document is not inserted, even though `execute` was set to `TRUE`. -This is because the Query Service executes the generated statement only if it's a SELECT statement. +If you examine the `hotel` keyspace, you'll see that this document was not inserted, even though `execute` was set to `TRUE`. +This is because the Query Service executes the generated statement only if it's a SELECT query. ==== [[example-6]] -.USING AI with flex index hint +.USING AI with the flex index hint ==== {example-note} @@ -469,7 +473,7 @@ How many hotels are located in California?; ==== {example-note} -This example uses the same prompt as <> but specifies the `output` option instead of the `FLEXINDEX` keyword. +This example uses the same prompt as <>, but specifies the `output` option instead of the `FLEXINDEX` keyword. .Request [source, sh] @@ -486,7 +490,8 @@ How many hotels are located in California?; { "requestID": "c6fcaed5-23fa-4dc5-936c-febc6b5cb222", "generated_statement": "SELECT COUNT(*) - FROM `travel-sample`.`inventory`.`hotel` AS `h` + FROM `travel-sample`.`inventory`.`hotel` + AS `h` USE INDEX (USING FTS) WHERE `h`.`state` = \"California\"", "signature": { "$1": "number" @@ -537,7 +542,8 @@ Create a function to list all hotels in California; AS `h` WHERE `h`.`state` = \"CA\"; /* Initialize an empty array to store the results */ var res = []; - /* Iterate over the query results and push each hotel into the results array */ + /* Iterate over the query results and + push each hotel into the results array */ for (const doc of q) { var hotel = {}; hotel.name = doc.name; @@ -636,7 +642,8 @@ List the names and cities of hotels with a rating greater than 4; { "#operator": "Filter", "condition": "any `review` in (`h`.`reviews`) - satisfies (4 \u003c (`review`.`rating`)) end" + satisfies (4 \u003c (`review`.`rating`)) + end" }, { "#operator": "InitialProject", @@ -678,7 +685,7 @@ List the names and cities of hotels with a rating greater than 4; [[example-10]] .Running USING AI from the Query Workbench using request-level parameters ==== -Before executing this statement, you must set the required parameters in the xref:server:tools/query-workbench.adoc#query-preferences[Run-Time Preferences] window. +Before executing the following statement, you must set the `natural_cred`, `natural_orgid`, and `natural_context` parameters in the xref:tools:query-workbench.adoc#query-preferences[Run-Time Preferences] window. For more information, see the <> section. .Request @@ -699,7 +706,7 @@ When you execute a USING AI statement from the Query Workbench, it returns only [[example-11]] .Running USING AI from the Query Workbench with all parameters inline ==== -This is the same as <>, but it specifies all parameters directly in the USING AI statement. +This is equivalent to <>, but specifies all parameters directly in the statement, instead of setting them at the request-level. .Request [source, sqlpp] From 039c5f8c71ac59a72de8f32143f3a053f5687f53 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 15 Sep 2025 13:19:18 +0530 Subject: [PATCH 04/11] Apply changes from review --- .../n1ql-language-reference/using-ai.adoc | 74 ++++++------------- preview/DOC-13536-using-ai-from-ui.yml | 8 ++ 2 files changed, 32 insertions(+), 50 deletions(-) create mode 100644 preview/DOC-13536-using-ai-from-ui.yml diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index 3c63a13f5..0157f9fac 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -28,7 +28,7 @@ AI is treated as a keyword only when used in conjunction with the USING AI state Before using the USING AI statement, make sure you have: * A Couchbase Capella account. -* Your Capella account credentials and organization ID readily available. +* Your Capella account credentials and organization ID readily available. NOTE: Although the USING AI statement requires a Capella account, you can use it with any Couchbase Server 8.0 instances. @@ -101,6 +101,11 @@ __optional__ If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_orgid] parameter. +To find your organization ID, log in to your Couchbase Capella account and check the URL in your web browser. +The organization ID is the `oid` parameter in the URL. + +For example, in the URL https://cloud.couchbase.com/databases?oid=5c670d3e-12a3-456b-7c89-123456789ab, the organization ID is `5c670d3e-12a3-456b-7c89-123456789ab`. + | String | **execute** + @@ -188,9 +193,6 @@ A JSON object containing the generated statement, execution status, and metrics. If the generated statement is a SELECT query and the `execute` option is `TRUE` (default), the output includes the query results as well. -IMPORTANT: Currently, when you run a USING AI statement from the Query Workbench, it does not return the generated SQL++ statement. -Instead, it returns only the executed results of the generated statement. - [[handling-passwords]] == Handling Passwords Securely @@ -199,6 +201,24 @@ When working with the cbq shell, avoid passing passwords directly on the command Instead, use the `\set` command to specify only the username, and then enter the password at the terminal prompt. This ensures that the password is not recorded in the shell history. +For example: + +[source, sh] +---- +cbq> \set -natural_cred username@example.com; +Enter password for "natural_cred": + +cbq> \set; + Query Parameters : + Parameter name : natural_cred + Value : [username@example.com:***] + + Parameter name : profile + Value : ["timings"] + + ... +---- + Similarly, if you're sending requests directly to a REST endpoint from a shell, be mindful of how you provide the password and whether it will be recorded in the shell history. Consider using a method like the following to prompt for the password: @@ -680,50 +700,4 @@ List the names and cities of hotels with a rating greater than 4; } } ---- -==== - -[[example-10]] -.Running USING AI from the Query Workbench using request-level parameters -==== -Before executing the following statement, you must set the `natural_cred`, `natural_orgid`, and `natural_context` parameters in the xref:tools:query-workbench.adoc#query-preferences[Run-Time Preferences] window. -For more information, see the <> section. - -.Request -[source, sqlpp] ----- -USING AI How many hotels provide free parking?; ----- -.Response -[source,json] ----- -[{ - "$1": 253 -}] ----- -When you execute a USING AI statement from the Query Workbench, it returns only the results of the executed query and not the generated SQL++ statement itself. -==== - -[[example-11]] -.Running USING AI from the Query Workbench with all parameters inline -==== -This is equivalent to <>, but specifies all parameters directly in the statement, instead of setting them at the request-level. - -.Request -[source, sqlpp] ----- -USING AI WITH { -"creds":"username@example.com:P@ssw0rd", -"orgId":"5c670d3e-12a3-456b-7c89-123456789ab", -"keyspaces":"travel-sample.inventory.hotel" -} How many hotels provide free parking?; ----- - -.Response -[source,json] ----- -[{ - "$1": 253 -}] ----- -When you execute a USING AI statement from the Query Workbench, it returns only the results of the executed query and not the generated SQL++ statement itself. ==== \ No newline at end of file diff --git a/preview/DOC-13536-using-ai-from-ui.yml b/preview/DOC-13536-using-ai-from-ui.yml new file mode 100644 index 000000000..e16dfcd6a --- /dev/null +++ b/preview/DOC-13536-using-ai-from-ui.yml @@ -0,0 +1,8 @@ +sources: + docs-server: + branches: [release/8.0] + cb-swagger: + branches: [release/8.0] + start_path: docs +override: + startPage: server:introduction:intro.adoc From d43d1d40ab877e8e4c7ba12698d763ae987c35ef Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Mon, 15 Sep 2025 14:01:19 +0530 Subject: [PATCH 05/11] Adding a few xrefs --- modules/n1ql/pages/n1ql-language-reference/using-ai.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index 0157f9fac..eb80eda02 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -48,7 +48,7 @@ prompt:: options:: [Optional] A JSON object specifying additional <> for the statement. + -By default, the statement uses the `natural_orgid`, `natural_cred`, and `natural_context` parameters. +By default, the statement uses the xref:n1ql-rest-query:index.adoc#Request[natural_orgid], xref:n1ql-rest-query:index.adoc#Request[natural_cred], and xref:n1ql-rest-query:index.adoc#Request[natural_context] parameters. These parameters determine the organization ID, credentials, and keyspaces for the request. You can override them by specifying the relevant parameters in the <> object. @@ -215,7 +215,7 @@ cbq> \set; Parameter name : profile Value : ["timings"] - + ... ---- From ca5d337a85954935b4c59e4fb93b83c78ac521f5 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Tue, 16 Sep 2025 11:55:16 +0530 Subject: [PATCH 06/11] A tiny EBNF correction --- .../n1ql-language-reference/using-ai.png | Bin 11605 -> 11790 bytes modules/n1ql/partials/grammar/utility.ebnf | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/assets/images/n1ql-language-reference/using-ai.png b/modules/n1ql/assets/images/n1ql-language-reference/using-ai.png index d67f46fe414e206bedfd1f1fd0521de2622ecb90..fa0e9d4bf3ead4252ecc58e64b54e68cd70cf989 100644 GIT binary patch literal 11790 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 diff --git a/modules/n1ql/partials/grammar/utility.ebnf b/modules/n1ql/partials/grammar/utility.ebnf index f2dfcf515..8e40fb77b 100644 --- a/modules/n1ql/partials/grammar/utility.ebnf +++ b/modules/n1ql/partials/grammar/utility.ebnf @@ -99,5 +99,5 @@ delete-all ::= 'ALL' | 'STATISTICS' ***********************/ /* tag::using-ai[] */ -using-ai ::= 'USING AI' ( 'FOR' ( 'FLEXINDEX' | 'FTS' ) )? ( 'WITH' options )? prompt +using-ai ::= 'USING' 'AI' ( 'FOR' ( 'FLEXINDEX' | 'FTS' ) )? ( 'WITH' options )? prompt /* end::using-ai[] */ \ No newline at end of file From b32f82388d15b4bee7fc4159f7e2d8bf2ef5ecfa Mon Sep 17 00:00:00 2001 From: rakhi-prathap Date: Wed, 24 Sep 2025 18:38:42 +0530 Subject: [PATCH 07/11] Apply suggestions from code review Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- .../n1ql-language-reference/using-ai.adoc | 25 ++++++++----------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index eb80eda02..dbd0d9433 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -18,10 +18,9 @@ If the generated statement is a SELECT query, the Query Service automatically ex For all other query types, it returns the generated statement as a string without executing it. However, you can modify this behavior by using the <> option. -IMPORTANT: With the introduction of the USING AI statement, you might notice that AI is now recognized as a keyword. -However, this change has been implemented in a way that does not break existing queries or applications where "ai" is used as a field name or identifier. -For example, queries like `SELECT ai FROM XYZ` will continue to work without any issues. -AI is treated as a keyword only when used in conjunction with the USING AI statement. +IMPORTANT: The word `AI` is recognized as a keyword, but only when used as part of the `USING AI` statement. +When used by itself as a field name or identifier, you do not need to escape the word `AI` by enclosing it in backticks. +For example, in a query like `SELECT ai FROM XYZ`, you can use `ai` as a field name without needing to escape it. == Prerequisites @@ -43,12 +42,12 @@ include::partial$grammar/utility.ebnf[tag=using-ai] image::n1ql-language-reference/using-ai.png["Syntax diagram: refer to source code listing", align=left] prompt:: -[Required] A natural language request that you want to convert into a SQL++ query. +[Required] A natural language request that you want to convert into a {sqlpp} query. options:: [Optional] A JSON object specifying additional <> for the statement. + -By default, the statement uses the xref:n1ql-rest-query:index.adoc#Request[natural_orgid], xref:n1ql-rest-query:index.adoc#Request[natural_cred], and xref:n1ql-rest-query:index.adoc#Request[natural_context] parameters. +By default, the statement uses the xref:n1ql-rest-query:index.adoc#natural_orgid[natural_orgid], xref:n1ql-rest-query:index.adoc#natural_cred[natural_cred], and xref:n1ql-rest-query:index.adoc#natural_context[natural_context] request-level parameters. These parameters determine the organization ID, credentials, and keyspaces for the request. You can override them by specifying the relevant parameters in the <> object. @@ -72,9 +71,9 @@ __optional__ Can be one of the following: * A string in the username:password format. -* An object with the fields `user` and `pass`, similar to the xref:n1ql:n1ql-manage/query-settings.adoc#Credentials[creds] parameter. +* An object with the fields `user` and `pass`, similar to the xref:n1ql:n1ql-manage/query-settings.adoc#Credentials[creds] request-level parameter. -If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_cred] parameter. +If specified, this value overrides the xref:n1ql-rest-query:index.adoc#natural_cred[natural_cred] request-level parameter. To ensure your credentials are passed securely, see <>. @@ -87,10 +86,10 @@ __optional__ Can be one of the following: -* A string matching the xref:n1ql-rest-query:index.adoc#Request[natural_context] specification. +* A string matching the xref:n1ql-rest-query:index.adoc#natural_context[natural_context] specification. * An array of comma-separated strings. -If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_context] parameter. +If specified, this value overrides the xref:n1ql-rest-query:index.adoc#natural_context[natural_context] request-level parameter. | String or an array of strings @@ -99,12 +98,12 @@ __optional__ | Couchbase Capella organization ID for the request. -If specified, this value overrides the xref:n1ql-rest-query:index.adoc#Request[natural_orgid] parameter. +If specified, this value overrides the xref:n1ql-rest-query:index.adoc#natural_orgid[natural_orgid] request-level parameter. To find your organization ID, log in to your Couchbase Capella account and check the URL in your web browser. The organization ID is the `oid` parameter in the URL. -For example, in the URL https://cloud.couchbase.com/databases?oid=5c670d3e-12a3-456b-7c89-123456789ab, the organization ID is `5c670d3e-12a3-456b-7c89-123456789ab`. +For example, in the URL `+++https://cloud.couchbase.com/databases?oid=5c670d3e-12a3-456b-7c89-123456789ab+++`, the organization ID is `5c670d3e-12a3-456b-7c89-123456789ab`. | String @@ -203,7 +202,6 @@ This ensures that the password is not recorded in the shell history. For example: -[source, sh] ---- cbq> \set -natural_cred username@example.com; Enter password for "natural_cred": @@ -222,7 +220,6 @@ cbq> \set; Similarly, if you're sending requests directly to a REST endpoint from a shell, be mindful of how you provide the password and whether it will be recorded in the shell history. Consider using a method like the following to prompt for the password: -[source,console] ---- echo -n "Enter your password: " read -s p From 0a998daa29ca70cbe7b14e25b3530352c526c2c8 Mon Sep 17 00:00:00 2001 From: rakhi-prathap Date: Thu, 25 Sep 2025 14:11:44 +0530 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- .../n1ql-language-reference/using-ai.adoc | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index dbd0d9433..fdfa97a50 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -240,7 +240,7 @@ In the following examples, replace `natural_cred`/`creds` and `natural_orgid`/`o {example-note} .Request -[source, sh] +[source, sqlpp] ---- \set -natural_context travel-sample.inventory.hotel; \set -natural_cred username@example.com:P@ssw0rd; @@ -283,7 +283,7 @@ USING AI How many hotels provide free parking?; {example-note} .Request -[source,sh] +[source,sqlpp] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; @@ -318,7 +318,7 @@ How many airlines are based in United Kingdom?; {example-note} .Request -[source, sh] +[source, sqlpp] ---- USING AI WITH { @@ -362,7 +362,7 @@ List the names of all hotels in the same city as an airport; .USING AI with the Query REST API ==== .Request -[source, console] +[source, sh] ---- echo -n "Enter your password: " read -s p @@ -408,7 +408,7 @@ curl -s -d "natural_cred=username@example.com:${p}" \ {example-note} .Request -[source, sh] +[source, sqlpp] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; @@ -444,12 +444,12 @@ This is because the Query Service executes the generated statement only if it's ==== [[example-6]] -.USING AI with the flex index hint +.USING AI with the Flex Index hint ==== {example-note} .Request -[source, sh] +[source, sqlpp] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 5c670d3e-12a3-456b-7c89-123456789ab; @@ -493,7 +493,7 @@ How many hotels are located in California?; This example uses the same prompt as <>, but specifies the `output` option instead of the `FLEXINDEX` keyword. .Request -[source, sh] +[source, sqlpp] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 5c670d3e-12a3-456b-7c89-123456789ab; @@ -537,7 +537,7 @@ How many hotels are located in California?; {example-note} .Request -[source, sh] +[source, sqlpp] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 5c670d3e-12a3-456b-7c89-123456789ab; @@ -590,7 +590,7 @@ Create a function to list all hotels in California; {example-note} .Request -[source, sh] +[source, sqlpp] ---- \set -natural_cred username@example.com:P@ssw0rd; \set -natural_orgid 7a99d00c-f55b-4b39-bc72-1b4cc68ba894; From e5e3e22f5a3f39386b203a03643816bd0e28e7a2 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 25 Sep 2025 14:31:31 +0530 Subject: [PATCH 09/11] Add related links --- modules/n1ql/pages/n1ql-language-reference/using-ai.adoc | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index fdfa97a50..377f2213c 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -697,4 +697,10 @@ List the names and cities of hotels with a rating greater than 4; } } ---- -==== \ No newline at end of file +==== + +== Related Links + +* xref:cloud:get-started/intro.adoc[Couchbase Capella Operational] +* xref:n1ql-manage/query-settings.adoc#section_nnj_sjk_k1b[Setting Request-Level Parameters] +* xref:n1ql-rest-query:index.adoc[Query Service REST API] From 40b40f3767974493c78eed6fbcb303f664491b83 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 25 Sep 2025 15:27:17 +0530 Subject: [PATCH 10/11] Fix a broken link --- modules/n1ql/pages/n1ql-language-reference/using-ai.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc index 377f2213c..d26d317c2 100644 --- a/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc +++ b/modules/n1ql/pages/n1ql-language-reference/using-ai.adoc @@ -701,6 +701,6 @@ List the names and cities of hotels with a rating greater than 4; == Related Links -* xref:cloud:get-started/intro.adoc[Couchbase Capella Operational] +* xref:cloud:get-started:intro.adoc[Couchbase Capella Operational] * xref:n1ql-manage/query-settings.adoc#section_nnj_sjk_k1b[Setting Request-Level Parameters] * xref:n1ql-rest-query:index.adoc[Query Service REST API] From 184f9b9e298652896cd5a52226f4a66b0a3f4035 Mon Sep 17 00:00:00 2001 From: Rakhi Prathap Date: Thu, 25 Sep 2025 15:45:49 +0530 Subject: [PATCH 11/11] Delete the custom preview.yml file --- preview/DOC-13536-using-ai-from-ui.yml | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 preview/DOC-13536-using-ai-from-ui.yml diff --git a/preview/DOC-13536-using-ai-from-ui.yml b/preview/DOC-13536-using-ai-from-ui.yml deleted file mode 100644 index e16dfcd6a..000000000 --- a/preview/DOC-13536-using-ai-from-ui.yml +++ /dev/null @@ -1,8 +0,0 @@ -sources: - docs-server: - branches: [release/8.0] - cb-swagger: - branches: [release/8.0] - start_path: docs -override: - startPage: server:introduction:intro.adoc