[DOC-13706] USING AI Limitations

modules/n1ql/pages/n1ql-language-reference/using-ai.adoc

@@ -22,6 +22,9 @@ IMPORTANT: The word `AI` is recognized as a keyword, but only when used as part
 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.
 
+CAUTION: If you're using the USING AI statement on Couchbase Capella, we recommend that you use either the cbq shell or an SDK.
+For more information about these limitations and workarounds, see <<using-ai-limitations>>.
+
 == Prerequisites
 
 Before using the USING AI statement, make sure you have:
@@ -47,7 +50,7 @@ prompt::
 options::
 [Optional] A JSON object specifying additional <<optional-parameters,options>> for the statement.
 +
-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.
+By default, the statement uses the xref:n1ql:n1ql-manage/query-settings.adoc#natural_orgid[natural_orgid], xref:n1ql:n1ql-manage/query-settings.adoc#natural_cred[natural_cred], and xref:n1ql:n1ql-manage/query-settings.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 <<optional-parameters,options>> object.
 
@@ -66,14 +69,16 @@ See <<example-6>>.
 
 | **creds** +
 __optional__
-| Couchbase Capella credentials to authenticate the request.
+| Couchbase Capella account credentials to authenticate the request. 
 
 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] request-level parameter.
+* A string in the `username`:`password` format. 
+* An object with the fields `user` and `pass`.
+
+If specified, this value overrides the xref:n1ql:n1ql-manage/query-settings.adoc#natural_cred[natural_cred] request-level parameter.
 
-If specified, this value overrides the xref:n1ql-rest-query:index.adoc#natural_cred[natural_cred] request-level parameter.
+This parameter does not support Single Sign-On (SSO), Multi-Factor Authentication (MFA), or social login credentials (such as Google or GitHub).
 
 To ensure your credentials are passed securely, see <<handling-passwords, Handling Passwords>>.
 
@@ -86,10 +91,10 @@ __optional__
 
 Can be one of the following:
 
-* A string matching the xref:n1ql-rest-query:index.adoc#natural_context[natural_context] specification. 
+* A string matching the xref:n1ql:n1ql-manage/query-settings.adoc#natural_context[natural_context] specification. 
 * An array of comma-separated strings.
 
-If specified, this value overrides the xref:n1ql-rest-query:index.adoc#natural_context[natural_context] request-level parameter.
+If specified, this value overrides the xref:n1ql:n1ql-manage/query-settings.adoc#natural_context[natural_context] request-level parameter.
 
 | String or an array of strings 
 
@@ -98,7 +103,7 @@ __optional__
 
 | Couchbase Capella organization ID for the request.
 
-If specified, this value overrides the xref:n1ql-rest-query:index.adoc#natural_orgid[natural_orgid] request-level parameter.
+If specified, this value overrides the xref:n1ql:n1ql-manage/query-settings.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.
@@ -169,13 +174,13 @@ You can provide these details in two ways:
 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 the cbq shell, you can set these parameters using the `\set` command. 
+For example, in the cbq shell, you can set these parameters using the `\set` command. 
 See <<example-1>>.
-* 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].
+// Commenting out the following lines for now as the statement does not work on the Capella UI. 
+// In the Query Workbench, you can set these parameters in the xref:tools:query-workbench.adoc#query-preferences[Query Settings] 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 do not need to specify `creds`, `orgId`, or `keyspaces` in the WITH clause.
 
@@ -699,8 +704,20 @@ List the names and cities of hotels with a rating greater than 4;
 ----
 ====
 
+[[using-ai-limitations]]
+== Limitations 
+
+When using the statement, consider the following:
+
+* To run the statement on Capella, use either the cbq shell or an SDK.
+The statement does not function as expected when executed directly through the Capella UI (Query Workbench).
+* For similar functionality within the Capella UI, use xref:get-started:capella-iq/work-with-capellaiq.adoc[Capella iQ] instead.
+* You cannot use the `creds` and `natural_cred` parameters with the following types of credentials:
+** Single Sign-On (SSO)
+** Multi-Factor Authentication (MFA)
+** Social logins (such as Google or GitHub)
+
 == 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]
+* xref:n1ql-manage/query-settings.adoc#section_nnj_sjk_k1b[Setting Request-Level Parameters]