> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview.md). # Snowflake Integration Reference Guide {% hint style="info" %} **Preview documentation for upcoming feature** This page currently reflects the new Snowflake connections that users will see in future updates. {% endhint %} Using the Snowflake connection, you can register a Snowflake integration for your Snowflake Enterprise account. The sequence diagram below outlines the events that occur when an Immuta user wants to query a Snowflake table that has been registered as an Immuta data source.
## What does Immuta do in my environment? ### Registering a connection Immuta utilizes [connections](/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview/new-connections-reference-guide.md) to register and manage data from your entire Snowflake environment all at once. This approach simplifies data registration and allows Immuta to automatically monitor your Snowflake platform for changes. Data sources are then added or removed to reflect the current state of your data platform. When a [connection is first registered](/saas/configuration/integrations/snowflake/how-to-guides/connect-snowflake.md), Immuta will ask your application admin to provide the following: * The name of an **Immuta system database** in Snowflake that Immuta will control and create schemas (`immuta_procedures`, `immuta_policies`, and `immuta_functions`) in to contain policy definitions and user entitlements. This database will be created when you run the setup script. * A **Snowflake role** with the required privileges that the system account will use to maintain state of data objects between Snowflake and Immuta. * A **set of Snowflake credentials to a system account** with the [required privileges](/saas/configuration/integrations/snowflake/how-to-guides/connect-snowflake.md#set-up-the-immuta-system-account) to connect between Snowflake and Immuta. These credentials will be used to initially register all your [Snowflake objects](#supported-object-types) as data objects. Immuta will also continue to use those credentials for scheduled [object syncs](/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview/new-connections-reference-guide.md#object-sync), [identification](/saas/configuration/tags/data-discovery.md), and to orchestrate policies in Snowflake. The application admin will then run the setup script in Snowflake, which will create the following: * The **new Immuta system database** to contain policy definitions and user entitlements. * A **new system Snowflake role** to orchestrate policies in Snowflake, which will be attached to the Snowflake system account. When policies are applied to Snowflake objects, the following will be done in your Snowflake environment: * Subscription policies will require **a new role to be created for each user**, which will be granted access to the object in Snowflake. The role prefix is set on the [Immuta app settings page](/saas/configuration/application-configuration/how-to-guides/config-builder-guide.md#global-integration-settings). For example, if the user is `jane.doe@immuta.com` and if the role prefix is set to `IMMUTA`, the role will be `IMMUTA_USER_jane.doe@immuta.com` and granted access to the table. * Data policies will require **Immuta to manage and apply** [**Snowflake governance column**](https://docs.snowflake.com/en/user-guide/security-column.html) **and** [**row access policies**](https://docs.snowflake.com/en/user-guide/security-row.html) **to Snowflake objects** that are registered as Immuta data sources using the system Snowflake account and role. After the setup and registration is complete, Immuta ingests and stores connection metadata in the Immuta metadata database. In the example below, the Immuta application administrator connects the database that contains `marketing-data`, `research-data`, and `cs-data` tables. Immuta registers these tables as data objects and stores the table metadata in the Immuta metadata database. Creating the connection does not impact any user's existing access in Snowflake until subscription policies are applied to the tables.
Beyond making the registration of your data more intuitive, connections provide more control. Instead of performing operations on individual schemas or tables, you can perform operations (such as object sync) at the connection level. See the [Connections reference guide](/saas/configuration/integrations/data-and-integrations/registering-a-connection/reference-guides/connections-overview/new-connections-reference-guide.md) for details about connections and how to manage them. To configure your Snowflake connection, see the [Register a Snowflake connection guide](/saas/configuration/integrations/snowflake/how-to-guides/connect-snowflake.md). ### Applying policies By default, the Snowflake integration is designed to be minimally invasive: if a table does not have policy sync enabled, users will still have access to it in Snowflake. #### Subscription policies Immuta enforces read and write [subscription policies](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-policies.md) on Snowflake tables by granting access to the appropriate tables in Snowflake. Once the connection is registered, this is what happens when a user applies a subscription policy to a Snowflake data source: 1. Immuta creates a role for the user querying the table in Snowflake, if one doesn't already exist. The role will be `_USER_`. 2. Snowflake stores that role in its internal system catalog. 3. Immuta issues grants to that user's role in Snowflake to enforce policy. The [Protecting data page](/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview/protecting-data.md) provides an example of this policy enforcement. 4. Immuta will then grant that personalized role to the Immuta user in Snowflake. The [Accessing data page](/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview/accessing-data.md) provides details about how the user should set their Snowflake roles. 5. Users will query data in Snowflake, using [`USE SECONDARY ROLES ALL`](https://docs.snowflake.com/en/sql-reference/sql/use-secondary-roles.html#syntax), which allows them to use the privileges from all roles that have been granted to them including the `_USER_` role and their current active primary role. #### Data policies You can author [data policies](/saas/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/data-policies.md) in Immuta to enforce fine-grained access controls on Snowflake data objects registered as Immuta data sources. For more details about how enforcement works, see the [Protecting data page](/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview/protecting-data.md). When a data policy is applied to a Snowflake data source in Immuta, 1. A data owner, data governor, or administrator [creates or changes a policy](/saas/govern/secure-your-data/authoring-policies-in-secure/data-policies/how-to-guides/data-policy-tutorial.md) or a [user's attributes change](/saas/configuration/people/users-index/how-to-guides/managing-attribute-and-group.md) in Immuta. 2. Immuta manages and applies [Snowflake governance column](https://docs.snowflake.com/en/user-guide/security-column.html) and [row access policies](https://docs.snowflake.com/en/user-guide/security-row.html) to Snowflake tables that are registered as Immuta data sources using the system Snowflake account and role. 3. A Snowflake user who is subscribed to the data source in Immuta queries the corresponding table directly in Snowflake and sees policy-enforced data. See the integration support matrix on the [Data policy types reference guide](/saas/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/data-policies.md#data-policy-support-matrix) for a list of supported data policy types in Snowflake. #### **Snowflake privileges granted by Immuta** See the [Subscription policy access types page](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-access-types.md#granting-snowflake-privileges) for details about the Snowflake privileges granted to users when they are subscribed to a data source protected by a subscription policy. ### Required Snowflake privileges The privileges the Snowflake integration requires align to the least privilege security principle. The table below describes each privilege required in Snowflake for the [setup user](#user-content-fn-1)[^1] or the [system account user](#user-content-fn-2)[^2]. The references to `IMMUTA_DB` , `IMMUTA_WH`, and `IMMUTA_IMPERSONATOR_ROLE` in the table can be replaced with what you chose for the name of your Immuta database, warehouse, and impersonation role when setting up the integration, respectively. | Snowflake privilege | User requiring privilege | Features | Explanation | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CREATE DATABASE ON ACCOUNT WITH GRANT OPTION` | Setup user | All | The setup script this user runs creates an Immuta database in your organization's Snowflake account where all Immuta managed objects (UDFs, masking policies, row access policies, and user entitlements) will be written and stored. | | `CREATE ROLE ON ACCOUNT WITH GRANT OPTION` | Setup user | All | The setup user must create a `ROLE` for Immuta that will be used to manage the integration and policies once it has been initialized. | | `MANAGE GRANTS ON ACCOUNT` | Setup user | All | The user registering the connection must be able to `GRANT` global privileges and access to objects within the Snowflake account. All privileges that are documented here must be granted to the system account user by the setup user manually or through the setup script. | |
  • ALL PRIVILEGES ON DATABASE IMMUTA\_DB
  • ALL PRIVILEGES ON ALL SCHEMAS IN DATABASE IMMUTA\_DB
  • USAGE ON FUTURE PROCEDURES IN SCHEMA IMMUTA\_DB.IMMUTA\_PROCEDURES
