[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:
@@ -66,7 +69,7 @@ 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:
 
@@ -75,6 +78,8 @@ Can be one of the following:
 
 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>>.
 
 | String or object
@@ -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,21 @@ 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-rest-query:index.adoc[Query Service REST API]