Merge pull request #11088 from mendix/kk-snow-reconcilechanges

Cortex Analyst reconcile changes

Author: katarzyna-koltun-mx

content/en/docs/marketplace/platform-supported-content/modules/snowflake/snowflake-ai-data-connector.md

@@ -36,7 +36,7 @@ The Snowflake AI Data Connector supports the following:
         * [EMBED_TEXT_768](https://docs.snowflake.com/en/sql-reference/functions/embed_text-snowflake-cortex) – Given a piece of text, returns a vector embedding of 768 dimensions that represents that text.
         * [EMBED_TEXT_1024](https://docs.snowflake.com/en/sql-reference/functions/embed_text_1024-snowflake-cortex) – Given a piece of text, returns a vector embedding of 1024 dimensions that represents that text.
 
-    * Use [Snowflake Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) – This Snowflake Cortex feature is used to get information/insights out of structured data sets using natural language instead of sql.
+    * Use [Snowflake Cortex Analyst](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst) – This Snowflake Cortex feature is used to get information/insights out of structured data sets using natural language instead of sql. Cortex Analyst works with semantic models or semantic model views that define how your data should be interpreted.
     * Synchronous execution of calls
     * Query your Cortex Search services
 
@@ -68,13 +68,33 @@ After you install the connector, you can find it in the **App Explorer**, in the
 
 ### Configuring Snowflake Authentication
 
-To use the capabilities of Snowflake in a Mendix app with the Snowflake AI Data Connector, you must use either OAUTH authentication or RSA key-pair authentication.
+To use the capabilities of Snowflake in a Mendix app with the Snowflake AI Data Connector, you must configure one of the supported authentication methods:
+
+* OAuth authentication
+* RSA key-pair authentication (KEYPAIR_JWT)
+* Programmatic Access Token (PAT)
 
 #### Configuring OAUTH Authentication {#setup-OAUTH-snowflake}
 
 To find out how configure the OAUTH Authentication method, see [Role-based Access Control](/appstore/modules/snowflake/snowflake-rbac/).
 
-When using an OAuth token to authenticate REST calls, use the **JWT_GetCreate** microflow from the Utils folder to get or create a JWT object and set your OAuth token and expiration date on the Token and ExpirationDate attributes of the returned JWT object. In the **POST_v1_ExecuteStatement** and **CortexAnalyst** operations, the JWT is retrieved from the **ConnectionDetails** and used for authentication. Be aware that **GET_v1_RetrievePartition** should be edited when using OAuth for authentication. Further instructions on what to change are included in the microflow annotations.
+When using an OAuth token to authenticate REST calls, use the **BearerToken_GetCreate** microflow from the *Utils* folder to get or create a **BearerToken** object. Set your OAuth token and expiration date on the **Token** and **ExpirationDate** attributes of the returned object.
+
+In the **POST_v1_ExecuteStatement** and **CortexAnalyst** operations, the token is retrieved from the **ConnectionDetails** and used for authentication. Be aware that **GET_v1_RetrievePartition** should be edited when using OAuth for authentication. Further instructions on what to change are included in the microflow annotations.
+
+#### Configuring Programmatic Access Token (PAT) Authentication {#setup-pat-snowflake}
+
+You can use Programmatic Access Tokens (PATs) to authenticate Snowflake REST API calls without configuring OAuth or key-pair authentication.
+
+Use the **BearerToken_GetCreate** microflow from the *Utils* folder to get or create a **BearerToken** object. Set the PAT value on the **Token** attribute and configure the **ExpirationDate** according to the lifetime of the token.
+
+The token is retrieved from **ConnectionDetails** during execution of operations such as **POST_v1_ExecuteStatement** and **CortexAnalyst** and is used as a bearer token for Snowflake API authentication.
+
+{{% alert color="info" %}} Snowflake enforces a maximum validity period for authentication tokens. Even if you configure a longer expiration when generating or storing a token, Snowflake will enforce its own upper limit and the token will not remain valid beyond that limit.
+
+Because this limit is defined by Snowflake and may change over time, you should always verify the current maximum supported token lifetime in the official Snowflake documentation. For more information, see the Snowflake documentation on [Authenticating to the SQL API](https://docs.snowflake.com/en/developer-guide/sql-api/authenticating). {{% /alert %}}
+
+When configuring the **ExpirationDate** of a **BearerToken**, make sure it aligns with the token lifetime supported by Snowflake to avoid authentication failures caused by expired tokens.
 
 #### Configuring Key-Pair Authentication in Snowflake {#setup-key-pair-snowflake}
 
@@ -233,7 +253,7 @@ Activities define the actions that are executed in a microflow or a nanoflow.
 
 #### ExecuteStatement {#execute-statement}
 
-The `ExecuteStatement` activity allows you to execute a command in Snowflake using the SQL statement and the configuration details given in a `Statement` and `ConfigurationDetails` objects and returns a list of `HttpResponse` objects. Make sure that a JWT object containing your KEYPAIR_JWT or OAuth token is associated to your connection details before using the `ExecuteStatement` activity.
+The `ExecuteStatement` activity allows you to execute a command in Snowflake using the SQL statement and the configuration details provided in the `Statement` and `ConnectionDetails` objects. The activity returns a list of `HttpResponse` objects. Make sure that a `BearerToken` object containing your KEYPAIR_JWT, OAuth token, or Programmatic Access Token (PAT) is associated with your `ConnectionDetails`.
 
 The input and output for this service are shown in the table below:
 
@@ -285,24 +305,41 @@ This statement returns data from a Snowflake table with the columns named as spe
 [Snowflake Cortex Analyst](/appstore/modules/genai/snowflake-cortex/) is a fully-managed, LLM-powered Snowflake Cortex feature that helps you create applications capable of reliably answering business questions based on your structured data in Snowflake.
 
 {{% alert color="info" %}}
-Snowflake Cortex Analyst is currently in open preview. For more information, refer to the [Snowflake Cortex Analyst documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst).
+Snowflake Cortex Analyst is now generally available. For more information, refer to the [Snowflake Cortex Analyst documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst).
 {{% /alert %}}
 
 ### Prerequisites
 
 * Make sure that you have access to Cortex Analyst. For more information, refer to the [Snowflake Cortex Analyst documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst).
-* Create the semantic model for Cortex Analyst. For more information, refer to [Creating Semantic Models for Snowflake Cortex Analyst](https://developers.snowflake.com/solution/creating-semantic-models-for-snowflakes-cortex-analyst/) in the Snowflake Cortex Analyst documentation.
+* Create a semantic model, semantic model view, or inline semantic model for Cortex Analyst. For more information, refer to:
+  * [Creating Semantic Models for Snowflake Cortex Analyst](https://developers.snowflake.com/solution/creating-semantic-models-for-snowflakes-cortex-analyst/)
+  * [Using Semantic Model Views](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst#understanding-semantic-views)
 * Set up one of the following supported authentication methods for Cortex Analyst:
     * OAUTH
     * KEYPAIR_JWT
+    * PAT (Programmatic Access Token)
 
 ### Configuration 
 
 To configure your Mendix app for Snowflake Cortex Analyst, perform the following steps:
 
 1. Create a microflow and retrieve your **ConnectionDetails** object.
-2. When using KEYPAIR_JWT as your authentication type use the **Generate JWT** action from the **Toolbox** to generate a JWT object. When using OAuth as authentication type please use the **Get or Create JWT** action from the **Toolbox** to create a JWT object and set your OAuth token and expiration date on that object.
-3. Add the **Cortex Analyst: Create Request** action from the **Toolbox**, and then configure the **Request** to contain the path to the Snowflake semantic model file and your question/prompt for the model.
+2. Configure authentication based on the authentication type set in **ConnectionDetails**:
+   * When using **KEYPAIR_JWT**, use the **Generate JWT** action from the **Toolbox** to generate a JWT token.
+   * When using **OAuth** or **PAT**, use the **BearerToken_GetCreate** microflow from the **Utils** folder to get or create a **BearerToken** object. Set the **Token** and **ExpirationDate** attributes accordingly.
+3. Add the **Cortex Analyst: Create Request** action from the **Toolbox**, and configure the **Request**.
+   The request is based on the **AbstractCortexAnalystRequest** entity, which has two implementations depending on whether you want to use a single semantic model or multiple models:
+
+   * **CortexAnalystRequest** – Use this for single-model requests. Configure one of the following attributes:
+     * **Semantic_Model_File** – Provide the path to a semantic model YAML file stored in Snowflake.
+     * **Semantic_View** – Provide the name of the semantic model view that Cortex Analyst should use. For more information, refer to the [Using Semantic Model Views](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst#understanding-semantic-views) section of the Snowflake documentation.
+     * **Semantic_Model** – Provide the semantic model definition as a YAML string. This allows you to define the semantic model inline instead of uploading it to Snowflake.
+   * **CortexAnalystMultiModelRequest** – Use this when working with multiple semantic models. This allows Cortex Analyst to select the most relevant model when answering a question.
+     Each **SemanticModel** object can contain one of the following:
+     * **Semantic_Model_File** – Provide the path to a semantic model YAML file stored in Snowflake.
+     * **Semantic_View** – Provide the name of the semantic model view that Cortex Analyst should use. For more information, refer to the [Using Semantic Model Views](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-analyst#understanding-semantic-views) section of the Snowflake documentation.
+     * **Inline_Semantic_Model** – Provide the semantic model definition as a YAML string. This allows you to define the semantic model inline instead of uploading it to Snowflake.
+   The user prompt is stored in the **CortexAnalystMessage** object. Set the question for Cortex Analyst in the **Content** attribute of this entity.
 4. Add the **Snowflake Cortex Analyst** action from the Toolbox and provide the following information:
     * **ConnectionDetails** – The connection details that you configured
     * **Request** – The request that you configured for the **Cortex Analyst: Create Request** action
@@ -312,8 +349,6 @@ To configure your Mendix app for Snowflake Cortex Analyst, perform the following
     * **SQLText** – The returned SQL suggestion
 6. To get the Cortex Analyst Response entity, add the **Response: Get Cortex Analyst Response** action from the Toolbox, and then add the **Response** entity as a parameter. The response contains the following information:
     * **Request_ID** – The returned *RequestId*
-   
- {{< figure src="/attachments/appstore/platform-supported-content/modules/snowflake-ai-data-connector/CortexAnalystRequestExample.png" >}}
 
 ## Configuring Snowflake Cortex Search {#cortex-search}
 
@@ -323,16 +358,19 @@ Snowflake Cortex Search is a fully-managed, ML-powered Snowflake Cortex feature
 
 * Make sure that you have access to Cortex Search. For more information, refer to the [Snowflake Cortex Search documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview).
 * Create the Cortex Search service. For more information, refer to [Creating Snowflake Cortex Search service](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview#create-the-service) in the Snowflake Cortex Search documentation.
-* Set up one of the following supported authentication methods for Cortex Analyst:
+* Set up one of the following supported authentication methods for Cortex Search:
     * OAUTH
     * KEYPAIR_JWT
+    * PAT (Programmatic Access Token)
 
 ### Configuration 
 
 To configure your Mendix app for Snowflake Cortex Search, perform the following steps:
 
 1. Create a microflow and retrieve your **ConnectionDetails** object.
-2. When using KEYPAIR_JWT as your authentication type use the **Generate JWT** action from the **Toolbox** to generate a JWT object. When using OAuth as authentication type please use the **Get or Create JWT** action from the **Toolbox** to create a JWT object and set your OAuth token and expiration date on that object.
+2. Configure authentication based on the authentication type set in **ConnectionDetails**:
+   * When using **KEYPAIR_JWT**, use the **Generate JWT** action from the **Toolbox** to generate a JWT token.
+   * When using **OAuth** or **PAT**, use the **BearerToken_GetCreate** microflow from the **Utils** folder to get or create a **BearerToken** object. Set the **Token** and **ExpirationDate** attributes accordingly.
 3. Create a **CortexSearchRequest** object, and then configure the **Request** to contain the path to the Snowflake Cortex Search service, your query/prompt for the model and what indexed columns the Cortex Search service should return.
 4. Add the **Snowflake Cortex Search** action from the Toolbox and provide the following information:
     * **ConnectionDetails** – The connection details that you configured