| System account user | All | Immuta requires these privileges because Immuta must have full ownership of the Immuta database where Immuta objects are managed. | | `USAGE ON WAREHOUSE IMMUTA_WH` | System account user | All | To make changes to state in the Immuta database, Immuta requires access to compute (a Snowflake warehouse). Some state changes are DDL operations, and others are DML and require compute. | | `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` | System account user | Audit | To ingest audit information from Snowflake, Immuta must have access to the `SNOWFLAKE.ACCOUNT_USAGE.ACCESS_HISTORY` view. See the [Snowflake documentation](https://docs.snowflake.com/en/sql-reference/account-usage/access_history) for details. | |
  • APPLY MASKING POLICY ON ACCOUNT
  • APPLY ROW ACCESS POLICY ON ACCOUNT
| System account user | Data policies | Immuta must be able to apply policies to objects throughout your organization's Snowflake account and query for existing policies on objects using the `POLICY_REFERENCES` [table function](https://docs.snowflake.com/en/sql-reference/functions/policy_references.html). | | `SELECT` on all tables and views registered in Immuta | System account user | Identification and specialized masking policies that require fingerprinting | Immuta must have this privilege to run the necessary queries for [identification](/saas/configuration/tags/data-discovery.md) on your data sources. | | `OWNERSHIP ON ROLE IMMUTA_IMPERSONATOR_ROLE` | System account user | Impersonation | If impersonation is enabled, Immuta must be able to manage the Snowflake roles used for impersonation in order to manage the impersonation feature. | |
  • USAGE on all databases and schemas with registered data sources
  • REFERENCES on all tables and views registered in Immuta
| System account user | Object sync | Immuta must be able to see metadata on securables to register them as data sources. | | `MANAGE GRANTS ON ACCOUNT` | System account user | Subscription policies | Immuta must be able to `MANAGE GRANTS` on objects throughout your organization's Snowflake account. | | `CREATE ROLE ON ACCOUNT` | System account user | Subscription policies | Immuta must be able to create roles as targets for Immuta subscription policy permissions in your organization’s Snowflake account. | | `APPLY TAG ON ACCOUNT` | System account user | Tag ingestion | To ingest table, view, and column tag information from Snowflake, Immuta must have this permission. Immuta reads from the `TAG_REFERENCES` [table function](https://docs.snowflake.com/en/sql-reference/functions/tag_references.html). | | `IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE` | System account user | Tag ingestion | To ingest table, view, and column tag information from Snowflake, Immuta must have access to the `SNOWFLAKE.ACCOUNT_USAGE.ACCESS_HISTORY` view. See the [Snowflake documentation](https://docs.snowflake.com/en/sql-reference/account-usage/access_history) for details. | |
  • USAGE ON DATABASE IMMUTA\_DB
  • USAGE ON SCHEMA IMMUTA\_DB.IMMUTA\_PROCEDURES
  • USAGE ON SCHEMA IMMUTA\_DB.IMMUTA\_FUNCTIONS
  • USAGE ON FUTURE FUNCTIONS IN SCHEMA IMMUTA\_DB.IMMUTA\_FUNCTIONS
  • USAGE ON SCHEMA IMMUTA\_DB.IMMUTA\_SYSTEM
  • SELECT ON IMMUTA\_DB.IMMUTA\_SYSTEM.USER\_PROFILE
| `PUBLIC` role | All | Immuta has stored procedures and functions that are used for policy enforcement and do not expose or contain any sensitive information. These objects must be accessible by all users to facilitate the use and creation of policies or views to enforce Immuta policies in Snowflake. | | `SELECT ON IMMUTA_DB.IMMUTA_SYSTEM.ALLOW_LIST` | `PUBLIC` role | All | Immuta retains a list of excepted roles and users when using the Snowflake integration. The roles and users in this list will be exempt from policies applied to tables in Snowflake to give organizations flexibility in case there are entities that should not be bound to Immuta policies in Snowflake (for example, a system or application role or user). | #### Maintaining state with Snowflake The following user actions spur various processes in the Snowflake integration so that Immuta data remains synchronous with data in Snowflake. The list below provides an overview of each process: * **Data source created**: Immuta registers data source metadata and stores that metadata in the Immuta metadata database. * [**User account is mapped to Immuta**](#user-registration-and-id-mapping): When a user account is mapped to Immuta, their metadata is stored in the metadata database. * **User subscribed to a data source**: When a user is added to a data source by a data owner or through a subscription policy, Immuta creates a role for that user (if a role for them does not already exist) and grants Snowflake privileges to their role. * **Automatic subscription policy applied to or updated on a data source**: Immuta calculates the users and data sources affected by the policy change and grants or revokes users' privileges on the Snowflake object. See the [Protecting data page](/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview/protecting-data.md) for details about this process. * **Subscription policy deleted**: Immuta revokes privileges from the affected roles. * **Data policy created or updated**: Snowflake row access policies and column masking policies are applied to the Snowflake object to reflect the Immuta policy. See the [Protecting data page](/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview/protecting-data.md) for details about this process. * **Data policy deleted**: Immuta removes the policy from the Snowflake object. * **User removed from a data source**: Immuta revokes privileges from the user's role. ### Supported object types | Object type | Subscription policy support | Data policy support | Request app support | | ----------------- | --------------------------- | -------------------- | -------------------- | | Table | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | View | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | Materialized view | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | External table | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | Event table | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | Iceberg table | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | | Dynamic table | :white\_check\_mark: | :white\_check\_mark: | :white\_check\_mark: | ## Supported policies The Snowflake integration allows users to author subscription and data policies to enforce access controls. See the corresponding pages for details about specific types of policies supported: * [Subscription policy access types](/saas/govern/secure-your-data/authoring-policies-in-secure/section-contents/reference-guides/subscription-access-types.md#granting-snowflake-privileges) * [Data policy types](/saas/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/data-policies.md#data-policy-support-matrix) ## Supported Snowflake features The Immuta Snowflake integration supports the following Snowflake features. * [Private connectivity for Snowflake](/saas/configuration/application-configuration/how-to-guides/private-networking-support/data-connection-private-networking/index-1.md): While Immuta does not persist any of your data, [data is temporarily held in memory in some instances](/saas/configuration/application-configuration/reference-guides/index.md#sample-raw-data), like when a user generates a data source fingerprint. This data is encrypted using TLS from the data source to Immuta as it traverses the public internet. Alternatively, Immuta can be connected to a user's Snowflake account over either AWS PrivateLink or Azure Private Link so that any data moving between the user's data source and the Immuta tenant is over a private network. * [Snowflake external tables](https://docs.snowflake.com/en/user-guide/tables-external-intro.html): However, you cannot add a masking policy to an external table column while creating the external table in Snowflake because masking policies cannot be attached to virtual columns. ## Security and compliance ### Authentication methods The Snowflake integration supports the following authentication methods to register a connection. The credentials provided must be for an account with the permissions listed in the [Register a Snowflake connection guide](/saas/configuration/integrations/snowflake/how-to-guides/connect-snowflake.md#set-up-the-immuta-system-account). * **Username and password**: Users can authenticate with their Snowflake username and password. * **Key pair**: Users can authenticate with a [Snowflake key pair authentication](https://docs.snowflake.com/en/user-guide/key-pair-auth.html#key-pair-authentication-key-pair-rotation). * **Snowflake External OAuth**: Users can authenticate with [Snowflake External OAuth](https://docs.snowflake.com/en/user-guide/oauth-intro.html). For more information about this authentication option, see the [Security and compliance guide](/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview/security-and-compliance.md#snowflake-external-oauth). ### User registration and ID mapping The built-in Immuta IAM can be used as a complete solution for authentication and user entitlement. However, you can connect your existing identity management provider to Immuta to use that system for authentication and user entitlement instead. Each of the [supported IAM protocols](/saas/releases/support-matrix.md#external-iams) includes a set of configuration options that enable Immuta to communicate with the IAM system and map the users, permissions, groups, and attributes into Immuta. For policies to impact the right users, the user account in Immuta must be mapped to the user account in Snowflake. You can ensure these accounts are mapped correctly in the following ways: * [Automatically](/saas/configuration/people/users-index/how-to-guides/external-user-mapping.md#configure-external-user-id-mapping-on-app-settings-page): If usernames in Snowflake align with usernames in the external IAM and those accounts align with an IAM attribute, you can enter that IAM attribute on the app settings page to automatically map user IDs in Immuta to Snowflake. * [Manually](/saas/configuration/people/users-index/how-to-guides/external-user-mapping.md#manually-configure-external-user-id-mapping-on-a-users-page): You can manually map user IDs for individual users. For guidance on connecting your IAM to Immuta, see the [how-to guide for your protocol](/saas/configuration/people/section-contents.md#how-to-guides). ### Excepted roles/users Excepted roles and users are assigned when the connection is registered, and no policies will apply to these users' queries, despite any Immuta policies enforced on the tables they are querying. Consequently, roles and users added to this list should be limited to service accounts. #### How do excepted roles/users work? Immuta excludes the listed roles and users from policies by wrapping all policies in a `CASE` statement that will check if a user is acting under one of the listed usernames or roles. If a user is on the list, then the policy will not be acted on the queried table. If the user is not, then the policy will be executed like normal. Immuta does not distinguish between role and username, so if you have a role and user with the exact same name, both the user and any user acting under that role will have full access to the data sources and no policies will be enforced for them. #### When should you use excepted roles/users? * Add **service accounts** to the excepted roles/users list so that Immuta subscription and data policies will not unintentionally impact their jobs. * When using both tables and their views as data sources, add **the owner of the view** in Snowflake as an excepted role/user. Otherwise, the backing table's policies will be applied to that view. ### Tag ingestion You can enable Snowflake tag ingestion so that Immuta will ingest Snowflake object tags from your Snowflake instance into Immuta and add them to the appropriate data sources. The Snowflake tags' key and value pairs will be reflected in Immuta as two levels: the key will be the top level and the value the second. As Snowflake tags are hierarchical, Snowflake tags applied to a database will also be applied to all of the schemas in that database, all of the tables within those schemas, and all of the columns within those tables. For example: If a database is tagged `PII`, all of the tables and columns in that database will also be tagged `PII`. Snowflake tag ingestion supports two authentication methods: * **Username and password** * **Key pair** To enable Snowflake tag ingestion, see the [Enable Snowflake tag ingestion page](/saas/configuration/integrations/snowflake/how-to-guides/enable-snowflake-tag-ingestion-1.md). **Credentials** If you want all Snowflake data sources to have Snowflake data tags ingested into Immuta, ensure the credentials provided on the [Immuta app settings page](/saas/configuration/integrations/snowflake/how-to-guides/enable-snowflake-tag-ingestion-1.md) for the external catalog feature can access all the data sources registered in Immuta. Any data sources the credentials do not have access to will not be tagged in Immuta. In practice, it is recommended to just **use the same credentials for the** [**connection**](/saas/configuration/integrations/snowflake/how-to-guides/connect-snowflake.md) **and tag ingestion**. **Caveats** Snowflake has some [natural data latency](https://docs.snowflake.com/en/sql-reference/account-usage.html#data-latency). If you manually refresh the governance page to see all tags created globally, users can experience a delay of up to two hours. However, if you run object sync or a health check to find where those tags are applied, the delay will not occur because Immuta will only refresh tags for those specific tables. ### Limitations and known issues * Snowflake workspaces are deprecated and are not supported with Snowflake table grants enabled, which is the default for all new connections. * If there are errors in generating or applying policies natively in Snowflake, the data source will be locked and only users on the [excepted roles/users list](#excepted-roles-users) and the credentials used to register the connection will be able to access the data. * Once a Snowflake connection is deactivated in Immuta, the user must remove the access that was granted in Snowflake. If that access is not revoked, users will be able to access the raw table in Snowflake. * When configuring one Snowflake instance with multiple Immuta tenants, the Snowflake system account for the connection must be unique in each Immuta tenant. * You cannot add a masking policy to an external table column while creating the external table because a masking policy cannot be attached to a virtual column. * If you create an Immuta data source from a Snowflake view created using a `select * from` query, Immuta cannot get the column metadata because [Snowflake views are not automatically updated based on backing table changes](https://docs.snowflake.com/en/sql-reference/sql/create-view.html#usage-notes). To remedy this, you can create views that have the specific columns you want or you can `CREATE AND REPLACE` the view in Snowflake whenever the backing table is updated and manually run the object sync job on the data source page. * If a user is created in Snowflake after that user is already registered in Immuta, Immuta does not grant usage on the per-user role automatically - meaning Immuta does not govern this user's access without manual intervention. If a Snowflake user is created after that user is registered in Immuta, the user account must be [disabled](/saas/configuration/people/users-index/how-to-guides/managing-personas-and-permissions.md#disable-users) and re-enabled to trigger a sync of Immuta policies to govern that user. Whenever possible, Snowflake users should be created before registering those users in Immuta. * Snowflake tables from imported databases are not supported. Instead, create a view of the table and register that view as a data source. * Data sources created from connections cannot be deleted. To remove the Immuta-applied policies from a Snowflake table, remove the policies from the data source, then disable it. To remove the Immuta-managed policies from all Snowflake tables, deactivate the connection. **Custom WHERE clause limitations** The Immuta Snowflake integration uses Snowflake governance features to let users query data natively in Snowflake. This means that Immuta also inherits some Snowflake limitations using correlated subqueries with [row access policies](https://docs.snowflake.com/en/user-guide/security-row-intro.html#considerations) and [column-level security](https://docs.snowflake.com/en/user-guide/security-column-intro.html#limitations). These limitations appear when writing [custom WHERE policies](/saas/govern/secure-your-data/authoring-policies-in-secure/data-policies/reference-guides/custom-where-clause-functions.md), but do not remove the utility of row-level policies. **Requirement for a custom WHERE policy**: The Immuta system account must have `SELECT` privileges on all tables/views referenced in a subquery via the system Snowflake role created by the setup script. Reach out to your Immuta support professional if you do not know the role to grant privileges to. **Subquery limitations** **Any subqueries that error in Snowflake will also error in Immuta.** 1. Including one or more subqueries in the Immuta policy condition may cause errors in Snowflake. If an error occurs, it may happen during policy creation or at query-time. To avoid these errors, limit the number of subqueries, limit the number of JOIN operations, and simplify WHERE clause conditions. 2. For more information on the Snowflake subquery limitations see * ​[Understanding column-level security](https://docs.snowflake.com/en/user-guide/security-column-intro.html#limitations)​ * ​[Understanding row access policies](https://docs.snowflake.com/en/user-guide/security-row-intro.html#considerations) [^1]: The user registering the Snowflake connection. [^2]: This system account is used by Immuta to manage the Snowflake integration once it has been set up. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.immuta.com/saas/configuration/integrations/snowflake/reference-guides/snowflake-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.